uv-pep440 版本解析演进史：从公开 crate 到 uv 内部组件的 PEP 440 实现

本文以 crates/uv-pep440/CHANGELOG.md 为主线，梳理 uv 中负责 PEP 440 版本解析与版本约束（version specifier）匹配的 uv-pep440 crate 从 0.2.0 到 0.7 的完整演进历程，并结合当前仓库源码（version.rs、version_specifier.rs）印证每次变更在现实现中的落点，帮助你理解 uv 为什么能高速完成版本解析、比较与约束匹配。

一、crate 定位：从独立发布 crate 演变为 uv 内部组件

uv-pep440 实现了 PEP 440 定义的版本号与版本约束语法。它在历史上是一个公开发布的独立 crate（早期名为 pep440-rs），Changelog 记录了它 0.2.0 至 0.7 的公开版本线；而在当前 uv 仓库中，它已成为 uv 的内部组件 crate：

• Cargo.toml 中 version = "0.0.74"，描述为 "This is an internal component crate of uv"；
• README.md 明确声明 "This crate is an internal component of uv. The Rust API exposed here is unstable and will have frequent breaking changes"，并注明 0.0.74 是 uv 0.12.7 的组成部分；
• Cargo.toml 保留了 serde = [] feature，注释为 "Match the API of the published crate, for compatibility"——这是公开发布 API 在内部化之后留下的兼容性痕迹。

理解这一背景很重要：Changelog 中的 0.7 及以前版本描述的是"公开 crate 时代"的演进，而当前仓库中的代码是在 0.7 基础上的持续内部迭代（内部版本号重置为 0.0.x），因此下文每一节都会把 Changelog 条目与当前源码对应起来。

二、0.2.0 ～ 0.3.x：奠定 API 基础与 Python 绑定层

2.1 0.2.0：引入 VersionSpecifiers 聚合类型

Changelog 0.2.0 记录了两个关键变化：

1. 新增 VersionSpecifiers，一个围绕 Vec<VersionSpecifier> 的薄封装，带 serde 实现；VersionSpecifiers::from_str 取代了旧的 parse_version_specifiers 自由函数成为推荐入口；
2. 为 Python 模块 re-export Rust 函数。

当前源码中该类型依然存在，见 version_specifier.rs#L30-L44：

pub struct VersionSpecifiers(Box<[VersionSpecifier]>);

内部实现已从 Vec 换成 Box<[_]> 以省去容量字段；解析后还会按版本、再按操作符排序（from_unsorted，version_specifier.rs#L68-L80），使 >=1.4.4,<=1.4.4 与 <=1.4.4,>=1.4.4 这类语义等价的约束归一化为同一表示。

2.2 0.3.0 ～ 0.3.12：Python 绑定层的逐步打磨

这一阶段的 Changelog 条目几乎全部围绕 pyo3 绑定：

版本	变更	说明
0.3.0	引入 PyVersion 包装类型	专门用于 Python 绑定，用于绕过 pyo3 上游的一个缺陷
0.3.0	新增 VersionSpecifiers::contains	判断版本是否满足全部约束
0.3.0	新增 Version::from_release	构造纯 release 版本，如 3.8
0.3.1	从 PyVersion 中暴露 Version
0.3.2	向 Python 暴露 operator 与 version 字段
0.3.3	为 VersionSpecifiers 实现 Display
0.3.4	提供 VersionSpecifiers 的 Python 绑定
0.3.5	字符串序列化风格向 poetry 看齐；实现 VersionSpecifier 的 __hash__
0.3.7	为 Version 增加 major()、minor()、micro()	由社区贡献者 ischaojie 通过 PR 引入
0.3.10	pyo3 升级 0.19，maturin 升级 1.0
0.3.12	为 Version 实现 FromPyObject

当前源码中 contains 语义依然保留：version_specifier.rs#L58-L60 的 contains 用 iter().all(...) 实现"版本满足所有约束"的语义，正是 0.3.0 引入的契约。

三、0.4：面向正确性的数据模型修正

0.4 是 Changelog 中含金量很高的一版，四条变更都指向性能或正确性：

1. release 段从 usize 改为 u64。Changelog 给出的理由非常具体：保证跨平台一致，且当"时间戳被用作 patch 版本"时必须能放下——例如 20230628214621（ISO 8601 basic 格式的日期时间），这种数字超过 32 位范围，在 usize 为 32 位的平台上会溢出。这一决策直接约束了当前 version.rs 中 VersionSmall 的位编码：release 各段被压缩进一个 u64 repr（首段占 16 位、其后每段各 8 位，见 version.rs#L1169-L1179 的注释与 push_release 逻辑），"全段 u64 语义 + 紧凑位打包"是 0.4 决策的延续。
2. 更快的版本比较——为 0.5 的彻底重写做了铺垫。
3. 新增 VersionSpecifier::equals_version：==<version> 的便捷构造器。当前实现在 version_specifier.rs#L499。
4. 新增 VersionSpecifier::any_prerelease：判断版本约束是否包含预发布标记。当前实现在 version_specifier.rs#L572；Version 一侧也有同名方法 version.rs#L315-L317（is_pre() || is_dev()），配套还有 is_stable、is_post、is_local 等判断。
5. pyo3 升级 0.20；用 once_cell 替换 lazy_static。

