版本号的承载方式
常见做法是把版本放进路径，直观且便于网关路由、日志分析和缓存区分。放进请求头则显得地址干净，但调试和分享链接时不够直观。
路径版本适合对外公开的开放接口，头部版本适合内部服务之间。同一系统里不要混用两套规则，否则文档和网关配置都会变复杂。
版本号只在出现不兼容变更时递增。字段新增、可选参数增加这类向后兼容的调整，没必要新开版本，否则版本会迅速膨胀。对外文档要标注每个版本的状态，哪些在维护、哪些已废弃，调用方一眼能看出该用哪个。
什么算不兼容变更
删除字段、修改字段类型、改变字段语义、把可选参数改成必填、调整错误码的含义，这些都会让已有调用方出问题。
把默认分页大小从十改成二十，看起来是优化，对依赖固定数量的调用方就是破坏。这类隐式契约要写进变更规范里。
响应里新增字段通常是安全的，但调用方如果用严格模式反序列化，多出的字段会直接报错。这属于调用方的问题，仍应在文档里明确说明。字段在响应中的顺序变化一般不影响解析，但依赖固定顺序做校验的实现会遇到问题。
让新增能力不破坏旧逻辑
需要改变行为时，先加一个新字段或新参数，旧字段保留并在一段时间内继续返回，让调用方有时间迁移。
参数校验的放宽容易，收紧要谨慎。先按宽松规则接受并在日志里记录不合规调用，观察一段时间后再决定是否强制。
灰度发布是验证兼容性的有效手段。新版本先在部分流量上启用，观察错误率和调用方的异常反馈，再全量。新版本上线后要观察一段时间再推进旧版本的废弃，两件事不要挤在同一天。
废弃流程与沟通
废弃要提前公告，给出时间点和替代方案，而不是直接下线。公告里写清楚迁移步骤和影响范围，最好提供一段过渡期的兼容层。
在废弃期返回特定的提示信息或响应头，让调用方在日志里能发现自己在用旧接口。被动等待调用方自觉迁移通常不可靠。
到期的判定标准要客观，比如监控里旧版本调用量降到可忽略的水平。用量仍在就强行下线，等于把自己的维护成本转嫁给调用方。公告渠道要覆盖到实际调用方，只发在内部文档里往往没人看到。
文档与测试的同步
接口文档要和代码同源或者自动生成，手工维护的文档必然滞后。变更能否通过评审，看的是文档是否同步更新。
为每个仍然在服务的版本保留契约测试，覆盖字段存在性、类型和必填校验。防止在维护旧版本时不小心引入破坏性改动。
调用方的兼容性也应纳入联调检查清单。上线前的回归范围要包含上一个版本的核心链路，不能只测最新版本。
