3. 加密SDK版本管理策略与语义化版本号
版本管理这事儿，看着简单，真踩过坑才知道多重要。我一直记着早期做SDK时，把一个大版本直接推给了线上客户，结果因为接口不兼容，人家连夜回滚——那种滋味，啧。后来我才理解，版本号不只是一串数字，它是你跟用户之间的契约。
这一章我们就聊聊，怎么给加密SDK定版本号，怎么管分支，怎么让升级过程不翻车。核心就四个字：语义化版本。
3.1 语义化版本号规范
语义化版本号（SemVer）的格式很简单：主版本.次版本.补丁版本。比如 2.1.3，大版本2，小版本1，补丁3。
| 字段 | 含义 | 何时增加 | 举例 |
|---|---|---|---|
| 主版本 | 不兼容的改动 | API删除、字段类型变更、加密算法替换 | 1.0.0 → 2.0.0 |
| 次版本 | 向下兼容的功能新增 | 新增加密模式、新字段支持 | 1.0.0 → 1.1.0 |
| 补丁版本 | 向下兼容的问题修复 | bug修复、性能优化、文档更新 | 1.0.0 → 1.0.1 |
个人经验：我习惯在内部预发布版本上用
-alpha、-beta 后缀。比如 3.0.0-alpha.1，告诉测试团队：“这个版本接口可能改，别对外发。”
3.2 为什么加密SDK对版本号特别敏感
普通SDK不兼容最多报个错，加密SDK要是版本不对，可能直接导致数据读不出来。你想想看，A系统用v1.0加密了一些字段，B系统升级到v2.0后，发现解密失败——这辈子都不想再经历那种场景。
所以加密SDK的版本管理要额外关注三点：
- 密钥格式变化：哪怕密钥长度不变，仅仅调整了salt计算方式，也是主版本升级。
- 算法体系切换：从AES-128-GCM换到AES-256-GCM，必须发新主版本。
- 元数据结构调整：加密后的输出报文里加了版本标识字段——这算兼容增加，次版本就够了。
避坑指南：我曾经把一次算法参数微调当补丁发了（
1.2.3 → 1.2.4），结果下游服务用新SDK加密、旧SDK解密全部崩溃。那之后我定了铁规：算法相关任何改动，最低是次版本升级。
3.3 版本管理策略
光有版本号还不够，还得有策略。我一般用三线分支模型：
- 主干（master）：只合并经过完整回归测试的稳定版本。
- 开发（develop）：日常开发集成，版本号带
-SNAPSHOT或-dev。 - 发布（release）：每个待发布版本独立分支，测试通过后合入master并打tag。
打个比方：
master 标签: v1.0.0, v1.1.0, v2.0.0
release/1.1 → 测试 → 创建标签 v1.1.0 → 合入master
develop: v1.2.0-SNAPSHOT (持续迭代)
实际上，我还见过更轻量的单线策略——直接用tag做版本隔离，不保留长期分支。对于小团队或独立SDK模块，这招挺好用，但一定要注释清楚每个tag的改动范围。
3.4 向下兼容承诺
我理解的“兼容”分三级：
| 级别 | 含义 | SDK示例 | 允许场景 |
|---|---|---|---|
| L1 源码兼容 | 用户代码不改就能编译通过 | 增加枚举值、新增可选参数 | 次版本升级 |
| L2 二进制兼容 | 旧编译好的jar/dll直接替换 | 增加方法（不修改已有的签名） | 次版本/补丁版本 |
| L3 数据兼容 | 旧版SDK加密的数据能被新版解密 | 保留旧算法解析路径 | 主版本也要尽量保障（通过版本标识） |
重点：加密SDK最难保证的是「数据兼容」。我建议在每个加密结果头部嵌入一个版本号（1字节足够），这样新版在解密时可以先判断版本，再选择对应算法流程。这样即使主版本升级，旧数据也能读。
3.5 版本号在依赖管理中的落地
实际工程中，版本号会写进pom.xml、build.gradle或CMakeLists.txt。给个Maven的例子：
<dependency>
<groupId>com.example</groupId>
<artifactId>field-encryption-sdk</artifactId>
<version>2.1.0</version>
</dependency>
如果是C++，头文件里可以定义宏：
#define ENC_SDK_VERSION_MAJOR 2
#define ENC_SDK_VERSION_MINOR 1
#define ENC_SDK_VERSION_PATCH 0
个人习惯：我还会在SDK提供一个静态函数
getVersionString()，运行时能打印出版本，方便排查问题。比如用户在support里喊「解密失败了」，你让他先打出版本——三句话就能确认基线。
3.6 版本升级流程图
下面这张图概括了从开发到发布、再到兼容验证的核心流程，你看一眼就能记住节奏。
3.7 版本号变更决策清单
我把每次需要改动SDK时的决策步骤简化成一张清单，团队直接照着做就行。说白了就是个「版本跳检验表」。
- 改动是否破坏现有API？
是 → 主版本+1
否 → 走第2步 - 改动是否影响加密/解密结果？
是 → 主版本+1（即使接口签名没变）
否 → 走第3步 - 是否新增了功能接口？
是 → 次版本+1
否 → 补丁版本+1 - 是否修改了旧数据可读性？
是 → 必须在文档中声明「向后数据兼容」等级，并在解密切面保留旧解码通路。
我曾遇到过：有人把算法从AES-128-CBC换成AES-256-GCM，只改了次版本（1.5.0 → 1.6.0），因为接口没变。结果所有线上密文都无法解密。从此我的检验清单加了一条：「算法更换=主版本」。
3.8 版本管理工具与自动化
手工改版本号容易漏，我建议用工具自动化：
- Maven：
mvn versions:set -DnewVersion=2.1.0，自动更新pom。 - Gradle： 配置
version = '2.1.0'，配合git tag使用。 - GitHub Actions / GitLab CI： 在merge到master时自动打tag并生成release notes。
# 简单自动化脚本片段（bash）
#!/bin/bash
VERSION=$1
git tag -a "v$VERSION" -m "Release version $VERSION"
git push origin "v$VERSION"
echo "Tag v$VERSION created and pushed."
自动化之后，开发者只需要在PR里写清楚改动类别，程序自动帮你升版本。减少了人为遗漏，也保证了版本号的连续性和一致性。