4. 数据契约版本管理：语义化版本、向后兼容性、版本迁移策略

数据契约这东西，一旦上了生产，就不是你想改就能改的了。我见过太多团队，契约一改，下游全挂，半夜被电话叫醒。说白了，版本管理不是锦上添花，是保命的。

这一章，咱们就聊聊怎么给数据契约做版本管理。核心就三件事：语义化版本怎么定、向后兼容怎么判断、版本迁移怎么落地。

4.1 语义化版本：给契约一个“身份证”

数据契约的版本号，我建议直接用 SemVer（语义化版本）规范。格式很简单：MAJOR.MINOR.PATCH。

但注意，数据契约和软件库的语义不太一样。软件库的 MAJOR 升级意味着 API 不兼容，数据契约的 MAJOR 升级意味着数据格式或语义不兼容。

版本位	数据契约中的含义	典型变更场景
MAJOR	破坏性变更，不向后兼容	删除字段、修改字段类型、改变枚举值含义
MINOR	新增功能，向后兼容	新增可选字段、扩展枚举值（不破坏旧值）
PATCH	内部修正，无外部影响	修复文档描述、调整字段顺序、修正校验规则

举个例子。我之前在电商团队，订单契约里有个 status 字段，原来是 string 类型，枚举值 ["pending", "paid", "shipped"]。后来业务要加一个 cancelled 状态。

• 如果只是加一个枚举值，且旧消费者能识别旧值，那就是 MINOR 升级。
• 但如果把 status 从 string 改成 int（比如 0=pending, 1=paid），那就是 MAJOR 升级，因为所有消费者都得改代码。

4.2 向后兼容性：怎么才算“兼容”？

向后兼容，说白了就是：新版本的契约，老版本的消费者能不能正常工作？

我习惯把兼容性分成三个维度来检查：

4.2.1 结构性兼容

字段层面。新增可选字段是兼容的，删除字段是不兼容的。修改字段类型？除非是 widening（比如 int → long），否则基本不兼容。

4.2.2 语义性兼容

数据含义层面。比如 price 字段，原来单位是“分”，现在改成“元”。结构上还是 decimal，但语义变了，这就是不兼容。

4.2.3 协议性兼容

序列化/反序列化层面。比如从 JSON 切到 Protobuf，或者改了字段的序列化顺序，都可能造成不兼容。

4.3 版本迁移策略：平滑过渡的三种模式

MAJOR 升级不可避免。但你不能直接一刀切，让所有消费者同时升级。我常用的策略有三种：

4.3.1 双写/双读模式

生产者同时输出新旧两个版本的数据。消费者各自消费自己兼容的版本。等所有消费者都迁移到新版本后，再下线旧版本。

• 优点：风险最低，消费者可以按自己的节奏迁移。
• 缺点：维护成本高，生产者要同时维护两套逻辑。
• 适用场景：核心契约，消费者众多，迁移周期长。

4.3.2 兼容代理模式

在数据管道中加一个代理层，负责新旧版本的转换。消费者只认新版本，代理负责把旧版本数据转成新版本。

• 优点：消费者无需改动，迁移对下游透明。
• 缺点：代理层成为性能瓶颈，转换逻辑复杂时容易出错。
• 适用场景：消费者数量多但技术能力弱，无法快速适配。

4.3.3 版本协商模式

生产者和消费者在握手阶段协商版本。消费者声明自己支持的版本范围，生产者返回对应版本的数据。

• 优点：灵活，支持多版本共存。
• 缺点：实现复杂，需要协议层支持版本协商。
• 适用场景：API 网关、微服务间调用。

4.4 版本管理流程：从开发到下线

我建议把版本管理嵌入到 CI/CD 流程中。每次契约变更，自动触发版本检查和兼容性校验。

# 版本检查伪代码
def check_version_compatibility(old_schema, new_schema):
    if is_breaking_change(old_schema, new_schema):
        return bump_major()
    elif is_additive_change(old_schema, new_schema):
        return bump_minor()
    else:
        return bump_patch()

流程大致是这样的：

1. 开发阶段：开发者修改契约定义（比如 Avro/Protobuf/JSON Schema）。
2. 提交阶段：CI 自动运行兼容性检查，判断版本号应该怎么升。
3. 审批阶段：如果是 MAJOR 升级，需要架构师审批，并制定迁移计划。
4. 发布阶段：新版本契约注册到 Schema Registry，同时触发迁移流程。
5. 下线阶段：确认所有消费者已迁移，旧版本标记为 DEPRECATED，最终下线。

4.5 避坑指南：我踩过的几个坑

最后，分享几个我亲身经历过的教训：

• 别信“小改动”：我曾经觉得加个字段是 MINOR，结果那个字段是 required 的，下游直接反序列化失败。记住，新增 required 字段是 MAJOR 变更。
• 枚举值不是随便加的：如果消费者用 switch 或模式匹配处理枚举，新增值可能导致未处理的分支报错。这种情况，我建议走 MAJOR 升级。
• 默认值陷阱：给新字段加默认值，看起来是兼容的。但如果默认值在业务上不合理（比如金额默认 0），消费者可能没注意到，产生数据质量问题。
• 版本号别跳：我见过有人直接从 1.0.0 跳到 2.0.0，中间跳过了 1.1.0、1.2.0。这会让消费者搞不清楚中间有哪些变更。按顺序来，别跳。