标签：优先 示例 成熟度 JSON API 文档 服务器 客户端

API优先开发成熟度框架

Photo by 马雷克·奥康 on 不飞溅

在与软件开发人员的交谈中，我注意到他们中的大多数都声称在他们的 API 开发策略中是 API 优先的。实际上， Postman 的 2022 年 API 状态报告 发现 67% 的受访者在接受 API 优先开发方面的评分为 5 分或更高（0 到 10 分）。

在过去的几年里，我帮助了许多团队构建和交付 API。他们中的大多数声称是 API 优先的。但事实证明，API 优先在每个项目中都有不同的含义。这并不奇怪。 Postman 的 2021 年 API 状态报告包括以下 API 优先定义（括号中为订阅它们的受访者百分比）：

• “在开始开发之前定义和设计 API 和架构”（39% 或受访者）
• “在开发应用程序或集成之前开发 API”（31% 的受访者）
• “在定义和设计 API 之前定义业务需求”（18% 的受访者）

其余 11% 的受访者承认他们不知道 API 优先意味着什么（另外 1% 的受访者回答“其他”）。

尽管围绕 API 优先的含义存在各种不同的看法，但多年来我注意到这一概念的日益巩固。当我有机会与同一个团队长期合作时，我注意到 随着时间的推移，API-first 的定义变得更加清晰 和坚实。随着 API-first 概念的成熟，我也注意到 API 开发方法如何变得更加复杂和标准化。鉴于此，我想提议 用于分析 API 优先开发策略的框架 .我称之为 API优先成熟度框架 （是的，受伦纳德理查森的启发）。

我想明确一点，这是一个分析 API-first 的框架 发展 策略。我一般不会分析 API-first 策略，而是专门关注 API-first 开发： 用于构建 API 的策略 .由于我们首先讨论的是 API，因此框架假设 在开始实施之前，总会有一个 API 设计元素 .但是，没有关于您如何设计 API 或如何以及何时记录它的假设。事实上，这个框架考虑了记录 API 的不同策略，并根据它们的好处和约束来评估它们。讨论还主要集中在 REST 上，因为它是最流行的 API 类型，但根据我的经验，同样的结论也适用于 GraphQL 和其他类型的 API。

在 API 开发的早期，很少有人清楚地知道如何设计和记录他们的 API，API 开发工作流程充满了小问题。我曾经说过 没有 API 服务器能够在与其客户端的第一次联系中幸存下来 .在某种程度上，即使对于最先进的 API 开发工作流程也是如此。然而，强大的 API 开发工作流程的好处不是消除所有集成错误，而是 让您对错误有更多的控制和可观察性，并使您能够更快地修复它们 .

理想的情况是能够提供无论 API 和集成的复杂性如何都能正常工作的 API 集成 .这意味着API客户端和API服务器开发团队都有一个水晶 清楚了解 API 的工作原理 ，并且 API 客户端和服务器都是 针对 API 设计实施和验证 .我评估每个 API 文档方法和每个 API 开发工作流程的成熟度，以帮助我们实现这一理想。

我将分析分为两类：1）API 建模和文档策略以及 2）API 开发工作流程。对于每个类别，我将讨论我在与不同团队合作时发现的最常见的策略和工作流程。在进行分析之前，以下是我将分析的文档策略和开发工作流程的列表：

API 建模和文档策略：

• JSON 示例
• 使用编程语言进行数据建模
• 开放API
• 较少标准的 API 描述语言

API 开发工作流程：

• 先服务端，后客户端
• 代码优先
• 双向测试
• 针对手动制作的模拟开发 API 客户端
• 使用模拟服务器根据规范开发 API 客户端
• 使用合同测试工具根据规范验证服务器

我将从分析 API 建模和文档策略开始，然后分析 API 开发工作流程。我将以总结和讨论来结束这篇文章。

API 建模和文档

API 建模是指设计 API 端点和模式的过程，而 API 文档是指描述 API 设计的过程。在本节中，我将分析我遇到的用于建模和记录 API 的最常见策略。

JSON 示例

通过 JSON 示例，我们以 JSON 示例的形式设计 API 端点及其关联的有效负载。因此，我们没有为有效负载提供模式，而是 有有效载荷是什么样子的例子 .这种方法适用于非常简单的 API。但是，具有包含可选属性或具有多种类型的属性的复杂模式的 API 不容易使用 JSON 示例进行记录——这意味着对于相同的有效负载具有不同的 JSON 示例。当有效负载设计发生变化时，这意味着更新所有 JSON 示例。这种方法存在三大缺陷：

