改进rust代码的35种具体方法-类型(二十一)-熟悉Cargo.toml版本使用

上一篇文章-改进rust代码的35种具体方法-类型(二十)-避免过度优化的诱惑

---

“如果我们承认SemVer是一个有损的估计，只代表可能变化范围的子集，我们可以开始将其视为一个钝器。”——Titus Winters，“谷歌软件工程（O'Reilly）”

 Rust的软件包管理器Cargo允许根据语义版本控制（semver）自动选择Rust代码的依赖项。Cargo.toml节喜欢：

[dependencies]
serde = "1.4"

向cargo表明这种依赖性可以接受的semver版本范围。官方文档提供了有关指定可接受版本的精确范围的详细信息，但以下是最常用的变体：

• "1.2.3"：指定任何与1.2.3兼容的版本都是可以接受的
• "^1.2.3"：是另一种更明确地指定相同事物的方法
• "=1.2.3"：针脚到一个特定版本，不接受替代品
• "~1.2.3"：允许与1.2.3兼容的版本，但仅在最后指定的组件更改的情况下（因此1.2.4是可以接受的，但1.3.0不是）
• "1.2.*"：接受与通配符匹配的任何版本

这些规范允许的示例如下表所示。

依赖版本规范

技术规格	1.2.2	1.2.3	1.2.4	1.3.0	2.0.0
"1.2.3"	不	是	是	是	不
"^1.2.3"	不	是	是	是	不
"=1.2.3"	不	是	不	不	不
"~1.2.3"	不	是	是	不	不
"1.2.*"	是	是	是	不	不
"1.*"	是	是	是	是	不
"*"	是	是	是	是	是

在选择依赖版本时，Cargo通常会选择所有这些semver范围组合的最大版本。

由于语义版本化是cargo依赖性解决过程的核心，因此本项目探讨了有关semver含义的更多详细信息。

Semver必需

语义版本控制的要点列在semver文档的摘要中，转载如下：

给定一个版本号MAJOR.MINOR.PATCH，增加：

• 当您进行不兼容的API更改时的主要版本
• 当您以向后兼容的方式添加功能时，次要版本
• 当您进行向后兼容的错误修复时，补丁版本

一个重要点潜伏在细节中：

一旦版本化软件包发布，该版本的内容不得修改。任何修改都必须作为新版本发布。

用不同的词来表达：

• 更改任何内容都需要一个新的补丁版本。
• 以一种方式将东西添加到API中，这意味着板条箱的现有用户仍然需要编译和工作，需要小版本升级。
• 删除或更改API中的东西需要主要版本升级。

semver规则还有一个重要的codicil：

主要版本零（0.y.z）用于初始开发。任何事情都可能随时改变。公共API不应被视为稳定。

货物略微调整了最后一条规则，“左移”了早期的规则，以便最左侧非零组件的变化表明不兼容的变化。这意味着0.2.3到0.3.0可以包含不兼容的API更改，就像0.0.4到0.0.5一样。

Crate 作者的语义化版本控制

在理论上，理论等同于实践。但在实践中，情况并非如此。

作为一名板条箱作者，从理论上讲，这些规则中的第一条很容易遵守：如果你触摸任何东西，你需要一个新的版本。使用Git标签匹配发布版本可以对此有所帮助——默认情况下，标签固定为特定提交，只能使用手动--force选项移动。发布tocrates crates.io版本也会对此进行自动监管，因为注册表将拒绝发布同一板条箱版本的第二次尝试。不合规的主要危险是，当你在发布后不久就注意到一个错误，你必须抵制只是扼杀修复的诱惑。

semver规范涵盖了API的兼容性，因此，如果您对行为进行了不改变API的细微更改，那么就应该只需要更新补丁版本。（然而，如果您的板条箱被广泛依赖，那么在实践中，您可能需要了解Hyrum定律：无论您对代码所做的更改有多小，即使API没有变化，也可能会依赖旧行为。）

对于板条箱作者来说，困难的部分是后一种规则，这需要准确确定更改是否与后兼容。一些更改显然不兼容——删除公共入口点或类型，更改方法签名——一些更改显然是向后兼容的（例如，向struct添加新方法，或添加新常量），但中间还剩下很多灰色区域。

为了帮助解决这个问题， 在Cargo 书中相当详细地阐述了什么是兼容的，什么是不兼容的。这些细节大多不足为奇，但有几个方面值得强调：

• 添加新项通常是安全的，但如果使用该 crate 的代码已经使用与新项同名的内容，则可能会导致冲突。
  • 如果用户从 crate 中进行通配符引入，这样做就存在特别的危险，因为所有 crate 的项都会自动地进入用户的主命名空间
  • 即使没有进行通配符引入，一个新的 trait 方法（带有默认实现；第 13 条）或一个新的固有方法都有可能与现有名称发生冲突。
• Rust 对涵盖所有可能性的坚持意味着改变可用可能性的集合可能会引起破坏性变化。
  • 对枚举进行匹配必须涵盖所有可能性，因此如果一个 crate 添加了一个新的枚举变体，那将是一个破坏性的改变（除非该枚举已标记为 non_exhaustive — 添加 non_exhaustive 也是一个破坏性的改变）。
  • 显式创建结构体实例需要为所有字段提供初始值，因此向可以公开实例化的结构体添加字段是一个破坏性改变。拥有私有字段的结构体是可以的，因为 crate 用户无法显式构造它们；结构体也可以标记为 non_exhaustive，以防止外部用户执行显式构造。
