API版本管理：当我第18次被问这个接口什么时候废弃时的崩溃与反思

凌晨两点，线上告警响了。原因是一个第三方依赖悄悄更新了API，返回的字段从user_name变成了displayName。我的项目毫无防备，集体报错。

那一刻我深刻意识到：API版本管理不是技术问题，是哲学问题——它本质上是问自己：我如何在不杀掉现有用户的前提下，满足未来的自己？

三种版本策略的实战对比

1. URL版本号（最常见，但坑最多）

GET /api/v1/users/123
GET /api/v2/users/123

优点：直观、强制、便于路由。缺点：每次升级都要改URL，改完v1的用户全来找你问你们是不是偷偷下线了。更坑的是，很多团队把版本号当成了功能开关，v2加了新字段就是大版本，结果v3、v4像下饺子一样往下发。

2. Header版本控制（优雅，但调试要命）

GET /api/users/123
Accept: application/vnd.myapi.v2+json

这种方案在HTTP规范里是正确的做法。URL保持干净，版本信息在语义层。但实际开发中你试试：在Postman或浏览器里调试接口，改Header比改URL麻烦10倍。而且很多监控、日志系统会忽略Header里的版本信息，出问题了你都不知道请求方用的是哪个版本。

3. 演化版本（Evolutionary API）——我目前的最爱

核心思想是：不要大版本号，要增量兼容。

GET /api/users/123  # 不变

# 响应逐步演化：
# v1: { "name": "张三" }
# v2: { "name": "张三", "nickname": "小张" }  # 新增字段，兼容旧版
# v3: { "name": "张三", "nickname": "小张", "avatar": "https://..." }

客户端只需要忽略不认识的新字段，旧代码继续工作。新功能通过新增字段实现，而不是改旧字段。

真正的血泪经验：废弃（Deprecation）怎么做

大多数团队废弃API的做法是：在文档里写一行小字此接口计划于某年某月废弃。然后，就没有然后了。

我的废弃流程：

第一阶段：警告期。接口正常返回，但在响应Header里加：Deprecation: true和Sunset: Sat, 01 Jan 2030 00:00:00 GMT。让调用方有据可查。
第二阶段：降级期。对仍坚持调用的老版本，返回额外字段{"deprecated": true, "migration_guide": "/docs/v1-to-v2"}，明确告知下一步该怎么做。
第三阶段：锁死期。只返回错误码410 Gone，Body里写清楚迁移文档链接。这个阶段持续至少一个季度，给所有人足够的反应时间。

GraphQL的降维打击

说到这里，必须提一下GraphQL。它用字段别名彻底绕过了版本问题：

query {
  user(id: 123) {
    name        # v1字段，还保留着
    displayName # v2字段，按需取用
  }
}

但GraphQL不是银弹。它的学习曲线、复杂度、以及N+1查询问题，都需要付出代价。所以很多团队从GraphQL又退回REST了——有时候简单才是王道。

写在最后

API版本管理没有银弹。URL版本号简单直接，适合对外公开的API；Header版本控制适合内部服务间的精确控制；演化版本是长期维护公共API的最佳选择。

最重要的不是选哪种策略，而是建立共识：团队所有人都知道什么情况下该升级版本、什么情况下该新增字段、废弃流程是什么。没有共识，再好的策略都会被玩坏。

下次当你准备在URL里敲/api/v18/的时候，先问问自己：真的需要这个大版本吗？还是加个字段就能解决？大多数时候，加字段就够了。

API版本管理：当我第18次被问这个接口什么时候废弃时的崩溃与反思