1. 不完整的文件 : JSON 示例通常并不详尽，并且某些情况通常会丢失（特别是对于复杂的有效负载）；生成包含错误的示例也很容易。
2. 维护负担 ：随着 API 设计的发展，我们需要更新所有 JSON 示例。根据我的经验，忘记更新一些示例是很常见的，这最终导致示例集合不可靠。
3. 高信噪比 ：每个有效负载有多个示例，很难了解 API 的实际工作原理。您最终不得不通过整理多个示例来推断模式。

使用编程语言进行数据建模

这是一种非常常见的 API 文档方法。在这种方法中，开发人员枚举 API 端点并使用编程语言（例如 TypeScript）将其有效负载建模为类型。这种方法的吸引力在于定义的模型可以直接在 API 客户端和服务器代码中重用。

如果做得好，这种方法非常强大，因为它允许您定义可重用的模型、可选属性和具有多种类型的属性。它还具有每个人（熟

这种策略的更好版本是模型可以导出到 JSON Schema 或者至少可以用来生成 JSON 示例。对模型的任何更新都可以附带一个 JSON 示例的更新列表，API 客户端开发人员可以使用这些更新列表进行测试。

开放API

这 黄金标准 .这 开放API 创建规范是为了满足 REST API 的文档需求，并且对于它的所有缺陷，它确实很好地描述了 API 的工作原理。
不幸的是，这种方法在自称 API 优先的开发人员中并不像人们预期的那样普遍。这是为什么？当我问软件开发人员为什么不使用 OpenAPI 来记录他们的 API 设计时，最常见的答案是他们发现 OpenAPI 难以理解 并与之合作。

在这种推理的背后，似乎有一个假设，即您必须手动编写 OpenAPI 规范。但是，确实有许多不同的方法可以生成 OpenAPI 文档：您可以使用框架从代码生成文档，或者您可以使用多种工具中的一种来更轻松地生成 OpenAPI 文档，例如 Postman 的 API 构建器 , 失眠的设计师 ， 或者 红绿灯工作室 .
对于不太熟悉 OpenAPI 的人来说，使用文档生成工具非常有效。我想说的是，您必须检查这些工具的输出，以确保它真正符合您想要实现的 API 设计，并进行任何必要的修改。

OpenAPI 拥有庞大的社区和庞大的工具和框架生态系统，可以更轻松地设计、构建、测试和使用 API。一旦您手头有 OpenAPI 文档，您就可以利用这个生态系统并加速您的 API 开发过程。

较少标准的 API 描述语言

关于 OpenAPI 的一个常见抱怨是它难以学习和阅读。因此，多年来我们已经看到了许多 OpenAPI 的替代方案，例如 随机存取存储器 , WADL , API 蓝图 ， 和 其他 .许多这些替代方案的问题在于，在大多数情况下，它们 不是真的更具可读性 或者更容易学习。

更简单的描述语言也倾向于支持较少的记录 API 特性的功能。最后，由于标准较低，这些替代方案具有 较小的社区和较小的生态系统 比 OpenAPI 更多的工具和框架，这导致了糟糕的开发体验。

API 开发工作流程

API 开发工作流是指构建 API 所遵循的过程。对于 API 开发工作流程，最大的区别在于您是否在开始实施之前制定了 API 规范，或者 API 规范是否在您实施 API 之后出现。正如我之前提到的，这个分析是针对 API 优先策略的，所以在所有情况下，我都假设 API 设计中存在一个元素，除了“服务器优先，客户端后”策略。

先服务端，后客户端

在这种方法中，首先构建 API 服务器，然后构建 API 客户端。在 API 开发的早期，这是一种非常常见的方法。令人惊讶的是，这种方法仍然存在。这个想法是 在构建之前，您不知道 API 会是什么样子或它将如何工作 ，因此在实现服务器之前构建客户端是没有意义的。

这种方法通常与 缺乏 API 设计和文档实践 .我记得很多年前就采用了这种方法，这是最令人沮丧的。文档是 API 开发过程的事后想法，您经常不得不绕过端点或深入服务器代码来弄清楚 API 是如何工作的。
遗憾的是，我在首先设计和记录其 API 的团队中也遇到过这种方法。即使文档可用，客户端开发人员仍决定等待服务器实现的原因是因为他们 不要相信服务器开发人员会遵守 API 规范 ，这意味着 API 服务器未根据规范进行验证。这种方法的明显风险是最终导致 API 服务器实现不反映预期的 API 设计。

代码优先

