4. 版本管理必修课：语义化版本（SemVer）与API/ABI兼容性声明
4.1 为什么版本号不是随便写的
版本号这东西，看着简单，但搞砸的代价可不小。我以前参与过一个加密SDK的项目，团队里有人升级了内部依赖，就顺手把版本号从1.2.3改成了1.2.4。结果下游用户发现之前能用的函数签名变了，直接编译报错。后来排查才知道——这次改动引入了API破坏，按规则该升MAJOR版本的。但大家图省事，只改了PATCH。嗯，从那以后，我强制团队必须推行语义化版本（SemVer），并且每次发布前都要过一遍兼容性检查清单。
说白了，版本号不是用来刷存在感的，而是你和用户之间关于「变与不变」的契约。用户看了版本号，就得知道：能不能直接升级？会不会报错？要不要改代码？
4.2 语义化版本核心规则
语义化版本号长这样：MAJOR.MINOR.PATCH。每个部分都有明确的含义：
| 版本段 | 何时增加 | 对用户的影响 |
|---|---|---|
| MAJOR（主版本） | 做了不向后兼容的 API / ABI 改动 | 用户必须修改代码或重新编译 |
| MINOR（次版本） | 新增功能，但仍向后兼容 | 用户无需改动，可放心升级 |
| PATCH（修订号） | 修复 bug，完全向后兼容 | 零风险，纯优化 |
你想想看，如果用户看到你的版本号从 2.5.0 跳到 2.6.0，他敢不敢直接替换动态库？按 SemVer 的规矩，敢。但如果是从 2.5.0 跳到 3.0.0，那就得掂量掂量了——老代码很可能不兼容。
这里有个容易忽略的点：Pre-release 和 Build metadata。比如 1.0.0-alpha.1 或 1.0.0+build.20231001。预发行版本优先级低于正式版，且不承诺兼容性。在我带过的项目里，预发行版本经常被用户当成正式版来用，结果一升级就炸。所以我的建议是：非正式版名称里务必带上 -alpha、-beta、-rc.1 之类的标记，并且明确告诉用户——这些版本随时可能变。
4.3 API 兼容性 vs ABI 兼容性
大部分开发者只关心 API（应用编程接口），但做 SDK 封装，尤其是 C/C++ 的动态库场景，ABI（应用二进制接口）兼容性问题更致命。API 兼容只保证源码级能编译通过，ABI 兼容则保证已有的二进制文件（.so、.dll）可以直接链接，不用重新编译。
我记得有一次，我改了一个结构体的内部排列顺序，函数签名和头文件都没变，所以只改了 MINOR 版本号。结果供应商的旧程序运行时内存踩踏，崩溃了。为什么？因为结构体 ABI 变了：成员变量的偏移量变了，而旧程序里已经硬编码了那些偏移量。这就是典型的 ABI 破坏但 API 没变 的情况。
所以对于加密 SDK 这种底层库，我强烈建议你：把 ABI 兼容性也纳入版本号变更的决策依据。下面这个表格可以帮助你快速判断：
| 变更类型 | API 兼容？ | ABI 兼容？ | 应增加 |
|---|---|---|---|
| 新增非虚函数、全局变量（不暴露结构体） | 是 | 是 | MINOR |
| 修复内部 bug，不涉及公共头文件 | 是 | 是 | PATCH |
| 修改结构体成员、删除虚函数、改变枚举值 | 可能 | 否 | MAJOR |
| 新增虚函数（C++ 类） | 是 | 否 | MAJOR |
你看，新增虚函数明明是源码兼容的，但 ABI 不兼容——因为虚表指针指向的函数表发生了重新排列。很多 C++ 库踩过这个坑。
4.4 兼容性声明与版本策略
光有版本号还不够，你还得 明确声明 每个版本的兼容性范围。我建议在 SDK 的发布说明（Release Notes）里，专门加一段「兼容性声明」，格式可以参考：
兼容性声明：
- 版本 3.2.0 完全兼容 3.1.x（API 和 ABI）
- 版本 3.2.0 不兼容 2.x.x 系列（所有 2.x 版本请参考迁移指南）
- 版本 4.0.0 将移除已废弃函数 `crypto_set_flag()`，请改用 `crypto_config()`另外，对于加密 SDK，我建议保持 向后兼容至少两个大版本。比如当前稳定版是 4.x，那么 3.x 的公共接口尽量用弃用标记（deprecated）而不是直接删除。用户需要时间来迁移，尤其是安全类库，代码审核流程往往很慢。
我个人习惯在头文件里加上 __attribute__((deprecated)) 或 [[deprecated]]，并在编译时输出警告。这样用户升级 SDK 时，编译就能提前发现问题，而不是运行时炸了。
4.5 避坑指南：这些教训我替你们付过学费了
我曾经遇到过，一个同事修复完 bug 后只改了代码，版本号还是 1.0.0。用户下载后发现跟以前不一样，以为是同一个版本自己搞错了。最终的代价是运维排查了两天，最后发现是版本号没更新。我的建议：提交前让 CI 自动检查版本号是否与上次 tag 一致，不一致就阻断发布。
这是 ABI 兼容性最容易翻车的地方。如果你在动态库里暴露了内部符号（比如不该导出的全局变量），另一个库也有同名符号，链接时就会产生冲突。我曾经花了一周追一个诡异的加密结果错误，最后发现是 foo.so 和 bar.so 都用了同一个符号名
__internal_key，链接器偷偷给合并了。解决办法：所有内部符号加 namespace 或者用 visibility=hidden，只导出用 __attribute__((visibility("default"))) 标注的接口。
对于 C/C++ 项目，可以用 libabigail 或 abi-compliance-checker 自动比对两个版本符号表的差异。我在 CI 里加了这一步：每次 tag 前运行检查，如果出现 ABI 破坏而版本号没升 MAJOR，就直接失败。这个习惯坚持了两年，再也没出现线上 ABI 崩溃的问题。
很多团队把
1.0.0-rc.1 当成正式版给客户试用，但不注明兼容性可能变化。结果客户基于 rc.1 写了集成代码，等正式版 1.0.0 出来时发现结构体改了。我建议：预发行版本号一定要明确标注“不保证兼容”，并且限制测试范围。如果非要给客户，请在合同中写明“此版本不享受兼容性承诺”。
- 版本号 = 兼容性承诺：每次改动必须对照 API 和 ABI 兼容性检查表，确定该升哪一位。
- 明确声明：在发布说明里写明当前版本兼容哪些旧版本，不兼容哪些。
- 工具化：用 CI 自动检查版本号、ABI 变化，避免人为疏忽。