后端接口如何做版本管理才能兼容旧客户端

结论：后端接口做版本管理，最稳妥的组合是「URL 路径带大版本号（如 /api/v1/orders）＋ 只做向后兼容的增量改动 ＋ 破坏性变更才升版本 ＋ 用 Deprecation/Sunset 响应头配合调用量埋点做灰度下线」。核心原则一句话：能加不能改，能改不能删。

哪些改动算破坏性变更，必须升版本？

结论：凡是会让老客户端「解析失败或行为改变」的改动，都是破坏性变更，必须开新版本号；其余一律在原版本内做。

必须升版本的情况包括：删除或重命名字段、字段类型变化（int 改 string、对象改数组）、把可选参数改成必填、收紧校验规则、改变字段业务含义、修改默认值、调整错误码或 HTTP 状态码语义、改分页结构（data.list 改成 data.items）、改认证方式（如 token 换成 Authorization: Bearer）。

可以安全地做、不需要升版本的情况：新增可选请求参数、响应里新增字段、新增独立接口。注意一个坑：「响应新增枚举值」对写了 switch 穷举判断的客户端也算破坏性变更，所以规范里要写明客户端必须容忍未知枚举值，否则别加。

版本号放在 URL 还是 Header？

结论：面向 App 和第三方开放接口，优先放 URL 路径；内部服务之间可以放 Header。

/api/v1/orders 这种 URL 版本的好处是：日志、Nginx/CDN 缓存、网关路由（按前缀转发到 v1 服务）、Postman 调试全都天然可辨识，排查问题时一眼看出谁在调老版本。缺点是「同一资源多个 URL」在 REST 纯粹主义者看来不优雅，但工程收益更大。

Header 方案（Accept: application/vnd.example.v2+json 或自定义 X-API-Version: 2）URL 干净，缺点是缓存键、日志、浏览器直接访问都不友好，出错时也难排查。查询参数 ?version=2 最不推荐，因为它常常在跳转和日志里被丢掉。

版本号用整数大版本（v1、v2），不要用 1.2.3 这种语义化版本——接口版本只表达兼容与否，不表达迭代次数。

怎么在不复制代码的前提下同时跑 v1 和 v2？

结论：内部只维护一套核心业务逻辑，版本差异用适配层（DTO 转换）解决，不要为 v1 拉一条独立分支。

具体做法：核心 Service 只接收内部的领域对象；v1、v2 各自有一个 Controller + 转换器，v1 的转换器负责把新模型「降级」成老结构（比如新模型有 fullName，v1 转换器拆成 firstName/lastName）。这样修 Bug 只改一处。只有当新旧逻辑语义真的冲突时，才允许 v1 保留独立实现分支，并在代码里标注删除时间。

写死的规则：线上同时维护的大版本不超过 2 个（N 和 N-1），第 3 个版本上线前必须先下线最老的。

老客户端怎么优雅下线？

结论：下线靠数据说话，不靠感觉——先埋点统计各版本调用量，再用标准响应头预告，最后按阈值切流。

步骤：① 网关按 v1/v2 前缀聚合 QPS 和调用方 App 版本，做成看板；② 接口返回 Deprecation: @1735689600（RFC 9745 定义的弃用时间戳）和 Sunset: Wed, 01 Jul 2026 00:00:00 GMT（RFC 8594 定义的停用时间），同时在响应体里给提示字段；③ 提前 6 个月通知，App 端在启动时检测到老版本就弹强更弹窗；④ 当 v1 的日调用量占比降到 0.1% 以下、且剩余调用方都是可联系的自有客户端时，再关停。

对移动端要有心理准备：App Store 和安卓渠道里可能仍有 12～24 个月前的老版本在跑，所以版本的规划周期按「年」算，不按「月」算。

怎么在 CI 里自动拦住破坏性变更？

结论：把 OpenAPI 文档纳入版本控制，用 schema diff 工具在合并请求里自动阻断破坏性改动。

落地方式：每次提交生成 openapi.yaml，用 oasdiff breaking 或 openapi-diff 对比主干版本，检测到删除字段、类型变更、新增必填参数就直接让流水线失败；返回值非 0 即阻断合并。再补一层契约测试（Pact 或基于 OpenAPI 的响应校验），保证 v1 的响应结构在每次发布后仍然符合冻结的 schema。

总结一下：URL 带大版本、只增不改不删、破坏性变更才升版本、核心逻辑一套加适配层、弃用靠 Deprecation/Sunset 头加调用量埋点、CI 里用 schema diff 兜底——这六件事做到位，旧客户端就不会因为你的发版而崩。