“成功的软件总是会改变。” -弗雷德里克·P·布鲁克斯
对于一般软件而言，同样适用于 API：成功的 API 会发生变化。原因很简单：成功的 API 被各种 API 消费者使用，他们需要新功能、扩展、错误修复和优化。从这个角度来看，API 的变化是不可避免的。
但这只是故事的一半。各种消费者使用 API 并依靠它们来保持稳定。否则，它会破坏他们现有的集成。他们的软件客户端依赖于 API，即使 API 中的一个小改动也足以破坏这些客户端。从这个角度来看，API 的变化是不可取的。
显然，有一个两难选择。解决这个困境是 API 提供者的任务。在这篇文章中，我想给你一些处理它的技巧。
版本控制的生命周期方法
为了有效地处理变更和版本控制，我们需要采用生命周期方法：研究 API 及其从开始和设计一直到退役的处理变化的能力。我希望这不会让你感到意外——应对变化也需要做好准备。这意味着在具体的变更提案出现之前考虑 API 变更方式。
我们可以将 API 的生命周期分为两个主要阶段：发布 API 之前的设计阶段和发布 API 之后的阶段。
在这两个阶段，您必须以非常不同的方式处理变化。事实上，当从一个阶段过渡到下一个阶段时，你对改变的心态需要转换 180 度。
- 发布 API 之前
- 发布 API 之前：欢迎在迭代 API 设计中提供反馈
- 发布 API 之前：为版本控制准备 API 设计模式
虽然最常见的模式将 API 版本控制作为 URI 路径参数来实现，但有多种替代 API 设计模式可以使主要版本可访问：
- Accept 标头中的 API 版本控制：客户端可以使用 HTTP Accept 标头明确指示 API 的版本。Accept 标头仍然像往常一样包含 MIME 类型，但另外附加了版本。API 的 URI 不包含任何版本信息。对于新版本，URL 不会更改，但请求标头会更改。
- API 版本控制作为 URI 路径参数：最常见的版本控制技术使用带有版本号的 URI 参数。
- 自定义 HTTP 标头中的 API 版本控制：可以为版本定义自定义 HTTP 标头。
- API 版本控制作为查询参数：可以为版本定义查询参数。
- API 版本控制作为新的子域：可以为新版本定义一个子域。
- 发布 API 之前：预测未来的变化
发布 API 后
API 发布后，为了您现有 API 使用者的利益，您对 API 变化的态度需要更加保守。需要更严格地管理变革。基本规则是 API 的外部可观察行为（从客户端的角度）一旦发布就不能更改。当然，规则的例外是创建 API 的新版本。
- 管理变革：第 0 步——变革真的有必要吗？
- 管理变更：第 1 步 – 变更是否向后兼容？
向后兼容的变化：
- 添加查询参数（它们应该始终是可选的）。
- 添加标题或表单参数，只要它们是可选的。
- 在 JSON 或 XML 数据结构中添加新字段，只要它们是可选的。
- 添加端点，例如新的 REST 资源。
- 向现有端点添加操作，例如，在使用 SOAP 时。
- 向请求接口添加可选字段。
- 将现有 API 中的必填字段更改为可选字段。
- 移除或更改数据结构，即更改、移除或重新定义数据结构中的字段。
- 从请求或响应中删除字段（而不是使其可选）。
- 将正文或参数中以前可选的请求字段更改为必填字段。
- 将正文或参数中先前需要的响应字段更改为可选字段。
- 更改 API 的 URI，例如主机名、端口或路径。
- 更改请求或响应字段之间的结构或关系，例如，使现有字段成为某个其他字段的子项。
- 向数据结构添加新的必填字段。
- 管理变更：第 2 步——处理向后兼容的变更
- 管理变更：第 3 步——处理重大变更
- 管理变革：第 4 步——日落
为 API 日落设定明确的期望，并尽早将其传达给所有受影响的 API 消费者，让他们尽可能多地处理日落并将其 API 客户端提升到新版本。您必须获取 API 使用者的联系方式，这些信息通常在他们加入时收集。在邮件列表中获取 API 使用者——不是为了营销目的，而是为了产品变化。当 API 的新版本发布时，在邮件列表中向所有 API 使用者发送有针对性的消息，包括关闭旧 API 的时间表。激励您的 API 使用者及时切换到新版本，并说明使用最新版本的好处。
结论
更改 API 的影响可能难以管理。因此，开发人员必须在 API 生命周期的早期做好准备。我们已经看到 API 版本控制在引入第一个重大更改之前就开始了——甚至在 API 最初发布之前。一个设计合理的 API 很可能能够在不破坏修改的情况下继续存在，因为它是迭代设计的，并且已经预料到未来的变化，并且定义了版本控制模式。如果这些更改最终到来，您可以将这些更改归类为向后兼容和破坏性更改。然后，对次要和主要版本做出相应的反应，并最终淘汰旧的 API 版本。