API版本管理是接口迭代中不可避免的问题。没有版本管理的API会在变更时破坏已有客户端，导致线上故障。合理的版本管理策略能平衡创新和稳定，让新旧版本和平共处。本文对比几种常见的版本管理方案。
URL路径版本
最直观的版本管理方式：/v1/users、/v2/users。版本号前置在URL路径的第一个位置。优势是清晰直观，客户端和中间件都能轻松区分不同版本。缺点是不符合RESTful规范中URL代表唯一资源的理念。版本号使用整数，不推荐语义化版本。大版本迭代需要同时维护多个版本的代码，增加维护成本。适合外部API和长期维护的接口。
请求头版本
通过自定义请求头指定API版本：Accept: application/vnd.company.v2+json 或 X-API-Version: 2。请求头版本的URL是干净的，符合RESTful原则。缺点是调试不方便，浏览器中设置请求头比较麻烦。网关可以根据请求头路由到不同版本的后端服务。请求头版本对客户端不透明，客户端需要额外配置请求头。适合内部服务和有统一客户端的场景。
查询参数版本
通过查询参数指定版本：/users?version=2。实现简单，URL可以直接在浏览器中访问测试。缺点是污染了查询参数空间，容易和业务参数混淆。而且查询参数版本容易被客户端忽略，导致使用默认版本。查询参数不适合作为版本管理的主要方式，但可以作为降级方案或在临时测试中使用。
向后兼容策略
无论用哪种版本管理方式，向后兼容是基本要求。兼容原则：不能删除已有字段，新增字段使用可选的，响应中不改变已有字段的数据类型和含义。请求参数增加可选参数，不改变已有参数的必填状态。如果需要破坏性变更，创建新版本，旧版本维护一段时间后按照废弃策略下线。客户端迁移需要给出明确的迁移指南和时间窗口。