4. 版本控制策略：路径、Header 与查询参数
接口版本控制，这问题几乎每个做 API 的团队都会遇到。你想想看，只要系统上线了，总会有新需求要加，旧字段要改，甚至整个逻辑要重构。但客户端又不能说升级就升级。怎么让新旧版本和平共处？我来聊聊三种主流方式。
一句话总结：路径版本最直观，Header 版本最优雅，查询参数版本最灵活但也最容易被滥用。
4.1 URL 路径版本（Path Versioning）
这是最常见的方式。直接把版本号塞 URL 里，比如 /v1/users、/v2/users。我几乎可以断定，你看过的百分之八十的公开 API 都在用这招。
为什么这么流行？说白了，简单粗暴。任何人看一眼 URL 就知道用的是哪个版本。发请求、打印日志、排查问题，版本号一目了然。你在浏览器里直接就能测试，不需要额外的工具。
但问题也明显。资源版本和业务语义绑死了。你改了 /v2/users，那 /v1/users 的代码就要一直维护着。时间长了，代码里全是 v1、v2、v3 的 Controller，臃肿得不行。
我个人习惯：做对外公开 API，或者移动端 API，我倾向于用路径版本。理由很简单——对调用方最友好。前端同学不用关心 HTTP Header 怎么设，直接改个 URL 路径就完事。
GET /v1/users/123
GET /v2/users/123 # 返回结构变了
注意：路径版本一旦发布，就别再改。你发布的是 /v1/users，就得一直活到死。我在项目里就见过一个团队，v1 上线后觉得字段命名不好，直接改了返回体，结果安卓端硬生生崩了一周。
4.2 Header 版本（Header Versioning）
另一种思路：URL 不变，版本号放请求头里。常见的做法是用自定义 Header，比如 X-API-Version: 2，或者用 Accept Header 配合自定义 media type。Accept: application/vnd.mycompany.v2+json。
这种方式的好处是 URL 干净。一个 /users/123 永远都叫 /users/123，语义纯粹。版本决策由服务端根据 Header 来做。你还可以在网关层统一处理，甚至做内容协商。
问题在哪？不可见。你发个请求，别人看 URL 不知道你用的是哪个版本。排查问题时，你得先把请求头翻出来，看版本号设对了没。调试也麻烦，用 curl 得额外加 -H。
避坑指南：我曾经在一个项目里用 Accept Header 做版本，看起来很完美。结果上线后发现某个老版本的客户端居然没设 Accept 头，默认回到了 v1。但那批数据格式已经变了，直接 406。嗯，这里要注意：一定要有默认版本兜底。
| 维度 | URL 路径版本 | Header 版本 | 查询参数版本 |
|---|---|---|---|
| 可读性 | ★★★★★ | ★★☆☆☆ | ★★★★☆ |
| 调试便捷度 | ★★★★★ | ★★☆☆☆ | ★★★★☆ |
| URL 资源语义 | ★★☆☆☆ | ★★★★★ | ★★★☆☆ |
| 网关统一处理 | ★★☆☆☆ | ★★★★★ | ★★★☆☆ |
| 浏览器直接测试 | ★★★★★ | ★☆☆☆☆ | ★★★★★ |
4.3 查询参数版本（Query Parameter Versioning）
URL 里加个 ?version=2。简单吧？确实简单。你甚至可以不用改路由，只改接口实现就行。
但问题也很大。版本号被当成了业务参数，容易混淆。比如你有个搜索接口 /search?q=hello&version=2，那 version 是版本号还是搜索参数？想优雅地做缓存也很难，版本参数变了，缓存键就得跟着变。
我建议：这个方式只适合临时过渡、内部工具、或者快速原型。千万别用到生产环境的对外 API 上。不然你迟早要被调用方追着问——明明 URL 和参数都对，为什么结果不一样？
GET /users/123?version=1
GET /users/123?version=2 # 你可能以为还是同一个接口
如果你非要用查询参数版本，记得在文档里高亮标注：版本参数和业务参数是两码事。还有，参数名不要叫 v，容易和别的东西冲突。我习惯用 api_version，清晰一点。
4.4 决策树：到底怎么选？
我相信你看到这里已经有点烦了。三种方式，各有优劣，到底选哪个？我个人有个简单的判断标准：
- 对外公开 API：路径版本。调用方最省心，排障成本最低。
- 内部服务间调用：Header 版本，或者直接用语义版本协商（比如 gRPC 那样）。
- 你说了算的单一客户端：怎么都行，但我建议养成好习惯，选路径版本。
- 千万别用：生产环境的对外 API 用查询参数版本。除非你只是临时用一下。
我遇到过一个更复杂的场景：同一个 API 既服务 Web 端又服务移动端，Web 端跟得紧，移动端落后两版。最终我的方案是：URL 路径版本作为主版本标记，配合 Accept Header 做小版本微调。主版本用路径，微调用 Header。分离清楚。
4.5 我踩过的坑：版本与兼容性
最后聊点进阶的。版本号怎么设计？我个人习惯用 major.minor 的思路，但落在 API 上只暴露 major。小版本变动不改版本号，只在字段可选的情况下做后向兼容。
比如 v2 要加一个字段 email_verified，这是向后兼容的。我不会因此改成 v3。但如果我要把某个必填字段改成选填，或者改变字段类型，那就必须升主版本。
还有一件事：版本和兼容性策略要配套。你选择了路径版本，就必须接受同时维护多套代码。你选择了 Header 版本，就必须有完善的文档告诉调用方怎么设 Header。没有的好坏。
别忘了降级策略。新版本出问题怎么办？你能不能快速切回旧版本？我曾经一个项目，v2 上线后发现数据迁移有 bug，但因为版本路由在网关层统一控制的，直接切回 v1，前后只花了 5 分钟。这个能力一定要有。
好了，版本控制策略就聊这么多。三种方式没有银弹，关键是结合自己团队的交付节奏和客户端兼容能力来选。我个人最推荐路径版本起步——简单、清晰、不容易出事。等你规模大了，再考虑用 Header 或者混合策略。