API 版本化与兼容策略

API 版本化不是加个 v2 路径就完事，关键是让旧客户端不被新改动打断。

什么时候需要

内部前端与后端同仓发布时不需要版本号，破坏性变更可以直接改。对外提供集成时才需要版本边界。

兼容优先

新增字段永远向后兼容；删除字段、改语义、改认证方式才需要新版本。能用可选参数解决的，不要开新版本。

文档与弃用

每个版本标注弃用日期和替代方案，日志里统计旧版本调用量，归零再下线。

常见错误

把版本号放在请求体里，导致网关与缓存无法区分；或者所有接口共用一个全局版本，一个小改动迫使全量迁移。