V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 1927 天前的主题，其中的信息可能已经有所发展或是发生改变。

我在 API 设计中收到的最常见问题之一就是如何对 API 进行版本控制。虽然并非所有 API 都完全相同，但我发现在 API 版本控制方面，某些模式和实践适用于大多数团队。我已经将这些内容收集起来，下面将提供一些关于版本控制策略的建议，该策略将帮助大多数 API 提供商，无论他们是向内部署 API，还是对外的 API。

API 版本真的那么重要吗？

API 是你与 API 使用者之间建立的纽带。正常情况下，你们之间的纽带不会轻易的断开。纽带包括 URI 模式，有效负载结构，字段和参数名称，预期行为以及其他内容。这种方法的最大好处是显而易见的：API 使用者的理解不会变更，应用程序可以保证持续有效。

但是，永久不变是不现实的。有时因为业务变化，你可能需要对 API 进行重大改变。发生这种情况时，最好的方式是，你确保不会做任何会导致 API 使用者修复代码的事情。

打破与不间断的变化

非破坏性变更往往就像是“添加剂”，一般是添加新字段或嵌套资源到资源陈述，又或是增加新的端点，如 PUT 或 PATCH。API 使用者从一开始应该构建能够适应这些非破坏性更改的客户端代码。

突破性变化包括：

1.名字段或资源路径，通常在 API 发布后为了统一命名规范。

2.更改有效负载结构，一般是适应以下内容：

a.重命名或删除字段
b.将字段从单个值更改为一对多关系（比如从一个帐户的一个电子邮件地址移动到这个帐户的电子邮件地址列表）。
c.修改了 API 的 URL，导致返回结果不一致的情况。

简而言之，一旦你将 API 对外公开发布，你就必须保持它是可用的并且不会影响到使用者的。如果您遇到多个项目，则需要对 API 进行版本控制，以防止破坏现有的 API 使用者。

定义 API 版本策略

任何不断发展变化的 API 都需要 API 版本控制策略。你的 API 版本可以适应根据 API 使用者的期望而切换不同版本变得有所不同。我通常建议将以下 API 版本控制策略作为整体 API 管理系统的一部分。

1.如果你的 API 处于早期测试版本中，为了获得消费者的反馈，请建立您的 API 可能会发生变化的正确期望。在此阶段内，你会保留这个版本一段时间，因为你的 API 设计可能还会更改。作为消费者，API 是不稳定的，因此他们应该预期到可能会发生的变化。

2.一旦发布，你的 API 应被视为契约，如果没有新版本，则不能被替换。

3.不间断的更改会导致次要版本出现问题，客户端会自动迁移到最新版本，不会出现任何负面副作用。

4.突破性的变化意味着客户必须迁移到此新版本，因为它包含一个或多个重大更改。你必须与 API 使用者建立适当的时间表并定期沟通，以确保他们能方便地迁移到新版本。但在某些情况下，这可能无法马上实现，所以你的团队将会被要求暂时性支持以前的 API 版本。

何时必须实现 API 版本控制

一旦确定需要新版本的 API，就需要知道如何处理它。实现 API 版本控制有三种常用方法。

1.资源版本控制

该版本是 HTTP 请求中 Accept 标头的一部分，例如，Accept:application/vnd.github.v3+json 发送到 GET /customers。这考虑了许多版本控制的首选形式，因为资源在版本化的同时需要保持 URI 相同。如果未在 Accept 标头中提供，某些 API 会选择提供最新版本作为默认版本。

2.URI 版本控制

该版本是 URI 的一部分，作为前缀或后缀，例如，/v1/customers 或 /customers/v1。虽然 URI 版本控制不如基于内容的版本控制那么精确，但它往往是最常见的，因为它适用于不支持自定义标头的各种工具。缺点是资源 URI 随每个新版本而变化，有些人认为这与拥有永不改变的 URI 的意图背道而驰。

3.主机名版本控制

该版本是主机名的一部分而不是 URI，例如，https://v2.api.myapp.com/customers。当技术限制阻止基于 URI 或 Accept 标头到 API 的正确后端版本时，将使用此方法。

**备注：**无论您选择哪个选项，API 版本都只应包含主要编号。不需要小数字（即 /v1/customers，不是 /v1.1/customers ）。

实现版本控制的工具

使用工具和技术可以从根本上实现 API 版本控制过程。用市场上优秀的 API 编辑器将使技术开发团队能够在更短的时间内生成并切换更多的 API 版本，从而不断改进设计决策。

结合工具进行版本控制是大多数开发过程的重要组成部分。API 设计领域中也有这种能版本控制的工具，实际上，全球范围内 API 服务领域中已经存在一些优秀的 Web API 设计工具。

现在，如 EOLINKER、RAML、Swagger，都提供了出色的编辑工具来支持他们的语言。EOLINKER 采用的是版本对比和重点标注提示，可以清晰的切换、对比。RAML、Swagger 采用的是版本切换，方便程度可能略逊一点。而且只有前者是支持中文的，后两种只支持英文语言。这些 API 编辑器都能轻松地实现 API 版本的控制，使得更容易在更短的时间内切换运行版本。