你的 API 一升级，老版本 App 就地瘫痪：接口向后兼容的六条军规

凌晨两点，值班手机响了。业务方说：客户端大面积报错。我们翻日志，发现客户端报的是 field_not_found——服务端把一个字段删了。

那个字段三个月前就已经没人用了。后端觉得"反正没人用"，顺手删了。

但客户端是装在几百万台用户手机里的。你删的不是字段，是几百万个还没升级的 App 的命。

这就是我要聊的主题：API 演进与向后兼容。它听起来像老掉牙的"接口规范"，实际上是后端工程里最容易翻车、也最容易被轻视的一块。它不酷，不炫，不出现在技术分享的封面页上——但它是那种"平时没人夸，出事全公司陪葬"的东西。

一、先搞清楚：向后兼容到底兼容的是什么

很多人以为兼容 = "老接口还能调"。这只是最表层的一层。真正的向后兼容至少包含四个维度：

协议兼容：客户端发来的请求，服务端仍然能解析。
字段兼容：客户端依赖的字段，仍然存在且语义不变。
语义兼容：字段还在，但含义变了——这是最阴险的一种。
行为兼容：接口返回一样，错误码、状态码、分页语义没变。

前三种破坏，业务当场就崩。第四种破坏，会在某个凌晨、某个监控盲区里慢慢渗透，直到变成一次事故复盘会。

为什么"删字段"会被当成小事？因为我们写代码时看到的是当前的契约，而不是历史的契约。老 App 里那个字段，对服务端代码而言是垃圾；对几百万台设备而言，那是它赖以运行的地基。

二、军规一：字段只增不删，语义只加不改

这是最容易理解、也最容易违反的一条。

想删字段？正确做法是标记废弃，而不是物理删除：

// 客户端会检查这个标记，不再使用，然后自然淘汰
{
  "user_id": "u_123",
  "nickname": "小龙虾",
  "legacy_mobile": "138****8888",   // deprecated: true
  "deprecated_fields": ["legacy_mobile"]
}

更隐蔽的是语义变更。比如 status 字段，原本 1 表示"待审核"，某次重构后 1 变成了"已通过"。字段名、类型、取值范围全都没变，客户端零报错，但业务逻辑全错。

三、军规二：新增字段必须是可选的，且客户端要能容忍未知字段

很多团队的客户端解析逻辑是"严格模式"：遇到不认识的字段直接抛异常。这在服务端同学看来很安全——"没见过的字段说明版本不对"——但它把服务端一次无害的字段新增，变成了客户端的崩溃。

正确做法：

服务端：新增字段一律可选（optional），有明确默认值；不删除、不重命名字段。
客户端：解析时忽略未知字段，这是 JSON 生态的基本礼仪。

严格模式唯一的合理用途是内部服务间的强契约通信，比如 gRPC 那套。而不是公网 API。公网 API 的客户端版本分布你永远不知道——包括你自己都忘了的老版本。

四、军规三：分页语义一旦定下，就别改

分页是兼容性重灾区，因为它是那种"看起来没人 care，实际上天天被依赖"的东西。

常见翻车姿势：用 page / page_size 做深翻页，数据量一大就慢得要死，于是想改成游标分页 cursor。结果老客户端的 page=2 参数直接失效或语义漂移。

更隐蔽的坑：

# 旧版：page 从 1 开始
GET /api/orders?page=1&page_size=20
# 返回 { "data": [...], "total": 100, "page": 1 }

# 新版想统一成 0-based（人类犯的经典错误）
GET /api/orders?page=0&page_size=20
# 老客户端传 page=1，新服务端理解成"第二页"——数据静默偏移

没有报错，没有 500，只是每一页都串位了。这种 bug 能藏几个月。

我的原则是：新分页方式用新接口，别在同一路径上改语义。/api/v2/orders 用游标，老的 /api/orders 原样保留并标注废弃。同时提供一个"桥接"能力：老的 page 参数服务端内部翻译成 cursor，老客户端零改动就能平滑活下来。

五、军规四：错误码是有版本的契约，不是随手写的字符串

客户端最怕的不是接口报错，而是"不知道该怎么办"。所以错误响应的结构必须标准化。

{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "订单不存在",
    "retryable": false,
    "details": { "order_id": "o_999" }
  }
}

最常见的破坏：把 retryable 的语义搞反。原来 ORDER_NOT_FOUND 的 retryable 是 false，某次重构统一错误处理逻辑时改成了 true。客户端拿到 404 就疯狂重试，一个"订单不存在"的查询瞬间打满你的库。

错误码的语义变更，比字段删除更可怕。因为字段删除客户端会报错（能发现），错误码语义变更客户端不会报错（只会在流量峰值时以另一种形式爆发）。

规则：错误码只增不改，废弃的保留，retryable 一经发布就是契约。

六、军规五：版本号用在"路径"还是"头部"，这是个立场问题

常见的三种做法，各有各的坑：

路径版本（/api/v2/orders）：直观、可缓存、可灰度。缺点是"同一个业务逻辑多份代码"容易腐化，v2 修 bug 忘了同步到 v1。
请求头版本（Accept: application/vnd.api.v2+json）：干净，但很多客户端库、网关、CDN 对它支持稀烂，调试时肉眼看不见版本，容易踩坑。
无版本 + 字段演进：理论上最优雅，实践中最容易失控，除非你有极强的纪律。

我的立场：优先靠"只增不删"的字段演进把版本需求压到最低；真的必须破坏性变更时，用路径版本，并且明确定义"每个版本的生命周期"。

七、军规六：兼容性的最终防线是"契约测试"，而不是口头约定

上面五条军规，靠人记是记不住的。人会忘，会换人，会在新需求下妥协。

唯一可靠的方式是把兼容规则变成自动化测试。

做法不复杂：维护一份历史请求/响应样本（golden files），每次发布前自动回放，验证老样本仍然得到符合预期的结果。

# 伪代码：契约回归
def test_backward_compatibility():
    for case in load_golden_samples("v1"):
        resp = request(case.request)
        assert resp.status == case.expected_status
        for field in case.required_fields:
            assert field in resp.json, f"字段 {field} 消失了！"
        assert resp.json.get("retryable") == case.expected_retryable

再加一条"字段白名单"规则：每次变更前后做一次字段 diff，任何被删除或类型变更的字段，必须在 MR 里显式声明"破坏性变更"并走审批。

这行代码在你的 CI 里跑一次，比在事故复盘会上写十页"我们以后一定要加强"有用得多。

八、一个自检清单

上线前对着过一遍：

我删/改/重命名任何字段了吗？→ 走废弃流程，别物理删
我改过任何枚举值的含义吗？→ 只能加新的，不能复用旧的
新增字段客户端老版本能忽略吗？→ 必须 optional
我改过分页参数、错误码、retryable 语义吗？→ 这些都是契约
老客户端传 page/offset 还能正常工作吗？→ 不行就上桥接层
有契约测试兜底吗？→ 没有的话，现在补还来得及

结语

API 兼容性这件事，本质上是你在为别人的未来买单。

你今天随手删掉的一个字段，是某个未知用户在某个网络环境下、用一台三年前的旧手机、打开一个没更新的 App 时，屏幕上弹出的那句"出错了，请稍后重试"。

而"稍后重试"从来不会好转。

所以，多写那几十行兼容代码，多跑那一次契约测试，多留那一个字段——成本很低，收益是别人看不见的夜晚你睡得着觉。

毕竟，谁不想当一个让人睡得着觉的后端呢。

你的 API 一升级，老版本 App 就地瘫痪：接口向后兼容的六条军规