代码优先通常符合以下概念 自记录 API .这种方法在后端开发人员中非常流行。这个想法是使用从我们的代码生成 API 文档的 API 开发框架，并发布该文档。

这种方法的拥护者声称这是 提供可靠的 API 文档并使其保持最新的唯一方法 ，因为它会在您更改代码时自动更新。这种方法的问题在于它假定 API 实现必须是事实的来源 .实际上，这种方法意味着不检查服务器是否符合 API 设计。

这种方法使 API 客户端开发人员的生活变得悲惨，因为新的服务器版本很容易破坏现有的 API 集成。作为 API 客户端开发人员，花费数小时针对服务器测试您的代码非常令人沮丧，只是为了在新的服务器版本中引入 API 的更改。最近 邮政 在 Reddit 中很好地说明了这种方法在客户开发人员中引起的不满。您可以争辩说，更好的团队沟通可以防止此类问题。但是，如果您从事软件工作的时间足够长，您就会知道交流是不够的。你需要有 自动验证 到位。

这种方法的另一个缺点是 API 文档生成工具通常是有限的，有时可能是错误的。例如，大多数框架不允许您创建 OpenAPI 链接。除非您使用框架的特定安全实现，否则记录安全方案也具有挑战性，这可能无法满足您的需求。

双向测试

这种方法在合约测试社区中很流行，并被 契约流 .这个想法是使用自文档框架实现服务器，并使用手动制作的模拟构建 API 客户端进行测试。然后生成后端的 API 规范和客户端的 API 规范。然后你比较两个规范，看看它们是否一致。这种方法的好处是 它强制服务器和客户端之间进行调解 在发布代码之前。

这种方法的缺点是服务器和客户端都不是直接针对 API 设计实现的。这种方法不是使用 API 规范作为唯一的事实来源，而是让服务器和客户端生成自己的规范，并由开发人员来解决它们之间的差异。这可能会在 API 开发过程中造成不必要的摩擦和延迟，并使讨论变得更加困难，涉及 API 每一方的具体实现细节。

针对手动制作的模拟开发 API 客户端

在这种方法中，您 手动创建模拟来构建 API 客户端 .这种方法最传统的版本涉及以 JSON 示例的形式创建模拟响应，而最近 构架 允许您基于这些 JSON 示例和一些额外的自定义配置运行模拟服务器。

这是构建 API 客户端的最传统方法，也是迄今为止最常见的方法，遗憾的是也是最容易出错的方法。正如我们之前所讨论的，JSON 示例往往不完整并且经常出错。它们也是一种维护负担，一旦 API 发生变化，它们就会被弃用。
这种方法最大的局限是它 没有利用完整的 API 规范 ，并且随着 API 设计的变化，JSON 示例和实际 API 之间的偏差可能会越来越大。

使用模拟服务器根据规范开发 API 客户端

在这种方法中，您首先生成一个 API 规范，然后运行 直接根据规范模拟服务器 .然后针对这些模拟服务器构建客户端。 模拟服务器是复制真实服务器行为的假服务器 基于 API 规范。这是 构建 API 客户端的最佳方法 ，因为它为您提供了与真实 API 服务器交互和测试最接近的体验。与使用手动制作的模拟响应等传统方法相比，这是一个很大的优势，因为您不再需要创建和维护 JSON 示例。

根据我的经验，根据规范运行 API 模拟服务器非常有效，尽管 并非所有 API 设计都易于模拟 .例如，返回时间序列数据的 API 很难模拟，其中日期必须是连续的并且在一定范围内。具有设计糟糕的数据模型的 API 也可能很难模拟（参见本文中的示例） 文章 ）。在这些情况下，只要您可以提供示例或附加配置，仍然可以利用模拟服务器。
有许多不同的方式来启动 API 模拟服务器 这是最常用工具的列表：

• 红绿灯棱镜 ：在本地启动简单模拟服务器的最简单方法。
• 微克 ：一个越来越流行的框架，用于在本地和云中运行模拟服务器，具有漂亮的可视化仪表板和许多其他功能。
• 邮差 ：对于那些已经熟悉 Postman 的人来说，这是一个流行的选择，允许与现有的集合集成。
• 线模/模拟实验室 ：API 模拟领域的经典之作，MockLab 允许您使用自己的存根自定义模拟服务器。
• （即将到来） 微API ：在我之前的工作中，我总是在前面提到的工具中遇到恼人的限制，比如无法保存结果、在 API 文档之外添加示例、利用 OpenAPI 链接，或者随机获取具有不同负载的成功和不成功响应以及响应延迟。我目前正在构建 microapis.io 的 mocker 来解决这些限制。

