在编写RESTful API接入文档时，接口版本管理是决定长期可维护性的关键设计。许多团队在API上线后才意识到版本策略的缺失，导致客户端被迫跟随服务端变动，甚至引发不可用事故。本文直接进入问题，提供基于证据的排查路径与操作步骤。
版本放在哪里？先明确三种常见位置
接口版本管理的第一步是确定版本标识的放置位置。常见方案有三种：URL路径、查询参数、自定义请求头。选择哪种，取决于你的客户端类型与缓存策略。
- URL路径（如
/v1/users）：最直观，便于日志分析和缓存区分，但会污染URL语义。 - 查询参数（如
?version=1）：易于实现，但可能被缓存忽略，导致版本混淆。 - 自定义请求头（如
Accept: application/vnd.example.v1+json）：符合RESTful语义，但调试和日志记录不便。
根据MDN Web开发文档对HTTP语义的说明，HTTP头字段允许自定义扩展，但需注意客户端兼容性。若你的API面向公开互联网，URL路径是最稳妥的选择；若仅内部服务间调用，请求头可减少URL污染。
判断你的客户端环境：决定版本策略
版本策略没有银弹，必须评估客户端类型。以下问题可帮助你做出判断：
- 客户端是否可强制升级？ 若可强制（如内部App），可采用激进策略；若不可（如第三方集成），需长期维护多版本。
- 缓存层是否区分版本？ 使用URL路径时，CDN和浏览器缓存天然区分；使用请求头时，需配置Vary头，否则可能返回错误版本。
- API是否面向长期合作伙伴？ 若是，应提供明确的废弃时间表。
例如，Python官方文档在版本说明中会明确列出每个版本的弃用特性，但API设计可借鉴其思路：在文档中标注每个接口的引入版本和废弃版本。
操作步骤：设计版本兼容性规则
确定版本位置后，需制定兼容性规则。以下步骤供参考：
- 定义语义化版本号：主版本号变化表示不兼容变更，次版本号表示向后兼容的功能新增，补丁号仅修复缺陷。
- 明确不兼容变更的类型：如删除字段、修改字段类型、改变枚举值等。若必须变更，优先考虑添加新端点而非修改旧端点。
- 设置过渡期：在废弃旧版本前，至少提前6个月发布通知，并提供迁移指南。
- 记录每个版本的变更日志：在接入文档中列出各版本差异，便于客户端适配。
以Python为例，其官方文档会为每个版本提供“What’s New”章节，API文档也可模仿此模式，为每个版本提供变更说明。
取舍：多版本并行 vs 单一版本演进
多版本并行会增加维护成本，但能保护存量客户端；单一版本演进可减少复杂度，但要求客户端快速跟进。取舍原则如下：
- 若API是收入核心（如支付接口），多版本并行更安全。
- 若API是内部工具，单一版本配合强制升级即可。
- 若API面向开发者生态，需提供至少两个主版本的支持，并给出明确的废弃机制。
注意，多版本并行时，每个版本都应独立部署，避免共享代码引发隐性依赖。
失败条件与常见误区
以下错误可能导致版本管理失效：
- 版本号放在URL但未规范命名（如
/api/users/1.0与/v1/users混用），导致客户端困惑。 - 忽略缓存Vary头：使用请求头传递版本时，若未设置
Vary: Accept，CDN可能返回错误版本。 - 废弃旧版本时未强制下线：若无限期保留，会增加攻击面（旧版本可能缺少安全补丁）。
- 文档未同步更新：接入文档必须与代码同步，否则客户端按文档调用会失败。
实操：为你的API添加版本管理
假设你正在编写RESTful API接入文档，以下是一个最小可行方案：
- 在URL路径中加入主版本号，如
/v1/users。 - 在文档中为每个端点标注“支持版本”和“废弃版本”。
- 设置废弃策略：至少保留上一个主版本6个月，并在响应头中加入
Deprecation和Sunset字段。 - 编写迁移指南，列出变更点。
例如，若要将 GET /v1/users 的响应字段 name 改为 full_name，可先添加新字段，保留旧字段，并在文档中注明废弃时间。
版本管理与相关接入文档的衔接
版本管理会影响其他接入环节，如负载均衡的路径转发规则，以及HTTPS证书的域名配置。在接入文档中，应明确版本路径与后端服务器组的映射关系，避免路由错误。
参考资料
- Python 官方文档 – 版本管理范例
- MDN Web 开发文档 – HTTP 与 Web 技术参考
延伸阅读