API 优先、API 设计优先和代码优先，该怎么选？

Vano

2023-04-07

原文标题：API-First, API Design-First, or Code-First: Which Should You Choose
原文链接：https://blog.stoplight.io/api-first-api-design-first-or-code-first-which-should-you-choose
作者：Janet Wagner

你有一个有利于业务的关于 API 的绝妙想法，那接下来你会怎么做？

你可以先写出 API 的业务需求，然后对其进行编码。也许你会决定先用一种规范语言（例如 OpenAPI）来描述你的 API；或者，你可以说服你的组织采纳你的 API 想法并将其转变为 API 优先的产品。

最后，你希望提供一个优秀的 API 架构。第一步是决定哪种开发方法可以帮助你做到这一点。让我们来看看这些方法的优点和缺点吧。

构建 API 的三种不同方法

代码优先

「代码优先」通常指的是根据业务需求编写 API 代码，然后根据该代码生成机器可读的 API 定义。它还可能意味着在代码中实现 API，然后使用注释或手动编写来创建 API 描述。「代码优先」的 API 方法并不意味着没有 API 设计，相反，有一个分布在各种代码文档中的设计过程。

API 优先

「API 优先」开发意味着你的组织将 API 视为最重要的资产，并清晰地认识到它是组织运营所依赖的关键业务资产。

这种方法涉及使用 API 描述语言（例如 OpenAPI）编写的规则设计每个 API。从 API 规则开始确保 API 的一致性、可重用性和易交互操作性。「API 优先」公司非常受欢迎，多年来这个术语已经成为流行语。

API 设计优先

「API 设计优先」意味着你在编写任何代码之前，以人类和计算机都能理解的迭代方式描述每个 API 设计。通过「API 设计优先」，每个团队都使用相同的语言并且使用的每个工具都利用相同的 API 设计。

这种方法从参与 API 设计的每个利益相关者开始，编写满足所有各方的 API 合同，还确保产出人类和机器都能理解的成品。通过这种方法，团队会在设计阶段花费大量时间，以确保在开始编码时，他们编写的代码不会被废弃和重写。

每种方法的优点

「API 优先」和「API 设计优先」的共同优势

「API 优先」和「API 设计优先」都强调了设计文档和规则的重要性。它们为 API 设计和开发团队提供可靠的真实来源。这两种方法都要求在编写任何代码之前尽早让利益相关者参与设计过程，从而提供几个优势，如：

并行工作的能力：你可以使用 API 描述文档来创建模拟服务器和模拟 API，这样就可以在部署之前尝试 API 设计并测试 API，而不必等待其他团队完成 API 的不同阶段。
确保积极的 DX（developer experience）：你可以使用 API 描述文档和第三方工具自动生成提高开发人员体验的内容，例如交互文档、客户端库和 SDK。
降低开发成本：在 API 编码后修复问题的成本远远高于在设计阶段修复的成本。你还可以通过跨多个 API 项目重用组件来降低开发成本。

最近随着 ChatGPT 火爆全球，「API 优先」和「API 设计优先」又多了一项优势。感兴趣的话可以看看：API First 再先一步，OpenAPI 定义被 openAI 定为 ChatGPT 插件标准。

「代码优先」的优势

一般来说，在先完成 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 可重用性，那么你应该同时「API 优先」和「API 设计优先」两种方法。

这两种方法都专注于创建 API 规则。因此，如果你实施了一种方法，那么你在你的 API 设计架构中就已经实施了另一种方法的一半。当你同时采用这两种策略时，你会获得它们的所有优势，甚至更多。

以 PayPal 为例。前不久，PayPal 经历了大规模的「API 优先」转型，采用了“API 就是产品”的思维方式，实施了一项战略，开发人员使用 OpenAPI 创建服务规则，然后尽可能按照设计优先的方法构建 API。

PayPal 的团队花了一些时间来重组和简化 API 设计和开发流程。最终，该公司通过采用「API 优先」并遵循「API 设计优先」获得了相当多的好处。好处包括：

开发人员在需要时可以获得客户反馈，使他们能够不断提高 PayPal API 的一致性和质量。
公司通过将所有 API 迁移到 OpenAPI 规范来减少基础架构的投资。
开发人员构建的 API 更容易被外部用户理解和使用。

在最近的 API Intersection 播客中，杰森·哈蒙（Jason Harmon）和亚当·杜万德（Adam DuVander）与 PayPal API 平台负责人杰伊·耶纳（Jay Jena）就 PayPal 的 API 计划进行了交流。杰伊解释说，PayPal 已经建立了详细的设计指南，以确保每个 API 的一致性。他说：“我们有一个标准化的 API 工具蓝图，它使事情保持一致。无论是 REST、GraphQL 还是任何其他类型的 API。”

PayPal 的团队通过对每个 API 的检查，添加团队想要做的一切，例如文档文本、OpenAPI 一致性文本和安全文本。如果请求有任何错误，验证器将不允许它通过，直到开发人员更正它们，确保开发人员遵循 API 设计指南。

你的组织即使不是 PayPal 这样的大型企业，也可以实施「API 优先」和「API 设计优先」来构建 API。

Apifox 允许各种规模的组织实施和简化他们的 API 设计和开发过程。使用 Apifox，你可以按照「API 优先」和「API 设计优先」构建产品，享受更好的 API 体验！