四、0.5：BurntSushi 主导的全面重写（本 crate 最重要的拐点）

Changelog 0.5 明确写道："The crate has been completely rewritten by burntsushi"，并列出六项变化。这一版奠定了 uv 版本引擎的性能底座，下面逐条对照当前源码印证。

4.1 更快的版本解析与比较

解析器目前基于 unscanny（见 Cargo.toml 的 dependencies），手写状态机而非正则或通用解析框架，错误路径也走零分配分支。Version 的入口示例可直接从 lib.rs 的文档测试复制运行：

use std::str::FromStr;
use uv_pep440::Version;

let version = Version::from_str("1.19").unwrap();
let version_specifier = VersionSpecifier::from_str("== 1.*").unwrap();
assert!(version_specifier.contains(&version));
let version_specifiers = VersionSpecifiers::from_str(">=1.16, <2.0").unwrap();
assert!(version_specifiers.contains(&version));

（上例取自 lib.rs#L54-L61 的 test_version 单元测试。）

4.2 Version 是内部表示的 Arc，克隆廉价

0.5 条目称 "Version is an Arc of its internal representation, so cloning is cheap"。当前源码中这一思想已经进一步细化：version.rs#L287-L290 定义

enum VersionInner {
    Small { small: VersionSmall },
    Full { full: Arc<VersionFull> },
}

也就是说，Arc 现在只套在 Full 变体上；Small 变体本身只是一个 u64 + u8 的内联结构（见 version.rs#L1169-L1179），克隆成本是两次字长拷贝。从源码结构看，这是 0.5 "克隆廉价" 目标的进化形态：常见路径（small）根本不涉及堆分配，冷门路径（full）才用 Arc 共享。

4.3 内部表示分裂为"完整表示"与"优化小变体"

这是 0.5 最核心的设计，Changelog 称小变体"可以处理 pypi 上 75% 的版本"。当前 version.rs#L195-L255 保留了作者当年的实测注释：从 PyPI 元数据统计了 11,264,078 个版本，其中"纯 release 且恰好 3 段"（即 x.y.z）的占 75.11%，"sweetspot"（无 local 段、release 不超过 4 段、所有数字都能装进 u8）的占 90.87%。小变体的位布局（VersionSmall）正是按这份分布设计的：

• repr: u64：首段 16 位 + 三处 8 位共 4 段 release，另留位段存放后缀类型与后缀版本号；
• len: u8：release 段数（0～4）；
• 后缀用 0～8 的枚举编码 dev / pre(alpha,beta,rc) / none / local / post，常量取值刻意按 PEP 440 排序关系赋值（见 version.rs#L1181-L1204 的 SUFFIX_DEV..SUFFIX_POST 注释）。

version.rs#L1150-L1162 的注释还坦白了一次踩坑史：早期尝试过在 packed 形式里同时编码多个后缀（如 1.2.3.dev2.post3），但"dev 版本应排在 pre 版本之前"的排序规则极难在固定位宽内表达正确，最终限制小变体只存一个后缀，复杂版本回落到 Full 表示。这解释了为什么 PEP 440 中罕见的"多后缀叠加"版本不会拖累常见路径。

4.4 字段访问器变为方法

0.5 起 "Version field accessors are now methods"。当前 version.rs#L352-L395 可见全部为方法形式：epoch()、release()、pre() 等，每个方法内部按 VersionInner 的两个变体分派，调用方对双表示完全无感。

4.5 解析错误改为不透明（opaque）类型

Changelog 称 "Parse errors are now opaque"。当前源码延续了这一风格，如 version.rs#L177-L193 的 OperatorParseError 仅有一个 pub(crate) got 字段，外部只能拿到 Display 文本（"no such comparison operator {:?}, must be one of ~= == != <= >= < > ==="），不能窥探内部状态——这与 uv 整体的错误处理风格一致。

4.6 rkyv 零拷贝序列化支持

0.5 加入 rkyv 支持，当前仍作为可选 feature 保留：Cargo.toml 中 rkyv = { workspace = true, optional = true }，源码里 Version、Operator 等类型都带 #[cfg_attr(feature = "rkyv", derive(rkyv::Archive, ...))]。version.rs#L1192-L1195 的注释还提醒：改动 VersionSmall 的位格式会破坏用 rkyv 序列化 Version 的 uv 缓存（至少包括 "simple" 缓存），必须同步提升缓存版本号——这是使用 rkyv 做二进制缓存的真实运维约束。

