接口版本演进：如何安全地下线一个旧字段

后端接口一旦有外部调用方，字段就不能说删就删。记录一套比较稳妥的演进流程，尤其适合有 App 客户端的场景——老版本 App 可能一年后还在被使用。

一、加字段容易，删字段难

新增字段对老客户端通常是安全的（只要它忽略未知字段），所以响应结构要保持向后兼容：

// v1
{"id": 1, "name": "张三"}
// v2 只加不删
{"id": 1, "name": "张三", "display_name": "张三"}

反过来，删字段、改字段类型、改枚举含义、把单个对象改成数组，都是破坏性变更。

二、下线一个字段的四步

1. 标记废弃：文档和响应头里注明 deprecated，同时继续返回该字段
2. 观察调用：在网关或服务层统计还有哪些客户端版本、哪些调用方在读它（可以用字段名埋点或采样日志）
3. 灰度停返：先对内部调用方、新版本客户端停止返回，确认没有报错
4. 全量移除：确认观察期内零调用后再删代码

第 2 步最容易被跳过，但恰恰最关键的就在这里：没有数据就只能靠猜。

三、破坏性变更用版本隔离

确实要改结构时，用 URL 或请求头区分版本：

/api/v2/orders
Accept: application/vnd.blog.v2+json

URL 版本直观、便于网关分流和缓存；请求头版本让 URL 保持干净，但对调试和 CDN 不够友好。选一种并在全站统一。

老版本不要无限期维护，但要给明确的 sunset 时间，并在响应里通过 Deprecation / Sunset 头告知。

四、客户端也要配合

• 解析 JSON 时忽略未知字段，别用严格模式
• 对缺失字段给默认值，别直接崩
• 关键字段类型变化要有兜底解析

服务端单方面做兼容是不够的，双方在解析层都留余地，升级才不会互相卡住。

小结

原则就一句：先加后减，用数据决定何时减。加上废弃标注和调用观测，旧字段就能在不影响任何在线用户的前提下干净下线。