📚 课程目录第4章破坏性变更识别

4. 破坏性变更识别：哪些改动会断裂向后兼容

版本兼容性最怕什么？我个人经验是，改了代码自己觉得没问题，别人一调用就跑飞。破坏性变更，说白了就是你的改动让老版本的调用方必须改代码才能继续用。这一节我带你挨个拆解，到底哪些操作会踩这个坑。

4.1 接口签名修改：最直接的断裂源

函数或者方法的签名一改，对调用方就是核弹级影响。我见过太多次了：有人觉得多加一个参数没事，结果编译直接报错。

4.1.1 删除公共函数或方法

这个是不能做的。你删了一个公共函数，所有调它的代码直接挂掉。

注意：即使你觉得这个函数“没人用”，也不能直接删。正确的做法是先标记为 @deprecated，等几个版本后再移除。

4.1.2 减少公开参数数量

参数少了，调用方传的多余参数怎么办？老代码可能还在传旧参数个数，编译器或者运行时校验会报错。

// v1.0
public void sendMessage(String to, String content);
// v2.0 突然改成：
public void sendMessage(String to);
// 调用方：sendMessage("user", "hello") 编译失败

嗯，这里要注意：就算你提供了重载版本，语义也可能不一致。

4.1.3 增加必需参数

在已有的函数前面加一个强制参数，或者加一个没有默认值的参数，都是破坏性的。调用方原来的调用方式直接无效。

技巧：如果必须加参数，请用带默认值的可选参数，或者提供一个新的重载方法，不改变原方法的签名。

4.1.4 修改参数类型或返回值类型

参数类型从 int 改成 long？返回值从 String 改回 Object？这些都会导致类型不匹配。我以前在项目中重构一个序列化库，把返回值从 byte[] 改成 ByteBuffer，结果下游几十个调用点全报错，修复了两周。

4.2 行为契约变化：隐形的杀手

有时候签名没变，但内部逻辑变了。这种我之前觉得不算破坏性，后来吃过亏才发现，不改签名也能搞崩别人的代码。

4.2.1 放宽输入校验或增强异常抛出

原来接受 null 的参数，新版突然抛出 NullPointerException？原来肯定有返回值的接口，新版在某些情况下返回 null？这些都属于契约破坏。

  经验：我一般会写一个“契约变更检查表”，每次发版前对照表里逐条检查：输入范围、返回约定、异常类型、锁定资源等。

4.2.2 修改默认值或替换算法

如果你有一个配置项默认值从 10 改成了 20，调用方没设这个值，行为就变了。替换算法也一样，比如排序算法从稳定排序改成不稳定排序，下游依赖排序稳定性的代码就会崩。

4.3 数据结构与序列化改动

在 SDK 内部传输数据时，结构变化容易被忽视。尤其是前后端交互、跨语言调用。

4.3.1 删除现有字段或属性

JSON 里原来有的字段突然没了，解析方会丢数据甚至抛异常。我项目里就出过这种事：response.userName 用得好好的，重构时被删了，前端白屏一整天。

4.3.2 改变字段类型

从 int 改成 string？原来 "age": 25，新版变成 "age": "25"。虽然值能转，但很多序列化工具会直接报错。

4.3.3 添加必填字段

给实体类加了一个必填字段，老代码 new User("Alice") 突然编译不过，因为没传新字段。

注意：添加字段时最好给默认值，或者用可选构造函数/构建者模式。

4.4 内部依赖与配置变更

有些破坏性变更藏在配置文件和依赖里，很难一眼看出来。

变更类型	例子	影响
升级基础库版本	从 Java 8 升到 Java 17	调用方可能不支持新语言特性或类库 API
修改最小依赖版本	要求 Spring Boot 2.x 升至 3.x	调用方需同步升级，否则冲突
重命名配置文件或 key	从 `sdk.timeout` 改为 `sdk.requestTimeout`	老配置文件失效，行为回退到默认值
移除已暴露的 SPI 实现类	删除了 `com.example.spi.MyProvider`	服务发现失败，调用方运行时异常

我遇到过最坑的一次：SDK 把内部日志框架从 Log4j 1 换成了 SLF4J，但没暴露日志配置接口，直接导致调用方原有日志拦截器失效。排查了整整两天才找到原因。

4.5 破坏性变更一览图

下面这张图把几类破坏性变更的识别路径串起来了。你可以当作快速排查清单。

4.6 如何提前发现破坏性变更

光知道哪些是破坏性变更还不够，关键是怎么提前发现。我总结了几步做法：

用语义版本号规则约束自己：只要改动了公共 API，先判断是否破坏向后兼容，是就升主版本号。
写兼容性测试用例：每次发版前用旧版本的测试用例跑一遍新代码。如果跑不过，说明有破坏性变更。
做 API 差异比对：可以用 javap（Java）、diff 或者专门的 API 扫描工具（如 Revapi）对比两版 SDK 的公开方法签名。
做序列化兼容性测试：序列化一张旧版本的 JSON 或 Protocol Buffer 数据，用新版反序列化，不报错且字段完整才算通过。

  我的个人习惯：每修改一个公共方法，就在注释里写“这个改动是否兼容老版本”，然后 PR review 时专门有人检查这一项。养成习惯后，基本不会漏掉。

破坏性变更识别其实没那么玄乎，说白了就是换位思考：如果你是调用方，收到这个更新，会不会报错？会的话，那就老老实实升大版本号，写清楚迁移文档。这一步做扎实了，后面 CI/CD 验证才能发挥真正的作用。