接口版本控制是让变化可预期、可追溯、可淘汰的工程实践，核心解决接口变更时旧客户端不崩、新需求不卡、测试不重来的问题；包含URI路径、请求头、参数三种控制方式及兼容演进策略。

接口版本控制不是加个“/v1”就完事，而是让变化可预期、可追溯、可淘汰的工程实践。它解决的核心问题是：当接口必须改时，怎么不让旧客户端崩、新需求卡、测试全重来。

URI路径版本控制：最直观，也最常用

把版本号直接写进URL，比如 /api/v1/users 和 /api/v2/users。这种方式一眼就能看出调用的是哪个版本，调试方便，网关路由清晰，文档也容易组织。

适合场景包括：对外公开API、需要明确区分大版本变更、第三方系统接入较多的情况。

• 每个版本可独立定义DTO、校验逻辑和异常处理
• 不同版本控制器物理隔离，避免逻辑耦合
• 注意避免过度拆分——比如为微小字段调整就升v2，反而增加维护负担

请求头版本控制：URL干净，但需客户端配合

通过 X-API-Version: v2 或 Accept: application/vnd.myapp.v2+json 传递版本信息。URL保持统一，缓存更友好，适合内部服务或移动端频繁迭代的场景。

缺点是版本信息藏在请求头里，不直观，测试时容易漏掉，老旧工具可能不支持自定义Header。

• 建议搭配全局拦截器统一解析，避免每个接口重复判断
• 对不带Header的请求，应有明确默认策略（如拒绝或降级到最新稳定版）
• 文档中必须突出标注Header要求，前端SDK最好自动注入

参数版本控制：灵活但风险高

在查询参数里加 ?version=v2。开发和测试时切换方便，URL不变，适合灰度发布或A/B测试。

但它把版本信息混进业务参数，容易被篡改、日志污染、缓存策略混乱，也不符合RESTful资源语义。

• 不建议用于生产环境的核心接口
• 若必须使用，应在网关层校验参数合法性，禁止非法值透传
• 避免与业务参数同名（如已有 ?version=ios15，再加API version会冲突）

兼容演进：不升级版本，也能安全迭代

不是所有变更都需要开新版本。新增可选字段、扩展枚举值、增加响应元数据，这些都可以在不破坏旧契约的前提下完成。

关键在于守住“向后兼容”的底线：旧客户端发请求，能收到结构一致、字段语义不变、状态码行为稳定的响应。

• 删除字段前，先废弃（deprecated）并留出至少一个大版本周期
• 字段类型变更（如string→int）属于破坏性变更，必须走新版本
• 用DTO而非实体类直接返回，便于各版本按需裁剪字段