3. 版本号语义：SemVer规范在SDK中的应用
你可能会问：版本号不就是个数字吗，有什么好讲的？
其实在字段级加密SDK这种底层库上，版本号代表的是兼容性承诺。一版改错了，整个加密链路可能就断了。我自己的项目就出过这事——升级一个依赖后，老密文全都解不开。后来我才意识到，版本号不是随随便便给的。
3.1 为什么SDK需要版本号？
字段级加密SDK不像普通业务组件。它的输出是密文，带元数据，甚至影响数据持久化。如果版本号不规范，你无法判断：
- 升级后，已加密的字段能否解密？
- 新的加密模式是否兼容老的元数据结构？
- 回滚旧版本会不会导致密钥不匹配？
我个人习惯在SDK的包名/模块名里直接体现SemVer三位数。比如 field-crypto-1.2.3。看一眼就知道大版本号，心里有底。
3.2 SemVer三要素：Major.Minor.Patch
SemVer的标准格式：MAJOR.MINOR.PATCH。每个位的变更意味着不同级别的兼容性。
| 位置 | 变更条件 | 对加密SDK的影响举例 |
|---|---|---|
| MAJOR | 不兼容的API变更 | 加密算法从AES-256-GCM改为SM4；密文头部结构重写 |
| MINOR | 向下兼容的新功能 | 新增加密模式（如IV生成策略），旧密文能正常解密 |
| PATCH | 向下兼容的问题修复 | 修复固定IV的安全缺陷，但不改变密文格式 |
我建议在SDK的README里明确写一条：“MINOR版本升级后，密文元数据中的version字段增加1，但解密逻辑仍兼容旧值”。这就是语义的具体落地。
3.3 预发布与构建元数据
还有两个附加字段：-prerelease 和 +build。比如 2.0.0-alpha.1 或 1.3.0+build.20240901。
- 预发布标签（如
-beta,-rc.2）表示版本未稳定，给早期尝鲜用户测试。注意：预发布版本在比较时优先级低于正式版。也就是说1.0.0-alpha小于1.0.0。 - 构建元数据（如
+git.sha.7a1c4e2）不影响版本优先级，只用于识别构建来源。我曾在公司内用构建元数据标记编译时是否启用了硬件加速模块。
在字段级加密SDK里，我建议预发布标签只用于内部灰度。如果你把 2.0.0-rc.1 给外部用户，他们升级后可能会发现生产环境的密文和rc版本不兼容——我就踩过这个坑。
3.4 SemVer在字段级加密SDK中的实践规则
结合具体场景，我梳理了三条规则：
-
Major版本升级 = 加密参数重协商
每一次Major版本发布都要触发使用者刷新密钥、重新加密数据。比如从1.x到2.x，加密算法变了，旧密文无法自动迁移。你必须准备一个“双读双写”过渡期。 -
Minor版本升级 = 保留向后解密能力
新功能不影响老密文的解密。比如新增AAD（附加认证数据）字段，但老的密文头部不包含AAD。SDK内部必须检查版本号，缺失AAD则用空值补齐。 -
Patch版本升级 = 热修复，无需重加密
可以自动灰度替换。比如修复加密随机数生成器种子重复的bug，密文格式完全不变。升级后新生成的密文安全，旧密文仍能解密，只是安全性较低。建议在Patch发布时附带一个check_security方法供用户扫描。
semver 命令行检查当前版本是否合规。我通常把版本号写在 VERSION 文件里，再通过CI脚本自动验证与Git tag的一致性。
3.5 SDK版本升级与回滚的语义映射
回滚本质上就是版本降级。SemVer的比较规则决定了回滚是否可以安全执行：
- Patch降级：直接回滚，无需兼容性判断。比如1.2.3 -> 1.2.2。因为Patch不含新特性，差异只是修复。
- Minor降级：需要验证是否使用了新功能。如果从未调用新增API，可以回滚；否则可能引发运行时缺失方法异常。
- Major降级：几乎不可回滚。因为密文元数据中的加密算法或格式可能已经随新版本写入磁盘。回滚后，新写的密文会变成“孤儿数据”。
我记得有一次线上问题：团队把SDK从1.9.0升级到2.0.0，发现新密文无法被旧版解密，于是直接回滚。结果旧版对2.0.0产出的密文返回UNSUPPORTED_VERSION错误。最后只能重新加密所有受影响数据——这就是没理解Major语义的代价。
最后补一句：SemVer不是银弹。对于字段级加密SDK，建议在版本号之外额外维护一个密文元数据版本号（通常放在密文头部的前2字节）。这样即使SDK版本回退，也能通过元数据版本号决定用哪套解密逻辑。我自己的SDK框架里就是这么做的——meta.version 和 sdk.version 独立演进。