使用合同测试工具根据规范验证服务器

在这种方法中，您首先生成一个 API 规范，然后您 根据规范构建 API ，然后你 根据规范验证您的实现 使用自动化 API 测试工具。这是 构建 API 服务器的最可靠方法 ，因为它是唯一让服务器负责并根据事实来源验证实现的方法。

不幸的是，这种方法并不像应有的那样普遍。它不那么普遍的原因之一是因为它要求您首先生成 API 规范，正如我们之前看到的，这让许多不知道如何使用 OpenAPI 的开发人员望而却步。但是，就像我之前所说的，生成 OpenAPI 规范并不需要很痛苦，因为您可以使用工具来实现。

在这种方法中，您使用自动化 API 测试工具来验证您的实现。像这样的工具 疏通 和 图式 .这些工具通过解析您的 API 规范并自动生成测试来确保您的实现符合规范。他们会查看您的 API 实现的各个方面，包括标头的使用、状态代码、与模式的合规性等。目前这些工具中最先进的是模式，我强烈建议您检查一下。

汇总表

下表总结了前几节的分析，并以 0 到 3 的等级对每个策略和工作流程的成熟度进行评分，0 表示最不成熟，3 表示最成熟。

API 文档方法

正如我之前所说，OpenAPI 是记录 REST API 的黄金标准——它是最广泛支持的文档格式，它为记录 API 特性提供了最高程度的粒度，因此它获得了最高的成熟度分数。

JSON 示例是最基本的 API 文档形式。它们往往不完整和不准确，并且难以维护，因此它们代表了最不成熟的 API 建模和文档类型。
使用编程语言建模更好，因为它迫使您考虑数据模型而不是特定示例，因此得分为 1。
最后，使用适当的 API 描述语言，即使它没有得到广泛支持，仍然比使用 JSON 示例或编程语言模型更好，因此得分为 2。

API 开发工作流程

针对唯一的事实来源进行开发和验证是提供可靠 API 集成的最有效方式，因此“根据 API 规范测试的 API 服务器”和“根据 API 规范测试的 API 客户端”获得最高评价。

另一方面，“服务器优先，客户端后”策略是交付 API 集成的最无效和最不可靠的方式，因为它不验证服务器实现并且很少公开可靠的文档，因此得分为 0。

针对手动模拟的代码优先和 API 客户端是次优的，因为它们不强制执行单一的事实来源，但至少它们具有 API 文档的概念，因此得分为 1。

双向测试迫使我们协调 API 客户端和服务器实现，这是一个确保可靠集成的简洁功能。然而，缺乏单一的事实来源供参考和验证会导致摩擦并使其得分为 2。

结论

API 是现代平台的基本组件，它们使我们能够访问 Internet 上的许多服务。许多企业的可持续性取决于拥有强大且可靠的 API。这就是为什么 投资于可靠的 API 建模和文档流程以及开发工作流程非常重要 .希望本文中的讨论能让您深入了解处理这些任务的不同方式，以及它们如何适应整个选择范围。

虽然我确实偏爱最成熟的 API 文档和开发工作流程，但我认为 立即开始使用它们并不总是容易或可能的 .拥抱 API 设计、使用 OpenAPI 规范和利用合同测试工具需要有时不具备的技能和知识。它们还需要额外的时间和资源投资，而这些投资有时是无法承受的。公平地说，在某些情况下，当您的 API 非常简单且不是业务关键型时，您可能能够摆脱简单的 JSON 示例和简单的开发工作流程。

API 优先开发成熟度框架的目标是让您了解 每种方法的好处和限制 ，因此根据您的具体情况，您可以 评估每种方法的风险并选择最适合您需求的策略 .

如果你喜欢阅读这篇文章并发现它有用，你会喜欢我的书 微服务 API .它教你从头开始构建 API 所需的一切，包括设计、文档、实现、测试、安全和部署！

你可以下载 两章 这本书的 自由的 由此 关联 .

您还可以使用以下代码获取 40% 折扣 买书时： 斯佩拉尔塔 .

我还经营一个非常受欢迎的系列 研讨会 ，免费和付费，我在其中教授构建微服务和 API 的最佳实践。我很想在我的一个研讨会上见到你！此处随时提供即将举行的研讨会的更新列表： https://microapis.io/workshops .

版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明

本文链接：https://www.qanswer.top/22644/18070711

标签：优先,示例,成熟度,JSON,API,文档,服务器,客户端
From： https://www.cnblogs.com/amboke/p/16664724.html