API 版本控制
API 版本控制是让 API 在长期演进中既能迭代创新、又不破坏既有客户端的工程实践。一个对外发布的 API，一旦有客户端依赖，任何「破坏性变更」（删除字段、改字段类型、改参数必填性、改语义）都会让这些客户端崩溃——而 API 又必须随业务演进。版本控制的核心矛盾：稳定性（旧客户端不能挂）vs 灵活性（API 要能改）。理解三大主流版本策略——URL 版本控制（/v1/users）、Header 版本控制（Accept-Version: 1）、媒体类型内容协商（Accept: application/vnd.api+json;version=1）——以及配套的语义化版本（SemVer）、废弃策略（deprecation）、向后兼容原则，是设计可演进、对客户端友好 API 的基础。版本控制没有银弹，每种策略都有取舍（URL 显式但丑、Header 干净但难调试、内容协商优雅但复杂），关键是团队理解利弊后一致执行。
API 版本控制的全部考点围绕策略与生命周期展开：①三种策略（URL/Header/媒体类型）——回答「版本信息放哪」；②语义化版本（SemVer，MAJOR.MINOR.PATCH）——回答「版本号怎么定」；③废弃策略（@deprecated、Sunset 头、迁移窗口）——回答「旧版本怎么退场」；④向后兼容（什么算破坏性变更、如何尽量兼容）——回答「何时必须升版本、何时不用」。本叶是 API 设计章的演进基石，讲清版本控制的策略选型、语义化版本、废弃与迁移——与 REST、GraphQL、OpenAPI 三叶共同构成完整的 API 设计体系。
评价
优点
- 保护既有客户端：破坏性变更放新版本，旧客户端继续用旧版本不被中断
- 支持并行迭代：新旧版本可同时运行（路由层分发），给客户端迁移窗口
- 显式契约：URL 版本让客户端明确知道自己依赖哪个版本的契约
- 配合文档：每个版本对应一份文档（OpenAPI spec），降低理解成本
缺点
- 维护成本翻倍：多个版本要同时维护（bug 要在所有版本修，或写适配层），团队负担重
- 版本爆炸：没有强制退役策略时版本越积越多，最终变成「历史包袱」
- 策略争议：URL vs Header vs 媒体类型各有利弊，社区无共识，团队易陷入争论
- 客户端惰性：客户端不愿升级（「能用就不改」），旧版本迟迟退不了场
本叶地图
- 入门 —— 版本控制的必要性、三种策略概览、语义化版本、向后兼容速览
- 版本控制策略 —— URL/Header/媒体类型内容协商三种策略的详细对比与实现
- 废弃策略与迁移 —— 废弃通知、Sunset 头、迁移窗口、向后兼容原则
- 参考 —— 策略对比速查、破坏性变更清单、易错点