第一章 版本兼容概述
做接口协议适配这些年，我几乎每个项目都会遇到版本兼容的坑。说白了，只要系统在迭代，接口就一定会变。不变的接口只存在于写完就废弃的 Demo 里。
1.1 为什么需要版本兼容
先想一个常见场景：你服务端升级了，改了某个字段的类型，客户端却还在用旧版本解析。结果是什么？字段解析失败，整个请求炸掉。用户感知到的就是 App 闪退、页面白屏。这就是版本兼容要解决的问题。
- 多版本共存：App 的更新不是强制性的，总有用户停留在旧版本。服务端不能一刀切。
- 渐进式升级：团队不可能让所有模块同时升级。上下游系统版本不一致是常态。
- 容错与回滚：新版本出问题时，需要能快速切回旧版本，不能因为接口格式不同而阻塞。
我记得刚接手一个金融支付项目时，旧版接口用 XML 传输，新版改成了 Protobuf，结果因为没有设计中间兼容层，导致灰度期间大量订单失败。嗯，那次之后我对“协议演进必须带兼容方案”这个原则再也不敢马虎了。
1.2 常见的兼容性问题
兼容性问题其实就几类，但每一类都能让你线上事故不断。我按踩坑频率排个序：
- 字段增减：新增必填字段，旧客户端发来的数据缺字段，服务端直接抛空指针。
- 类型变化：比如 int32 改成 int64，客户端解析溢出；string 改成 enum，旧客户端不认识。
- 语义变更：字段名没变，但值的含义变了。比如 status=1 原来是“待支付”，新版本改成“已取消”。
- 默认值陷阱：新加了可选字段，服务端默认值设为 null，客户端却期待空字符串，导致判断逻辑出问题。
- 枚举扩展：新增枚举值，旧客户端反序列化时遇到不认识的值，直接抛异常。
- 协议格式变更：JSON 改二进制、字段顺序变化、压缩算法替换——这些都是致命变化。
discount_id 字段，没告诉前端团队。结果旧版安卓端解析整个 body 时因为 JsonObject 里多了一个 key 导致崩溃。从那以后我养成了习惯：任何字段变更都必须同步客户端，并且尽可能使用 optional 标记。
为什么会这样？因为很多协议框架默认“多字段是安全的”，但实际上某些客户端实现会做严格校验。你想想看，一个 JSON.parse() 并不会因为多字段报错，但如果客户端用 data!["discount_id"] 强行取非可选值……那就是线上故障。
1.3 兼容性目标
清楚了问题，我们得明确到底要兼容到什么程度。我一般把目标分成四个维度：
| 兼容维度 | 定义 | 典型要求 |
|---|---|---|
| 向后兼容 | 新版本服务端能处理旧版本客户端发来的请求 | 不删减字段、不改变字段含义、不要求新增必填字段 |
| 向前兼容 | 旧版本服务端能处理新版本客户端发来的请求 | 新客户端能忽略不认识的字段、使用默认值 |
| 二进制兼容 | 不重新编译的情况下替换 JAR/DLL 文件后系统仍能运行 | 不改变类结构、方法签名、序列化 ID |
| 语义兼容 | 协议行为与预期一致，不因版本不同产生歧义 | 枚举值含义不变、状态机转换路径不变 |
实际项目中，向后兼容是最基本的要求，做不到的话升级就是灾难。而向前兼容往往更难实现，因为旧服务端不认识新字段。我通常的做法是在协议里嵌入版本号，服务端根据版本号做不同处理。
X-API-Version: 1.2，或者在 JSON payload 里放 "version": 1。这样服务端可以知道客户端用的是哪个版本，按需选择解析逻辑。
// 请求示例
POST /api/order/create HTTP/1.1
Content-Type: application/json
X-API-Version: 1.1
{
"version": "1.1",
"product_id": "P10086",
"quantity": 2,
// 新版本新增可选字段
"coupon_code": "SAVE20",
"ext_info": { "source": "web" }
}
你看，这里 version 是顶层字段，新旧服务端都能解析。对于旧服务端来说，它只需忽略 coupon_code 和 ext_info 即可。这就是向前兼容的设计思路。
1.4 版本兼容的核心逻辑流
最后我画了一张图，帮你把整个思路串起来。它描述了协议演变过程中，兼容策略如何运作。
这张图的核心思路是：协议演变后，第一步判断变更是否兼容。如果是破坏性变更，要么强制客户端升级，要么报错阻断。如果是兼容变更，则通过向后兼容、向前兼容、版本路由三种手段协同处理。最后汇入版本兼容实现层，配合灰度发布策略安全上线。