五、0.6 ～ 0.7：收敛 Python 绑定，完成内部化

Changelog 尾声三个阶段相对简短，但每一步都在做减法：

版本	变更
0.6	pyo3 升级 0.21，Python 最低要求 3.8
0.6.1	pyo3 升级 0.22
0.6.2 ～ 0.6.5	CI 修复
0.6.6	补上 VersionSpecifiers::empty()——"该构造函数在 uv 的 fork 版本中已存在，但公开发布版缺失"
0.7	移除 pyo3 绑定

0.6.6 这条值得注意：它说明在公开 crate 停止维护之前，uv 内部 fork 已经在反向向社区版回流 API。而 0.7 移除 pyo3 则是分水岭——uv-pep440 不再对外提供 Python 扩展，彻底成为 uv 的纯 Rust 内部组件，这与当前仓库中不存在 pyproject.toml、无 pyo3 依赖的现状完全吻合（Cargo.toml 的依赖仅有 serde、unicode-width、unscanny、uv-cache-key，以及可选的 rkyv、tracing、version-ranges）。

empty() 在当前 version_specifier.rs#L46-L50 的实现是 Self(Box::new([]))，语义为"匹配所有版本"——空约束列表即无约束，这也是 0.2.0 引入 VersionSpecifiers 语义的自然延伸。

六、当前实现快照：Operator 与约束匹配

结合 Changelog 0.4 提到的比较语义与当前 lib.rs#L4-L23 对 PEP 440 "反直觉特性" 的官方注解，当前 Operator 枚举 覆盖全部 PEP 440 操作符：

变体	语法	说明
Equal / EqualStar	== 1.2.3 / == 1.2.*	等值与通配等值（as_str() 两者都打印为 ==，星号由版本号侧体现）
ExactEqual	===	任意相等，规范"强烈不鼓励使用"；解析时带 tracing feature 会发出警告（version.rs#L145-L152）
NotEqual / NotEqualStar	!= 1.2.3 / != 1.2.*	不等与通配不等
TildeEqual	~=	兼容版本，不变量：至少 2 个 release 段
LessThan / LessThanEqual / GreaterThan / GreaterThanEqual	< <= > >=

几个值得注意的语义细节（均有源码注释佐证）：

• 排序 ≠ 匹配：version.rs#L259-L261 的警告指出 Rust 的 Ord 比较与 PEP 440 操作符语义不一致——例如 1.0+local > 1.0（排序），但 ==1.0 却能匹配 1.0+local（匹配）。版本顺序是全序，匹配则需处理大量特例；
• ~= 不可取反：Operator::negate()（version.rs#L66-L79）对 TildeEqual 返回 None，调用方需在更高层（如 marker 表达式）把兼容版本约束拆成 >= 与 < 两部分分别取反；
• local 版本的操作符白名单：is_local_compatible（version.rs#L89-L100）按规范只允许 ==、!=、=== 匹配含 local 段的版本。

七、如何在仓库中使用与验证该 crate

uv-pep440 是 uv 工作区（Cargo.toml 定义的 workspace）的一部分，常规验证方式：

# 查看当前 crate 的依赖与 feature 声明
cat crates/uv-pep440/Cargo.toml

# 运行 lib.rs 内置的解析/匹配单元测试
cargo test -p uv-pep440

# 查看 PEP 440 特性注解与公开 API
cargo doc -p uv-pep440 --no-deps

crate 公开 API 的完整清单见 lib.rs#L26-L41：Version、VersionSpecifier、VersionSpecifiers、Operator、Prerelease、LocalVersion 等，以及 version-ranges feature 开启后额外导出的 canonicalize_version_ranges、release_specifiers_to_ranges 等范围代数工具（version_ranges.rs），供 uv-resolver 做约束化简时复用。

八、小结

crates/uv-pep440/CHANGELOG.md 这份从 0.2.0 写到 0.7 的记录，浓缩了 uv-pep440 的三次质变：0.2.0 确立 VersionSpecifiers 聚合 API 并开启 Python 绑定；0.4 用 u64 段与 any_prerelease/equals_version 补齐正确性与便捷构造；0.5 的全面重写引入 Small/Full 双表示、Arc 共享、不透明错误与 rkyv 支持，成为 uv 高性能解析的基石；0.6～0.7 则通过移除 pyo3 完成从"公开 crate"到"uv 内部组件"的身份转换。当前仓库中的 version.rs 与 version_specifier.rs 正是这条演进线的终点形态——Changelog 中的每一条能力承诺（any_prerelease、equals_version、VersionSpecifiers::empty、rkyv、方法化访问器）都能在现有源码中找到对应的实现位置。