📚 课程目录第3章 Schema版本管理

3、Schema版本管理：语义化版本控制、向后兼容与向前兼容、破坏性变更识别

版本管理这事儿，说白了就是给Schema上个户口。你想想看，API一上线，客户端、服务端、网关、文档，全都指着这份Schema活着。没有版本号，哪天改了字段，线上直接炸锅。

我个人习惯，从第一天就给Schema打上版本标签。哪怕只有我一个人用，也得标个1.0.0。这不是形式主义，这是给自己留条后路。

3.1 语义化版本控制：给Schema上户口

语义化版本控制（SemVer）不是新鲜概念，但用在Schema上，得稍微调整一下。标准格式是MAJOR.MINOR.PATCH，我直接说怎么映射到Schema场景：

版本位	Schema场景含义	典型变更
MAJOR	破坏性变更	删除字段、修改字段类型、新增必填字段
MINOR	向后兼容的新增	新增可选字段、新增枚举值、扩展约束范围
PATCH	修正与澄清	修正描述、调整示例值、修复默认值

我的习惯：每次发布Schema前，先跑一遍diff工具，自动判断应该升哪一位。别靠人脑记，人脑会漏。

举个例子。你有一个用户Schema，版本1.2.3：

{
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string" },
    "email": { "type": "string" }
  },
  "required": ["id", "name"]
}

现在你想加一个phone字段，可选。这是MINOR变更，版本升到1.3.0。但如果把email改成必填，那就是MAJOR变更，得升到2.0.0。

注意：千万别在PATCH级别做新增字段。PATCH只用于修正，不改变Schema结构。我曾经见过一个团队，PATCH里加了三个字段，结果下游消费者全懵了。

3.2 向后兼容与向前兼容：两个方向都要管

这两个概念，很多人搞混。我直接说人话：

向后兼容：老客户端能正常消费新Schema。你升级了服务端，旧版App不能崩。
向前兼容：新客户端能正常消费老Schema。你还没升级服务端，新版App先上线了，也不能崩。

说白了，向后兼容是保护存量用户，向前兼容是给未来留空间。两者都做到，才能平滑演进。

我记得有一次，团队里一个同学改了枚举值，觉得只是加了一个选项，没问题。结果老客户端收到新枚举值，直接解析失败。这就是典型的向后兼容没做好。

3.2.1 向后兼容的黄金法则

我总结了几条铁律，照着做基本不会出事：

只加不减：永远不要删除字段。实在要废弃，用deprecated标记。
只扩不缩：枚举值只能新增，不能删除或重命名。
只松不紧：约束只能放宽，不能收紧。比如maxLength只能增大，不能减小。
只加可选，不加必填：新增字段必须是optional，不能是required。

    核心原则：老客户端能读懂的字段，一个都不能少；老客户端读不懂的字段，不能让它崩溃。

3.2.2 向前兼容的实践技巧

向前兼容相对少见，但一旦遇到就很棘手。我常用的做法是：

忽略未知字段：服务端遇到不认识字段，直接忽略，不要报错。
默认值兜底：新客户端期望的字段，如果老Schema没有，给一个合理的默认值。
版本协商：客户端和服务端握手时，互相告知支持的Schema版本范围。

你想想看，如果服务端一看到不认识字段就抛400，那新客户端根本没法灰度上线。所以，宽容的解析策略是向前兼容的基石。

3.3 破坏性变更识别：哪些雷不能踩

破坏性变更，就是改了之后老客户端会炸的变更。我把它分成三类：

类别	具体变更	影响
结构破坏	删除字段、重命名字段、修改字段类型	客户端解析失败
约束破坏	收紧`minLength`、减少枚举值、新增必填字段	客户端数据校验不通过
语义破坏	改变字段含义、修改响应状态码、调整业务逻辑	客户端逻辑出错

前两类，工具能自动检测。第三类，得靠人审。我见过最坑的一次，是把status字段从字符串改成整数，"active"变成1。工具没报错，因为类型兼容？不，工具直接跳过了。结果前端所有判断=== "active"的代码全废了。

避坑指南：我曾经以为改字段名不算破坏性变更，只要新旧映射做好就行。结果发现，客户端用反射拿字段名的代码全挂了。所以，字段名也是契约的一部分，别乱动。

3.3.1 自动化识别工具链

手动检查太累，我推荐用工具自动化识别破坏性变更。常用的方案：

OpenAPI Diff：对比两个OpenAPI规范，自动标出破坏性变更。
JSON Schema Diff：针对JSON Schema的diff工具，支持自定义规则。
Protobuf Breaking Change Detector：Protobuf场景专用，检查wire format兼容性。

这些工具可以集成到CI流水线里。每次PR提交，自动跑一遍diff，如果检测到MAJOR变更，直接阻断合并。嗯，这里要注意，工具只能检测结构破坏和约束破坏，语义破坏还得靠Code Review。

3.4 版本管理流程：从开发到发布

光有理论不行，得有流程。我一般这么走：

本地开发：修改Schema，本地自测。
提交PR：触发CI，自动跑diff，判断版本变更类型。
Code Review：人工检查语义破坏性变更。
合并主干：自动生成新版本号，打Tag。
发布：更新Schema Registry，通知下游消费者。

这个流程，说白了就是让机器干机器的事，让人干人的事。机器检查结构，人检查语义，各司其职。

我的建议：在Schema Registry里维护一个CHANGELOG.md，每次变更都记录版本号、变更类型、变更描述。这样出了问题，回溯起来很快。

3.5 核心知识体系

下面这张图，把版本管理的核心逻辑串起来了。我画的时候特意把三个维度分开：版本号怎么定、兼容性怎么管、破坏性怎么查。你一看就明白。

这张图把三个核心模块串起来了。左边是版本号怎么定，中间是兼容性怎么管，右边是破坏性怎么查。底部是完整的发布流程。你照着这个框架搭，基本不会漏。

版本管理这事儿，说白了就是给变化一个身份，给兼容一个标准，给破坏一个预警。做到这三点，Schema演进就不会翻车。