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

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

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

规则的一个明显推论是：一个 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 是一种试图在这些方面做一些事情的工具。