4、API版本管理：版本化策略（URL、Header），向后兼容
API要迭代，接口就会变。这是绕不开的事。
我记得刚做令牌化服务那会儿，第一版上线后，业务方提了个需求：里要加个新的权限字段。我想着挺简单，直接在响应里加了个字段。结果第二天，对方的解析程序直接崩了——因为老客户端不认识新字段，但我们的代码把旧字段的位置给改了。
那次事故让我明白了一个道理：API版本管理不是锦上添花，而是生存底线。
4.1 为什么需要版本管理？
说白了，就是服务端和客户端无法同步升级。客户端可能几周甚至几个月才发一次版，但接口每周都在变。如果没有版本控制，你的每一次改动都可能引发线上故障。
我建议从设计第一天就把版本管理考虑进去。哪怕你现在的接口只有两个调用方，也值得做。因为后面加版本的成本，比你想的要高得多。
核心原则：服务端负责兼容，客户端负责选择。
你永远无法强迫所有客户端升级。所以服务端要能同时处理多个版本的请求。
4.2 两种主流版本化策略
目前业界最常用的就两种：URL路径版本和Header请求头版本。各有千秋，我分别说说。
| 策略类型 | 实现方式 | 优点 | 缺点 |
|---|---|---|---|
| URL路径版本 | /api/v1/ |
直观、易调试、缓存友好 | URL膨胀、违反RESTful资源定位原则 |
| Header请求头版本 | Accept: application/vnd..v2+json |
URL纯净、符合REST语义 | 调试麻烦、文档复杂度高 |
4.2.1 URL路径版本策略
这个最常用，也最容易被接受。我个人的习惯是：
- 用「v」加数字表示版本号，如
v1,v2 - 版本号放在API路径的第一段
- 主版本号变化才改路径，小版本和补丁版本不体现在URL里
# 令牌化服务URL版本示例
GET /api/v1/tokens/{_id} # 第一版
GET /api/v2/tokens/{_id} # 第二版，可能改动了响应结构我的经验：URL版本策略最适合对外公开的API。因为调用方只需要看一眼URL就知道用哪个版本，排错成本最低。
4.2.2 Header请求头版本策略
这种方式让URL保持干净，但实现起来要啰嗦一些。你需要解析请求头，然后路由到对应的处理逻辑。
# 请求头版本示例
GET /api/tokens/{_id}
Accept: application/vnd..v2+json
# 服务端根据Accept头选择返回格式我在一个内部微服务项目里用过这种方案。嗯，怎么说呢？虽然技术上更优雅，但联调的时候翻车率挺高的。开发同学总是忘了加这个头，结果拿到的是默认版本的响应，然后嚷嚷着说接口不对。
注意：使用Header版本时，一定要设置一个默认版本。客户端如果不传版本头，应该返回哪个版本？我建议返回当前最新的稳定版本，同时返回一个警告头，提示客户端显式指定版本。
4.3 向后兼容：版本管理的核心
你想想看，做版本管理是为了什么？是为了不破坏现有的客户端。那怎样才能不破坏？答案就是向后兼容。
我遇到过最典型的场景是这样的：令牌化服务v1版本返回的结构中，expires_in字段是秒数。v2版本我想改成毫秒。如果直接改，v1客户端拿到的值就错了。这种就叫不兼容变更。
4.3.1 什么是向后兼容？
简单说就是：老版本的客户端在不知道新版本存在的情况下，依然能正常工作。
具体到令牌化服务，有几个黄金法则：
- 只加不减：不要删除任何已有的字段或端点
- 只宽不严：输入参数可以放宽限制（比如把必填改成可选），但不能收紧
- 只增不改：新增字段可以出现在响应里，但不能改变已有字段的语义
判断兼容性的简单方法：
如果一个改动导致老客户端的代码需要修改才能工作，那就是不兼容变更。这时候你应该开新版本。
4.3.2 常见的兼容与不兼容变更
| 变更类型 | 示例 | 是否兼容 |
|---|---|---|
| 新增可选字段 | 响应里加了一个_type字段 |
✅ 兼容 |
| 新增接口 | 新增POST /api/v1/tokens/revoke |
✅ 兼容 |
| 删除字段 | 去掉响应里的expires_in |
❌ 不兼容 |
| 修改字段类型 | expires_in从int变成string |
❌ 不兼容 |
| 增加必填参数 | 请求里新增必填的client_secret |
❌ 不兼容 |
| 修改枚举值 | grant_type去掉password类型 |
❌ 不兼容 |
4.4 版本演进的实战策略
策略选定了，代码也写了，接下来怎么演进出新版本？我一般遵循下面这个流程：
- 标记废弃（Deprecate）：在老版本的响应头里加上
Deprecation: true，同时在文档里标注 - 设置过渡期：給调用方一个明确的停止使用时间，比如6个月
- 监控调用量：持续观察老版本的调用量，直到接近零
- 下线版本：停掉老版本，返回410 Gone
# 废弃版本的响应头示例
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2025 00:00:00 GMT
{
"": "eyJhbGci...",
"expires_in": 3600
}千万别干的事：直接删掉老版本的代码。我见过有团队上线v2后就把v1的controller全删了，结果有个遗留系统还在调v1，全线崩溃。保留老版本代码，哪怕只是返回一个统一提示也好。
4.5 画一张图：API版本管理策略总览
下面这张图总结了我们刚才聊的核心内容。你可以把它当做一个决策参考：
4.6 我的建议
如果你正在搭建一个令牌化服务的API，我个人的建议是这样的：
- 对外公开API：用URL版本策略，简单直接，少吵架
- 内部微服务：可以用Header版本策略，前提是你有完善的文档和联调规范
- 无论哪种策略：一定要把向后兼容作为代码review的重点项
一个小技巧：在代码里，我会把不同版本的逻辑放在不同的包或模块下。这样新旧代码物理隔离，不会互相干扰。下线老版本的时候，直接删目录就好。
版本管理这件事，说白了就是「服务端多操点心，客户端少摔点跤」。做得好，用户感知不到版本的存在；做得不好，每一次升级都像拆炸弹。你想想看，你是想让用户夸你接口稳定，还是天天追着你问「为什么我的代码跑不起来了」？