• 改变一个 trait 使其不再是对象安全的是一个破坏性改变；任何为该 trait 构建 trait 对象的用户将无法继续编译他们的代码。
• 为一个 trait 添加一个新的默认实现是一个破坏性改变；任何已经实现该 trait 的用户现在将会有两个冲突的实现。
• 改变开源 crate 的许可证是一种不兼容的改变：对于那些严格限制可接受许可证的 crate 用户来说，这种改变可能会导致破坏。请将许可证视为 API 的一部分。
• 改变 crate 的默认特性可能会是一种破坏性改变。移除一个默认特性几乎肯定会导致问题（除非该特性已经是一个无操作）；添加一个默认特性可能会根据其启用的内容而导致问题。请将默认特性集视为 API 的一部分。
• 改变库代码，以便使用 Rust 的新功能可能是一种不兼容的改变，因为那些还没有升级编译器到包含该功能的版本的 crate 用户可能会受到这种改变的影响。然而，大多数 Rust crate 将最低支持的 Rust 版本（MSRV）的增加视为非破坏性的改变，因此请考虑 MSRV 是否构成你的 API 的一部分。

规则的一个明显推论是：一个 crate 拥有的公共项越少，就越少会导致不兼容改变的事物。

然而，不可否认的是，从一个版本到下一个版本比较所有公共 API 项的兼容性是一个耗时的过程，最好只能得出对变更级别（主要/次要/修订）的粗略评估。考虑到这种比较是一个有些机械化的过程，希望能够出现工具来简化这个过程。

如果你确实需要进行不兼容的主版本更改，最好通过确保改变后仍提供相同的整体功能来为用户简化生活，即使 API 已经发生了根本性的改变。如果可能的话，对于 crate 用户来说，最有帮助的顺序如下：

1. 发布一个包含新版本 API 的次要版本更新，并将旧版本标记为废弃，包括迁移的指示。
2. 发布一个主要版本更新，移除 API 中已经废弃的部分。

一个更微妙的观点是要让破坏性改变真正成为破坏性。如果你的 crate 正在以一种对现有用户实际上不兼容的方式改变其行为，但可以重用相同的 API：不要这样做。强制更改类型（并进行主要版本升级），以确保用户不会无意中错误地使用新版本。

对于 API 的不太具体的部分，比如最低支持的 Rust 版本（MSRV）或许可证，请考虑建立一个 CI 检查，以便根据需要使用工具（例如 cargo-deny；）来检测变化。

最后，不要因为版本号达到 1.0.0 而感到害怕，因为这意味着你的 API 现在是固定的。许多 crate 陷入了永远停留在版本号为 0.x 的陷阱，但这将把 semver 的三个类别（主要/次要/修订）的表达能力减少到两个（有效主要/有效次要）。

Crate 用户的语义化版本（Semver）

对于一个 crate 的用户，对于一个依赖项的新版本的理论期望如下：

• 一个依赖 crate 的新修订版本应该“立即可用”。
• 一个依赖 crate 的新次要版本应该“立即可用”，但新的 API 部分可能值得探索，看看是否有更清晰或更好的使用方式。然而，如果你使用了新的部分，就无法将依赖关系回滚到旧版本。
• 对于一个依赖的新主要版本，一切皆有可能；很可能你的代码将不再能够编译，并且你需要重写部分代码以符合新的 API。即使你的代码仍然能够编译，你也应该检查在主要版本变更后你对 API 的使用是否仍然有效，因为库的约束和前置条件可能已经发生了变化。

实际上，即使前两种类型的更改可能会导致意外行为变化，即使代码仍然能够正常编译，也可能受到海伦姆法则的影响。

由于这些期望，你的依赖规范通常会采用类似"1.4.3"或"0.7"的形式，其中包括后续兼容的版本；避免指定完全通配符依赖，如""或"0."。完全通配符依赖表示你的 crate 可以使用任何版本的依赖，具有任何 API，这不太可能是你真正想要的。避免使用通配符也是发布到 crates.io 的要求；带有"*"通配符的提交将被拒绝。

然而，从长远来看，忽略依赖关系中的主要版本更改是不安全的。一旦一个库经历了主要版本更改，进一步的 bug 修复——更重要的是安全更新——可能不会应用到之前的主要版本。像"1.4"这样的版本规范将会随着新的 2.x 发布的到来而逐渐落后，其中的安全问题也会被忽视。

因此，你需要接受被困在旧版本上的风险，或者最终跟随依赖关系的主要版本升级。诸如 cargo update 或 Dependabot（第 31 条）等工具可以在更新可用时通知你；然后你可以安排升级的时间，以便适合你的方便。

讨论

语义化版本控制也是有成本的：每次对 crate 的更改都必须根据其标准进行评估，以决定适当的版本升级类型。语义化版本控制也是一个粗糙的工具：充其量只能反映 crate 所有者对当前发布属于三个类别中的哪一种的猜测。并非每个人都能做到完全正确，关于“正确”究竟意味着什么也并非一切都清楚明了，即使你做对了，也总有可能会违反海伦姆法则。

然而，对于那些没有幸运地在像谷歌这样经过高度测试的巨大内部单库环境中工作的人来说，语义化版本控制是唯一的选择。因此，理解其概念和局限性对于管理依赖关系是必要的。

---

例如，cargo-semver-checks 是一种试图在这些方面做一些事情的工具。