接口版本控制是每一个走向成熟的系统都必须面对的问题。随着业务迭代，接口的字段增删、行为变更不可避免，如何在演进过程中保障已有调用方的正常运作，是版本控制策略要解决的核心问题。本文对四种主流方案进行分析，帮助团队做出合理选型。
URI 路径版本
在 URI 中嵌入版本号是最直观的做法，形如「/v1/users」或「/v2/orders」。这种方案的优势在于一眼可见版本信息，调试和日志追踪非常方便，缓存层也不需要特殊处理。缺点是版本号暴露在路径中，当接口迁移到新版本时，旧路径仍需维护，路由表会膨胀。
URI 版本适合面向外部开发者的公开 API，因为外部调用方对接口的感知主要依赖路径，版本信息显式化能降低接入门槛。多数大型平台的公开 API 都采用这种方式，说明其在实践中的可靠性得到了广泛认可。
查询参数版本
通过查询字符串传递版本号，例如「/users?version=2」。这种方案不污染路径结构，版本切换只需要修改参数，灵活性较好。但缺点同样明显：版本信息容易被忽略，中间代理缓存可能无法正确区分不同版本的响应，且参数与业务查询条件混在一起容易造成混淆。
查询参数版本适合内部系统或版本差异较小的场景，不建议在公开 API 中作为主方案使用，因为它的可发现性较差。
HTTP Header 版本
通过自定义 Header 携带版本信息，例如「Accept-Version: v2」或利用 Accept 头的媒体类型参数「Accept: application/json; version=2」。这种方案保持了 URI 的纯洁性，符合 REST 的超媒体理念，版本信息与内容协商统一在 Header 层处理。
缺点是调试不便，开发者无法直接从 URL 判断调用的接口版本。此外，部分客户端框架对自定义 Header 的支持有限，可能需要额外封装。Header 版本适合对 REST 纯洁度有较高要求的团队，且调用方技术能力较强的情况。
内容协商版本
利用 Accept 头的媒体类型传递版本，是 HTTP 协议本身提供的标准机制。例如「Accept: application/vnd.company.user.v2+json」，这种写法在 GitHub API 等知名项目中有实际应用。它的最大优势在于完全复用 HTTP 内容协商机制，理论上最为规范。
但现实中这种方案的复杂度最高，客户端构造 Accept 头的门槛大，文档编写也更繁琐。除非团队对 HTTP 协议有深度理解和统一的工具链支撑，否则不建议作为首选方案。
选型建议与迁移策略
综合来看，URI 版本是性价比最高的选择，适用于绝大多数场景。对于内部微服务间的调用，Header 版本可以避免路由膨胀。无论选择哪种方案，关键在于建立明确的废弃流程：新版本上线后设定旧版本的过渡期，在响应头中标记废弃提示，定期监控旧版本的调用量，当调用量降至阈值以下时正式下线。
灰度迁移方面，可以采用网关层的流量分流，按调用方标识或比例逐步将请求切换到新版本。同时做好回滚预案，一旦新版本出现严重问题，能够快速将流量切回。版本控制不是一次性工作，而是系统演进中的持续实践，需要团队在规范和工具上同步投入。