当接口需要变更时，如何在不破坏现有客户端的前提下发布新版本，是每个后端开发者必须面对的问题。常见的策略有三种：URL 版本、请求头协商和字段只增不删。它们各有适用场景，理解其原理和取舍，能帮助你做出更合理的设计决策。
策略一：URL 版本
最直观的方式是在 URL 中显式包含版本号，例如 /api/v1/users 和 /api/v2/users。
优点：
- 一目了然，客户端和调试工具都能直接看到版本。
- 不同版本可以独立部署、独立路由，甚至独立维护代码分支。
- 缓存、日志、监控等基础设施可以按版本区分。
缺点：
- URL 会变得冗长，且版本号与资源标识强耦合，违背 REST 中“URI 标识资源”的部分理念。
- 如果版本迭代频繁，容易产生大量并行版本，维护成本高。
实践建议：
- 仅在发生不兼容变更（breaking change）时递增主版本号。
- 使用
v1、v2这类整数，避免v1.1这种小版本出现在 URL 中。 - 为旧版本设定明确的废弃时间表，并通过
Deprecation响应头或文档告知调用方。
策略二：请求头协商
通过 HTTP 请求头传递版本信息，常见两种方式：
- 自定义头：如
X-API-Version: 2。 - 内容协商：使用
Accept头，如Accept: application/vnd.myapi.v2+json。
优点：
- URL 保持干净，资源标识稳定。
- 更符合 HTTP 语义（尤其是
Accept方式）。
缺点：
- 调试和测试时不如 URL 直观，需要额外设置请求头。
- 浏览器直接访问无法指定版本，不利于快速验证。
- 缓存策略需要依赖
Vary头，否则可能返回错误版本。
实践建议：
- 如果团队内部使用，
X-API-Version更简单直接；若追求标准化，可选用Accept内容协商。 - 务必在响应中设置
Vary: Accept（或对应头），避免缓存污染。 - 当请求头缺失时，应回退到默认版本（通常是当前稳定版），并在文档中说明。
策略三：字段只增不删
这是一种“演进式”兼容策略，不改变版本号，而是通过字段级别的规则保证向后兼容：
- 只增加可选字段，不删除或重命名已有字段。
- 不改变已有字段的类型和语义。
- 客户端应忽略未知字段，服务端应容忍缺失的可选字段。
优点：
- 客户端无需感知版本变化，升级平滑。
- 服务端只需维护一套代码，降低复杂度。
缺点：
- 无法处理语义层面的破坏性变更（如字段含义改变）。
- 长期累积可能导致接口臃肿，包含大量历史字段。
实践建议：
- 在 API 设计规范中明确“只增不删”原则，并写入团队约定。
- 使用 JSON Schema 或 OpenAPI 描述接口，标记字段的可选性和废弃状态。
- 对于确实需要废弃的字段，先标记为 deprecated，保留一段时间后再移除（需配合版本策略）。
如何选择
| 策略 | 适用场景 | 注意事项 |
|---|---|---|
| URL 版本 | 对外公开 API、不兼容变更频繁 | 控制版本数量，制定废弃计划 |
| 请求头协商 | 内部服务、追求 URL 简洁 | 处理好缓存和默认版本 |
| 字段只增不删 | 兼容性要求高、变更以增补为主 | 无法应对语义破坏性变更 |
实际项目中，这三种策略常常组合使用。例如，对外 API 用 URL 版本做大的不兼容变更，同时内部遵循字段只增不删原则减少小版本迭代。关键在于：任何变更都要有明确的兼容性评估和文档记录，让调用方能够平稳迁移。
最后提醒一点：无论选择哪种策略，都应在 API 文档中清晰说明版本规则、废弃策略和迁移指南。技术手段只是工具，良好的沟通和契约意识才是接口长期稳定的基石。