接口版本管理的四种做法，以及各自真正的代价

接口一旦对外，就不再是自家的东西了。版本管理真正要解决的不是"怎么给接口编号"，而是"改动如何在不打断调用方的前提下上线"。这件事有四种常见做法，每一种都在用不同的东西换便利，而换出去的那部分成本往往在一年之后才出现。

一、URL 路径版本：/v1/orders

最直观，也是公开 API 的主流选择。它的优势来自"可见"：任何人拿到链接就知道自己在用哪个版本，浏览器地址栏、访问日志、网关路由表、监控大盘，全都能直接按前缀聚合，缓存键也天然把版本分开了。

代价是 URL 被两个维度占据：资源是 orders，版本是 v1。原本作为资源标识的 URL 从此不再唯一，同一个资源在缓存、限流、鉴权策略里变成多条规则，每加一个主版本就要复制一遍。更现实的问题是"僵尸版本"：因为下线成本高，v1 往往永远挂着，最后是四个版本同时维护。

适合：对外开放接口、移动端客户端（升级节奏不由你控制）。

二、请求头版本：X-API-Version: 2

URL 保持纯粹的资源语义，路由信息放进头部，网关按头部转发，灰度和对照实验都能在这一层完成，不动业务代码。

代价有三条。第一，它在地址栏和浏览器历史里是隐形的，排查问题时必须靠日志额外把头部打出来；第二，缓存必须正确设置 Vary: X-API-Version，漏写就会把 v1 的响应喂给 v2 的调用方，这类事故定位起来极慢；第三，调试门槛高，命令行要手加参数，文档示例也要多写一行。

适合：服务间调用、由 SDK 封装的接口，前提是所有调用方都走统一封装。

三、查询参数版本：?version=2

实现最快，浏览器直接可试，做一次性兼容开关很方便。但参数会进入 URL、进入日志、进入缓存键，还容易被误当成业务参数。更麻烦的是它和签名机制冲突：签名串多了一个字段，所有旧客户端的签名校验都要跟着改。

适合：内部调试、临时灰度开关，不建议作为长期版本策略。

四、媒体类型版本：Accept 协商

形式最正确：版本描述的是表示层，而表示层本来就该由内容协商决定，可以一个资源同时提供多种表示。

代价是实现和心智成本最高。文档工具、网关、限流组件对 application/vnd.acme.order+json;version=2 这类自定义媒体类型支持参差不齐；团队里多数人不会写这个 Accept 头；一旦需要"同一版本不同客户返回不同字段"，这套机制也扛不住，最终还是在业务层加判断。

比选哪种做法更重要的三件事

1. 兼容性优先于版本号。新增可选字段、新增枚举值、返回体里多一个字段，这些都不应该升主版本。把"改动大不大"交给版本号去描述，等于把兼容性判断外包给了直觉。真正稳的做法是：任何改动先进入兼容性检查，而不是先进入版本讨论。

# 把契约检查放在 CI 里，而不是放在评审人的眼睛里
openapi-diff --fail-on-api-change \
    specs/order-api.v1.yaml specs/order-api.v2-draft.yaml

上面这一行命令能拦住的，是人工评审最容易漏掉的那类改动：删字段、改必填、改字段类型。版本号帮不了你，自动比对可以。

2. 没有下线的版本策略，等于一笔无限负债。一个版本至少要有四个状态：引入、稳定、弃用、下线。弃用不等于写一句"已不推荐"，而是要在响应里把信号送到调用方手里：

Deprecation: deprecation="2026-10-01", link="https://example.com/blog/order-v1-sunset", sunset="2027-03-31"
Sunset: 2027-03-31T00:00:00Z

这两个头部的好处是可以被监控：网关按响应头聚合调用量，你就能在真正的下线日期之前一个月看见还剩多少流量。到了下线日再直接返回 410，而不是无限期地"再支持一个季度"。

3. 版本路由要留在网关，不要汄进业务代码。一旦服务内部出现 if (version == 1)，每个版本都变成一份长期分支，测试矩阵乘上版本数。服务应该只有一个当前行为，版本差异靠网关转发到不同服务、或由适配层做一次字段映射。

落地顺序建议

对外接口用 URL 路径版本，内部服务用请求头版本，两套不要混用；把契约比对入 CI，删字段的 PR 直接失败；每个版本上线时就登记好到期日；最后再把"升级引导"做成代码生成或 SDK 变更报告，而不是靠邮件通知。

一句话收敛：四种做法的选择其实不是重点，重点是你能不能把每一个旧版本变成一个有到期日的债务，而不是一个无限续期的默认选项。