API版本管理：向后兼容与平滑升级的企业级方案

API版本管理：向后兼容与平滑升级的企业级方案

上周排查一个线上问题，凌晨两点被告警叫醒。客户端大面积报错，日志里清一色的“Unsupported Media Type”。追到代码发现，某个微服务在升级时修改了响应体里的一个字段名，从user_name改成了username。就这一个字段，让下游三个系统挂了两个小时。这种场景你我都不陌生——API变更本是常态，但如何管理变更，却是区分业余与专业的关键分水岭。

版本管理不是可选项

很多团队初期认为版本管理是“过度设计”，直到第一次线上事故教会他们做人。API一旦对外发布，就不再是私有财产。哪怕只服务内部团队，调用方也可能分散在不同部门、不同时区、不同技术栈中。强制所有调用方同步升级？那得看运维团队愿不愿意半夜接电话。

真正的企业级方案，核心就两条：向后兼容，平滑升级。听起来简单，落地时处处是细节。

向后兼容的实操边界

向后兼容不是无限度的。我们得明确什么能改，什么不能改。

可以安全修改的：

• 添加新的可选请求参数
• 添加新的响应字段
• 扩展枚举值（前提是调用方能处理未知值）

绝对危险的：

• 删除或重命名字段
• 改变字段数据类型
• 改变必填/可选状态
• 收缩枚举值范围