📚 课程目录第3章 Schema兼容性策略

3、Schema兼容性策略：向后兼容、向前兼容、完全兼容、不兼容模式详解及选择建议

说到Schema兼容性，很多团队一开始都不太在意。我见过不少项目，上线前大家忙着对字段，结果一发布，老客户端直接崩了。嗯，这就是典型的兼容性没想清楚。

说白了，Schema兼容性就是回答一个问题：新Schema和旧Schema能不能愉快地一起工作？ 你想想看，一个线上系统，客户端和服务端不可能同时升级。总有先有后。这时候，兼容性策略就是你的安全带。

核心原则：兼容性不是技术问题，是契约问题。谁改了契约，谁就要负责让老版本还能跑。

3.1 四种兼容模式，一次讲透

我个人习惯把兼容性分成四种模式。每种模式对应不同的业务场景和风险等级。咱们一个一个来看。

模式	定义	典型场景	风险等级
向后兼容	新Schema能读老数据	服务端升级，客户端不动	低
向前兼容	老Schema能读新数据	客户端先升级，服务端后升	中
完全兼容	双向都能读	长期多版本共存	极低
不兼容	新老无法互通	重大重构、协议切换	高

3.2 向后兼容：最常用的安全策略

向后兼容，说白了就是新版本能处理老版本的数据。这是我最推荐团队优先采用的模式。为什么？因为大部分线上变更都是服务端先升级，客户端慢慢推。

我在项目中遇到过这样一个坑：有一次我们给用户表加了个 phone_number 字段，类型是 string，但没设默认值。结果老客户端发来的请求里没有这个字段，服务端反序列化直接抛异常。嗯，这就是典型的向后兼容没做好。

我的习惯做法：新增字段时，永远给一个合理的默认值。对于 Avro 或 Protobuf，用 optional 或设置 default 值。对于 JSON Schema，用 default 关键字。

向后兼容的规则其实很简单：

允许：新增可选字段、新增枚举值（如果客户端能处理未知值）、放宽约束（比如把必填改成可选）
禁止：删除字段、修改字段类型、收紧约束（可选变必填）、重命名字段

// 向后兼容示例：新增字段必须带默认值
// 旧Schema
{
  "type": "record",
  "name": "User",
  "fields": [
    {"name": "id", "type": "int"},
    {"name": "name", "type": "string"}
  ]
}

// 新Schema（向后兼容）
{
  "type": "record",
  "name": "User",
  "fields": [
    {"name": "id", "type": "int"},
    {"name": "name", "type": "string"},
    {"name": "phone", "type": ["null", "string"], "default": null}
  ]
}

3.3 向前兼容：容易被忽视的坑

向前兼容正好反过来——老版本能读新版本的数据。你可能会问：什么时候需要这个？我告诉你，当你的客户端先于服务端升级时，就需要了。

举个例子：移动端 App 发版审核周期长，服务端可以先升级吗？不行。这时候客户端先发了新版本，服务端还是老代码。如果新客户端发来的数据里多了字段，老服务端能不能忽略掉？能，就是向前兼容。

我曾经踩过的坑：有一次做物联网项目，设备固件先升级了，上报的数据格式变了。后端还没来得及更新，结果老服务端解析新数据直接报错，整条链路断了。后来我们强制要求所有设备端升级必须保留老格式字段，才算解决。

向前兼容的规则：

允许：删除字段（老代码忽略即可）、收紧约束、新增必填字段（如果老代码能跳过未知字段）
禁止：新增老代码无法忽略的字段、修改字段类型、放宽约束

3.4 完全兼容：理想状态，但成本高

完全兼容，就是双向都兼容。新老版本可以任意顺序升级，谁先谁后都行。说实话，这是最理想的状态，但也是成本最高的。

我建议只在以下场景追求完全兼容：

公共基础库的 Schema（比如用户中心、订单中心）
长期维护的开放 API
多团队协作，升级节奏不可控的系统

怎么做？其实就是把向后兼容和向前兼容的规则都遵守了。说白了，你只能做加法，不能做减法。新增字段必须是可选的，不能删除任何字段，不能修改任何已有字段的类型。

我的建议：完全兼容虽然好，但别强求。如果业务迭代快，完全兼容会拖慢开发速度。我一般只在核心链路用完全兼容，边缘业务用向后兼容就够了。

3.5 不兼容模式：什么时候必须用？

不兼容，就是新老 Schema 完全没法互通。这听起来很可怕，但有时候你不得不这么做。

什么时候必须用？

重大业务重构：比如从单体拆微服务，数据模型全变了
技术栈切换：比如从 JSON 切到 Protobuf，或者从 Avro 切到 Thrift
安全漏洞修复：某个字段设计有安全风险，必须立即改掉
性能优化：旧 Schema 导致序列化性能瓶颈，需要彻底重设计

注意：不兼容升级必须配合灰度发布和版本隔离。我曾经见过一个团队，直接在生产环境改了 Schema 没通知下游，结果所有消费者全部报错，回滚花了两个小时。那场面，真是惨烈。

不兼容升级的标准流程：

通知所有消费者：提前至少一个迭代周期告知变更
双写/双读：新旧 Schema 同时运行一段时间
版本路由：根据客户端版本返回对应 Schema 的数据
灰度切流：逐步切到新 Schema，监控错误率
清理旧代码：确认所有消费者都升级后，删除旧 Schema 支持

3.6 如何选择？我的决策框架

讲了这么多，到底怎么选？我总结了一个简单的决策框架，你直接套用就行。

我的个人经验是：

80% 的场景用向后兼容就够了。别想太多，先保证服务端能升级。
15% 的场景需要完全兼容。通常是核心链路或开放平台。
5% 的场景不得不做不兼容升级。这时候一定要做好灰度方案。
向前兼容我一般只在移动端先发版时才用，其他场景很少单独用。

一个小技巧：如果你用的是 Avro 或 Protobuf，它们自带的兼容性检查工具非常好用。我每次提交 Schema 变更前，都会跑一遍兼容性检查。Avro 的 avro-tools 可以指定 --compatibility 参数，Protobuf 的 buf 工具也支持。别偷懒，跑一下能省很多事。

3.7 避坑指南：我踩过的那些雷

最后，分享几个我亲身经历过的坑，希望能帮你少走弯路。

枚举值不能随便加：我曾经在 Protobuf 的枚举里加了一个新值，结果老客户端不认识，直接报错。后来我学乖了，枚举值一定要预留一个 UNKNOWN 兜底。
默认值不是万能的：有一次我设了默认值，但业务逻辑里没处理 null 的情况。结果新字段虽然反序列化成功了，但业务代码直接 NPE。嗯，默认值只解决了序列化问题，业务逻辑还得自己兜底。
别信文档，信工具：很多团队说“我们约定好不改字段”，但人总会犯错。我建议把兼容性检查集成到 CI/CD 流水线里，每次提交自动跑。人靠不住，工具才靠谱。
不兼容升级一定要有回滚方案：我曾经以为一次简单的字段删除不会出问题，结果下游系统缓存了旧 Schema，回滚花了两个小时。从那以后，每次不兼容升级我都准备双写方案。

好了，兼容性策略就讲到这里。记住一句话：兼容性不是技术债，是设计债。 一开始想清楚，后面能省很多事。