做后端开发这么多年，我见过太多团队在API设计上栽跟头。不是接口命名混乱，就是升级不带向下兼容，然后一堆客户端炸锅，最后全员加班救火。

今天不整那些虚的，说点大实话。

先搞清楚你在用什么风格

API版本管理主流就两派：URL路径版本化 vs Header版本化。

URL版本化是这样的：

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

Header版本化是这样的：

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

我的观点：能用URL版本的别整Header那些花活。URL版本肉眼可见，调试方便，curl直接打，浏览器直接看。Header版本看着优雅，用起来全是泪——调试要带额外参数，日志分析要额外解析，排查问题多绕三层路。

版本号不是你想加就能加的

很多人对版本号有个误解，以为想加就加。实际上版本号是有成本的——你每增加一个主版本，就要维护一套旧代码。

什么时候该升主版本？

• Response结构变了，且不兼容
• 某个必填字段被你删了
• 接口语义完全变了

什么时候不该升？

• 加了个可选字段
• 文档写错了，改一下
• 性能优化，逻辑没变

我见过最离谱的团队，三个人维护着5个版本的API，每个版本代码几乎一样，就是改了俩字段。结果呢？bug四处开花，谁都不敢动。

向后兼容才是王道

升级API的原则只有一条：尽量别动老的，让新的自己长。

加字段？完全OK，客户端忽略不认识的字段就行。

改字段？别，改了客户端直接挂。

删字段？先标记deprecated，等两个版本再删。

很多人喜欢在代码里这么搞：

# 错误示范
if (version == 1) {
    return oldUserData();
} else {
    return newUserData();
}

这种写法短期没问题，长期是灾难。版本分支越来越多，代码越来越难维护。

正确的做法是：

# 推荐做法：统一数据结构，内部做转换
def transform_user_data(user, version):
    base = {
        "id": user.id,
        "name": user.name,
        "email": user.email
    }
    if version >= 2:
        base["avatar"] = user.avatar_url
    return base

核心思路是：一个数据结构走天下，版本差异在出口处处理。别在业务逻辑里到处分支判断。

Deprecation通知要到位

很多团队删接口之前一点招呼都不打，客户端第二天直接404。这种做法要么是蠢，要么是坏。

标准流程应该是：

1. Response Header加 X-API-Deprecation-Warning
2. 文档站标明废弃时间和大版本号
3. 邮件/群通知所有集成方
4. 给至少2个版本窗口期再删

你可能觉得麻烦，但想象一下：你的API被几百个客户端调用，突然告诉他们下个月要停服务——他们会怎么看你？

实战建议

最后给几点实在的建议：

第一，接口命名要克制。能用 /users 就别 /getUsersByPageAndFilter。RESTful不是让你把所有SQL关键词都塞进URL里。

第二，用自动化的方式验证兼容性。每次发版前跑一遍接口契约测试，别靠人工review。

第三，版本号要唱出来。你在日志里打的每一个版本号，未来排查问题时能救命。

第四，给客户端留点喘息空间。不要一个月一个主版本更新，客户端开发不是你敌人。

总结

API版本管理不是什么高深学问，本质就是：保持克制、向后兼容、通知到位。

少折腾花样，多考虑用你接口的人。代码是给人看的，API是给人调用的。你自己写的代码都不想维护，凭什么要求别人维护对接你接口的成本？

好好做设计，少加班。