API 设计的版本治理：从 /v1 到无版本演进的取舍

服务端工程系列新篇。API 一旦有外部使用者，版本问题就来了：改个字段名算不算破坏性变更？v2 要不要兼容 v1 的怪癖？什么时候允许删掉老版本？这篇把 API 版本治理的常见策略和取舍规则整理成文。

第一步：定义什么算「破坏性变更」

比想象中细：删字段、改字段语义（类型没变但含义变了）、收紧校验规则（以前容忍的输入开始报错）、改变错误码、改变分页默认值——全是破坏性变更。反过来，加字段、加可选参数、放宽校验，一般算兼容变更。团队要有一份明文的变更分级表，每次 API 改动先过这张表——多数版本灾难源于「我以为这只是小改」。

三种主流版本策略

URI 版本（/v1/orders）：直观、调试友好、网关路由简单。代价是版本僵化——客户端绑死 URI，升级要改代码。适合外部开放 API（版本即契约，清晰压倒灵活）。

Header 版本（Accept: version=2）：URI 干净，版本是协商出来的。代价是可调试性差（curl 要带 header）、缓存层容易忽略版本维度导致串版本响应。内部 API 可用，公开 API 慎用。

无版本演进（Versionless）：只做兼容变更，永远不破坏——加字段可以，删字段永远不行。对使用方非常友好，对提供方是长期纪律税：每个历史决定都变成永久的兼容包袱。适合迭代快、生命周期可控的内部服务；对外 API 用这套，三年后你会有一堆「没人知道为什么还在」的字段。

实践中的混合策略

真实的系统常用「两层版本」：大版本走 URI（v1→v2，允许破坏性重构），小版本走时间戳或内容协商（兼容性追加）。这样既保留了大版本升级的逃生门，又不至于每次小改都动 URI。

废弃（Deprecation）流程：版本治理的核心

加版本容易，退役版本才是治理。标准流程四步：

1. 公告：变更日志+响应头标注（如 Deprecation + Sunset 头，已有标准化提案）——技术手段让客户端机器可读，不只是靠人看公告
2. 观测期：按调用方统计老版本流量，降到阈值（如 <5%）才启动退役——数据驱动，不是拍日历
3. 过渡期：老版本先返回告警头、再返回限流、然后返回错误——逐级收紧给落后者机会
4. 下线后：URI 保留 404 + 指引文档半年——直接复用老 URI 会酿成事故

版本治理的反模式清单

• 「双写双读」永动化：新旧字段同时支持且无退役计划，复杂度指数增长
• 私下定制：大客户要特殊字段就悄悄加在当前版本里，版本失去了契约意义
• 版本即人格：每个开发者都能开新版本，v7 和 v1 的行为差异没人说得清
• 只升不退：版本只加不减，测试矩阵爆炸（5 个版本 × 3 个客户端 × 2 种部署）

给新服务的建议

起步就用 URI 大版本 + 严格的变更分级表，第一个外部客户接入前把 Deprecation 流程写进 API 文档——版本治理是那种「开始时花一小时，省下将来一个月」的典型投资。等到第五个版本再想治理，历史包袱已经重到只能重写。

（服务端工程系列：网关限流 → 可观测 → 熔断降级 → 配置治理 → 灰度闭环 → 缓存一致性 → 本文：API 版本治理）