📚 课程目录第3章数据契约的版本管理

3、数据契约的版本管理：语义化版本控制、向后兼容性检查、版本演进策略、废弃与迁移

数据契约一旦投入生产，就变成了一个「活文档」。它会随着业务需求、数据模型、API 接口的变化而不断迭代。我见过太多团队，契约文件散落在各个仓库里，版本号乱标，消费者和生产者在对接时经常对不上号。说白了，版本管理做不好，数据治理就是一句空话。

这一章，我们聚焦四个核心问题：版本号怎么定、怎么判断新版本是否兼容、如何规划版本演进路线、以及旧版本如何体面地退场。

3.1 语义化版本控制：给契约一个清晰的身份证

数据契约的版本号，我建议直接采用 语义化版本控制（SemVer） 规范。格式很简单：MAJOR.MINOR.PATCH。但具体到数据契约，每个字段的含义需要重新对齐。

版本位	数据契约中的含义	典型触发场景
MAJOR	不兼容的变更	删除字段、修改字段类型、重命名字段、新增必填字段
MINOR	向后兼容的新增	新增可选字段、扩展枚举值、放宽字段约束
PATCH	内部修正，不影响接口	修正文档描述错误、调整字段排序、修复示例数据

我的习惯：在契约文件的元数据区，除了版本号，还会加上一个 compatibility 字段，显式声明本次变更的兼容性等级。这样消费者在拉取新版本时，可以快速判断是否需要调整代码。

举个例子，一个用户信息契约的版本演进可能是这样的：

# 初始版本
version: "1.0.0"
fields:
  - name: user_id
    type: string
  - name: email
    type: string

# 新增可选字段 phone（MINOR 升级）
version: "1.1.0"
fields:
  - name: user_id
    type: string
  - name: email
    type: string
  - name: phone
    type: string
    required: false

# 将 email 改为必填（MAJOR 升级）
version: "2.0.0"
fields:
  - name: user_id
    type: string
  - name: email
    type: string
    required: true
  - name: phone
    type: string
    required: false

3.2 向后兼容性检查：别让消费者措手不及

向后兼容性检查，是版本管理的「守门员」。我曾经在一个项目中，因为没做兼容性检查，直接修改了订单状态枚举值，导致下游十几个消费者在凌晨批量报错。嗯，那次事故之后，我们就把兼容性检查写进了 CI/CD 流水线。

检查的核心逻辑其实不复杂，我总结为三条规则：

生产者不能删除消费者正在使用的字段。 如果非要删，必须走 MAJOR 版本升级，并提前通知。
字段类型只能放宽，不能收紧。 比如 string 可以变成 string | null，但不能从 string 变成 integer。
枚举值只能增加，不能减少。 新增枚举值属于 MINOR 变更，删除枚举值属于 MAJOR 变更。

兼容性检查矩阵（简化版）

变更类型	兼容性	建议版本号
新增可选字段	✅ 兼容	MINOR
新增必填字段	❌ 不兼容	MAJOR
删除字段	❌ 不兼容	MAJOR
放宽字段约束（如去掉 maxLength）	✅ 兼容	MINOR
收紧字段约束（如增加 maxLength）	❌ 不兼容	MAJOR
修改字段描述	✅ 兼容	PATCH

你想想看，如果每次变更都能自动跑一遍兼容性检查，很多线上事故其实是可以避免的。我个人习惯用 JSON Schema 的 diff 工具 来做这件事，比如 json-schema-diff-validator，它能精确对比两个版本的 Schema，并给出兼容性结论。

3.3 版本演进策略：从 1.0 到 2.0 的平滑过渡

版本号怎么升，其实是个策略问题。我见过两种主流做法：

激进策略： 每次 MAJOR 升级，旧版本立即下线。适合内部服务、消费者可控的场景。
保守策略： 同时维护多个 MAJOR 版本，给消费者留出迁移窗口。适合开放 API、外部消费者众多的场景。

我个人更推荐保守策略。为什么呢？因为数据契约的消费者往往不止一个，你很难要求所有团队在同一时间完成升级。我曾经在一个金融项目中，同时维护了 v1、v2、v3 三个版本，每个版本的生命周期是 6 个月。虽然维护成本高了一些，但消费者可以按自己的节奏迁移，整体稳定性反而更好。

下面这张图展示了典型的版本演进路径：

3.4 废弃与迁移：让旧版本体面退场

废弃（Deprecation）不是直接删掉旧版本。我见过最糟糕的做法是：某天突然在契约仓库里删除了一个旧版本文件，然后下游所有消费者全部报 404。嗯，这显然不是治理，这是事故。

一个规范的废弃流程，应该包含以下步骤：

标记废弃： 在契约元数据中增加 deprecated: true 标记，并注明废弃日期和推荐替代版本。
通知消费者： 通过邮件、IM 群组或 API 响应头（如 Sunset 头）告知消费者。
设置缓冲期： 一般建议至少保留 3-6 个月，给消费者足够的迁移时间。
流量监控： 持续观察旧版本的调用量，直到确认没有消费者依赖。
最终下线： 在缓冲期结束后，正式移除旧版本。

我曾经踩过的坑： 有一次我们废弃了一个字段，但忘记在契约中标记 deprecated，只是口头通知了几个核心团队。结果有个边缘团队半年后还在用那个字段，导致数据丢失。从那以后，我要求所有废弃操作必须走契约文件变更，并且自动触发通知。

在契约文件中，废弃信息的表达方式是这样的：

fields:
  - name: old_field
    type: string
    deprecated: true
    deprecation_message: "此字段将于 2025-06-30 移除，请使用 new_field 替代"
    deprecation_date: "2025-01-01"
    sunset_date: "2025-06-30"
  - name: new_field
    type: string
    description: "替代 old_field 的新字段"

迁移策略上，我推荐 渐进式迁移。什么意思呢？就是新版本和旧版本同时运行，消费者可以按自己的节奏切换。比如先让 10% 的流量走新版本，验证没问题后再逐步提升比例。这个过程可以通过 API 网关的流量染色或路由规则来实现。

最后说一句，版本管理不是技术问题，而是沟通问题。工具和流程都是辅助，真正重要的是让所有参与者——生产者、消费者、平台团队——对「版本」这件事有统一的认知。数据契约的版本号，本质上是一种承诺：我变了，我告诉你我变了，我告诉你我怎么变了。