做过后端开发的同学，肯定经历过这样的“绝望时刻”：
产品突然跑过来说：“这个接口的返回字段加个新类型，顺便把那个废弃的字段删了吧。”
你心想：“简单，改一下代码，重新部署。”
结果上线不到 5 分钟，运维群里炸锅了：“老版本的 App 全白屏了！”“iOS 1.0 的用户疯狂报错！”
为什么？因为你破坏了向后兼容性。
API 是服务提供方和调用方之间的一份“契约”。一旦契约发布，就不能随便撕毁。那么，当业务真的需要大改时，我们该如何优雅地进行 API 版本控制？今天我们来盘点 3 种最常见的方案。
一、 方案 1：URL 路径版本号（最主流、最直观）
这是目前业界采用最广泛的方案，比如 GitHub、Twitter 的 API。
格式：GET /api/v1/users 或 GET /api/v2/users
优点：极其直观。不管是开发者看文档，还是运维查日志，一眼就能看出当前请求的是哪个版本。路由分发也非常简单。
缺点：从 RESTful 的严格语义来看，版本号不属于“资源”的一部分，稍微有点“不优雅”。
适用场景：绝大多数对外公开的 RESTful API。
二、 方案 2：请求头（Header）版本号（最符合 REST 规范）
这种方案将版本号隐藏在 HTTP Header 中，保持 URL 的绝对纯净。
格式：URL 依然是 /api/users，但在 Header 中添加 Accept-Version: v2 或自定义的 X-API-Version: v2。
优点：URL 极其干净，完美契合 RESTful 理念。
缺点：不够直观。测试人员在用 Postman 或浏览器直接访问时，没法像改 URL 那样方便地切换版本；日志排查时也需要额外关注 Header。
适用场景：对 RESTful 规范要求极高的内部微服务，或大厂的基础架构平台。
三、 方案 3：查询参数（Query String）版本号（最不推荐）
格式：GET /api/users?version=2
优点：实现极其简单。
缺点：参数容易被意外覆盖，且不符合 RESTful 规范，缓存机制也容易出问题。
适用场景：临时过渡，或者极其简单的内部小工具。强烈不建议用于核心业务。
四、 灵魂拷问：什么时候才需要发布新版本？
很多团队滥用版本号，改个错别字也发个 v2，导致维护成本爆炸。请记住以下原则：
🚫 不需要发新版本的“小改动”：
增加新的可选字段：老客户端会忽略不认识的字段，不会报错。
增加新的可选接口：不影响老接口。
修复 Bug：只要返回的数据结构没变，只是数据更准确了，直接覆盖老版本。
⚠️ 必须发新版本的“破坏性变更”：
删除或重命名已有字段：老客户端解析不到字段会崩溃。
修改字段的数据类型：比如把 price 从 String 变成了 Number。
改变接口的核心业务逻辑：比如原来 POST /users 是创建用户，现在变成了“创建并自动登录”，返回值完全变了。
五、 终极建议：能不加版本号，就别加！
维护多个版本的 API 是一场噩梦。你需要同时维护两套代码、两套测试用例、两套数据库兼容逻辑。
最佳实践是：
尽量通过“只做加法，不做减法”来延长 v1 的生命周期。如果实在要废弃某个字段，先在文档里标记为 Deprecated，给调用方留出 3-6 个月的过渡期，等老版本 App 彻底没人用了，再在底层悄悄清理。
