📚 课程目录第4章升级前的准备工作

4. 升级前的准备工作：环境检查、依赖梳理与影响评估

说实话，升级SDK这事儿，很多人上来就改代码，结果跑起来全是坑。我个人习惯是先停一停，把家底摸清楚。这一步做扎实了，后面至少能省掉80%的麻烦事。我在项目里见过太多次因为急着上线，跳过准备阶段，最后搞到凌晨三点回滚的惨案。

今天咱们就仔细聊聊，升级前到底要检查什么、梳理什么、评估什么。嗯，这里我把它分成三大块：环境检查、依赖梳理、影响评估。

4.1 运行环境检查：先看地基稳不稳

为什么是Java版本？因为字段级加密SDK底层用了大量的jce（Java Cryptography Extension）和安全管理器。不同JDK版本对加密算法的支持粒度不一样。

检查项	具体内容	我踩过的坑
Java版本	确认生产环境的JDK大版本（8/11/17/21）	新SDK依赖了Java 11的TLS 1.3特性，而生产还是Java 8，直接报NoSuchMethodError
操作系统字符集	LANG环境变量，locale -a输出	曾遇到过macOS本地正常，Linux生产环境因为zh_CN.UTF-8缺失导致Base64编码错误
键管理服务（KMS）版本	KMS client SDK版本、密钥算法支持	新SDK需要KMS支持AES-256-GCM，老版本KMS只支持AES-128-CBC
数据库驱动	MySQL / PostgreSQL客户端版本	加密后的密文字段长度增加，老驱动截断数据
CPU架构	x86_64 / ARM64（Apple Silicon / 鲲鹏）	某些加密库在ARM64上性能差50%

特别注意： 如果你有用过-pedantic或-XX:+UnlockExperimentalVMOptions这类JVM参数，升级后一定要验证是否与新SDK冲突。我曾经因为一个-XX:+UseG1GC的参数和加密SDK的堆外内存管理打架，排查了两天。

环境检查的实操方法很简单。我建议写一个脚本，采集每台机器的关键信息。比如这样：

#!/bin/bash
# env-check.sh —— 环境预检脚本
echo "=== Java 版本 ==="
java -version 2>&1 | head -3
echo "=== 操作系统 ==="
uname -a
echo "=== 字符集 ==="
echo $LANG
echo "=== CPU 架构 ==="
uname -m

4.2 依赖梳理：别让间接依赖坑了你

依赖管理这件事，很多团队做得不细。你想想看，你的pom.xml或者build.gradle里只写了一个直接依赖，但Maven/Gradle拉下来十几个间接依赖。这些间接依赖里但凡有一个版本不对，升级就炸了。

规范做法是生成完整的依赖树。以Maven为例：

mvn dependency:tree -Dincludes=*加密SDK的groupId*

然后你打开输出，一行一行看。重点看几点：

间接依赖的版本范围：比如某个日志框架是[2.0,3.0)，但生产环境实际用的是2.1，新SDK强制要求2.3+，那就冲突了。
传递性依赖的排除：如果新SDK引入了你不想要的依赖（比如旧的bouncycastle版本），记得在构建文件里exclude掉。
依赖收敛：同一个依赖在不同子模块里版本不一致，最终构建时选哪个版本？

依赖名	当前版本	新SDK要求	风险等级
com.google.guava	30.1-jre	31.0-jre	低（兼容）
commons-codec	1.14	1.15	中（API变动）
org.bouncycastle	1.68	1.72	高（算法实现不同）

我的建议： 如果项目依赖特别多，直接用Maven Enforcer插件或Gradle的resolutionStrategy做一个版本锁定。先把所有依赖的版本定死，升级时再逐个解绑。这样做回滚也容易，改一个文件就能还原。

4.3 影响评估：数据兼容性和API改动

这步是最考验经验的。升级字段级加密SDK，本质上是在动核心数据管道。我一般从四个维度评估影响：

4.3.1 数据格式变化

老版本SDK加密出来的数据可能是：ENC[base64密文]，新版本可能变成了ENCv2[版本号:base64密文:校验和]。存量的数据读出来时，新SDK能识别老格式吗？

实操做法：在本地写一个单元测试，用老版本SDK加密一批样本数据，然后用新版本SDK逐个解密。记录成功率：

// 样本数据预演
String[] samples = {"user_001", "张三", "test@example.com", "12345678901"};
for (String raw : samples) {
    String cipherOld = oldSdk.encrypt(raw);
    String plainNew = newSdk.decrypt(cipherOld);
    assert raw.equals(plainNew) : "兼容性失败: " + raw;
}

4.3.2 API签名变更

这一点容易忽略。新SDK可能会修改方法的参数列表、返回值类型或者异常声明。举个例子：

旧版：EncryptResult encrypt(String plain, String keyId)
新版：EncryptResult encrypt(String plain, EncryptOptions opts)，其中EncryptOptions包含keyId、iv、paddingMode等字段

如果不提前发现这种改动，编译阶段就会报错，还算好处理。怕的是运行时才暴露的API改动，比如返回值从String变成了一个带属性的对象：

旧版：String cipher = encryptService.encrypt(data);
新版：CipherResult result = encryptService.encrypt(data); String cipher = result.getCipherText();

  关键一步： 把所有调用老SDK的地方列一个清单。然后逐一对照新SDK的官方迁移文档，做映射。我习惯用一个简单的表格来追踪进展。

4.3.3 性能影响

新版本的加密算法可能更强，但也更慢。比如从AES-128升级到AES-256，加密耗时差不多增加30%~50%。此外，密钥轮换频率也可能影响性能。

我在项目中做过一组基准测试，结果如下：

场景	旧版SDK（ms）	新版SDK（ms）	变化
单条加密（1KB数据）	0.8	1.2	+50%
批量加密（1000条）	350	480	+37%
单条解密	0.6	0.9	+50%
批量解密	280	390	+39%

你看，性能退步是客观存在的。但这不一定成为阻塞项。只要确认在业务高峰期，数据库连接池和CPU还有余量，就可以接受。

4.3.4 回滚路径

这章本来不讲操作步骤，但准备工作里一定要想清楚回滚路径。你想想看，如果升级后线上出了问题，你手里得有能快速复原的方案。

回滚路径评估清单：

数据库快照：升级前是否对所有加密字段做了全量备份？
配置回退：新SDK引入的新配置项，能否一键关闭？
二进制回滚：是否保留了旧版本的jar包或docker镜像？
数据双向兼容：新版本加密的数据，老版本SDK能否解密？如果不能，回滚后这批数据怎么办？

我曾经踩过的坑：
新SDK改了默认加密算法，我忘了检查数据兼容性。升级后写入的新数据，用老版本SDK全读不出来。最后被迫写了半个小时的数据迁移脚本，在灰度期间人工替换密文。

4.4 最后总结：一个结构化的核对清单

好了，上面讲了很多细节。为了方便你落地，我把所有准备工作浓缩成一张核对清单。我建议你打印出来，每完成一项就打勾：

分类	检查项	完成
代码层	编译通过，无API兼容错误
代码层	单元测试覆盖新增/变更方法
数据层	存量数据兼容性测试通过
数据层	数据库字段长度验证（密文变长）
运维层	Java版本、KMS版本、数据库驱动确认
运维层	性能基准测试完成，达标
运维层	回滚脚本就绪，且经过验证
文档层	依赖变更记录在release notes中

准备工作做到这个份上，升级就是稳稳的了。先把这些硬骨头啃完，后面操作起来就能心不慌、手不抖。我始终相信，好的工程师不是靠事故堆出来的，而是靠扎实的准备工作撑起来的。