API 设计优先代码优先

API 设计优先 vs 代码优先

Vano

2023-02-01

原文标题：Design First vs Code First
原文链接：https://www.networknt.com/design/design-first/

在使用 REST API 规范格式时，有两种重要的 REST API 开发方法：「API 设计优先」和「代码优先」。「代码优先」是一种比较传统的 API 构建方法，在业务需求确定之后就直接进行代码开发，最终从代码生成文档。而「API 设计优先」主张在编写任何代码之前先设计 API 的文档。这是一种相对较新的方法，但随着 OpenAPI 规范格式的使用而越来越流行。
「API 设计优先」：将需求转化为人类和机器都可读的文档，例如 Swagger 文档，根据该文档生成代码。
「代码优先」：基于业务需求直接对 API 进行编写，然后再从中生成人类或机器可读的文档。
那我们来讨论每种方法的优缺点，以及该如何根据不同情况选择不同方法！

API 设计优先法

当开发人员体验很重要时

一个设计精良的 API 可以为 API 的采用和使用带来奇迹，而良好的设计可以通过「API 设计优先」更好地实现。如果你希望有更多人愿意使用你的 API，那么为开发人员提供良好的体验 (DX) 就很重要。有效的 API 设计可帮助你的最终用户快速了解你的 API 的功能和价值，从而减少他们与你的 API 磨合的时间。具有一致设计的 API 在与你的 API 集成时降低了学习曲线，使其可能具有更高的使用价值和参与度。

在交付关键任务 API 时

当你的 API 的目标受众是外部客户或合作伙伴时，你最优先考虑的就应该是采用「API 设计优先」法。在这种情况下，你的 API 是一个关键分发渠道，你的最终用户可以通过它来使用你提供的服务，而良好的设计在确定客户满意度方面起着关键作用。此类 API 在代表你组织的服务方面发挥着关键作用，尤其是在全渠道生态系统中，信息的一致性和无障碍消费是业务成功的重要指标。

当确保良好的沟通时

API 合同可以作为中心草案，使你的所有团队成员在关于“API 的目标是什么”以及“API 资源的公开方式”上保持高度统一。如果看一份所有人都可以看懂的设计，那么就会更容易发现 API 架构中的错误和问题。在编写任何代码之前发现设计中的问题比在实施到位之后才发现问题要更有效和简化的多。

当分解应用到微服务时

当你将大型单体应用程序分解为微服务时，你需要设计每个服务之间的规则，便于不同的团队独立处理这些服务，以提高生产力。这些规则将帮助团队进行沟通，并确保开发的服务可以集成在一起。

当使用非 REST API 时

当人们谈论「API 设计优先」或「代码优先」时，他们通常是在谈论 REST API，因为大多数 REST API 框架都提供从代码生成文档的功能。如果你使用 GraphQL 或 RPC 构建 API，那么别无选择，你必须手写框架或原型文件，而一个好的框架将帮助你从规则中搭建项目。

当将 API 规范用作接口协议文档时

大部分企业会用 API 规范作为接口协议文档，或者将其作为 IA 的一部分，这样就不需要在 Word 或 Excel 文档中描述接口了。传统的方法是让开发人员读取 Word 或 Excel 文件，把要求转化成代码，但这种方法已经过时了，因为用自然语言描述 API 很容易产生误解。规范的目的是为人类和计算机提供清晰的描述，如果采用「API 设计优先」，那么它就是一份始终与代码保持同步的文档。

当所选框架提供代码生成器时

先创建规范，然后使用代码生成器搭建项目是非常明智的。从头开始项目可以节省大量时间，复制或修改现有项目可能会引入一些很难检测的错误。如果框架已升级到新版本，大多数生成器将提供重新生成具有相同规范的代码的功能。即使规范有所改变，你仍然可以生成一个新项目，然后与旧代码库进行全文比较，将你的代码合并到新项目中。

当框架可以在运行时利用规范

一些框架，例如如 light-rest-4j、light-graphql-4j 和 light-hybrid-4j，可以在运行时加载规范并将其用于基于 JWT 令牌的请求验证和范围验证。在这种情况下，规则不仅用于代码生成，而且是应用程序的一部分，用于在运行时强制执行。

当希望用户并行工作时

使用「API 设计优先」的另一个好处是，你可以使用规范为每个端点生成带有示例的代码。代码生成后，你将拥有一个正在运行的模拟 API，你可以将其打包成 Docker 镜像并交付给要使用的用户团队。这样，消费者和提供者就可以同时进行工作，提高工作效率。在交互过程中，用户团队可能会给出反馈，以便我们可以修改 API 的设计，然后将新的 Docker 镜像再次发送给他们。

当有社区发布 API 时

如果你的组织运营了用户社区，则可以在发布初稿后立即在其发布 API 设计。这将吸引潜在用户和其他团队参与 API 设计的早期阶段。来自这些审查者的反馈将对 API 设计团队有很大帮助。

当采用用户驱动设计时

一些组织采用了用户驱动的设计方式，这意味着所有潜在用户都将参与其中，并提供有关 API 接口的需求。提供者的接口就是所有潜在用户需求的集合。有时，提供者会提供比所有消费者要求的更多的功能，因为他们对数据和业务领域有更多的了解。在这种情况下，设计规范是团队之间沟通的关键部分。

当测试团队并行工作时

为了尽快将微服务交付到生产环境，我们需要在 DevOps 工具链中构建 CI/CD 流水线，并进行单元测试、集成测试、用户规则测试和端到端测试。这些测试非常重要，可以确保服务质量，并为管理层提供持续集成到生产的信心。为了尽早让 QA 团队参与进来，必须有详细的设计规范。如果你想在完成编码后才让 QA 团队参与，那就太晚了。

代码优先法

当交付小型独立 REST API 时

当你处理单个、简单的 REST API 时，有时你可以跳过设计并立即开始编码。代码完成后，你就可以从代码中生成 OpenAPI 规范，或者将其编写为面向用户的文档。在大多数情况下，你将选择一个现有的示例项目，然后在其基础上进行一些修改。对于大型 API，我们可能无法尽早发现某些设计缺陷，直到发布一两个版本到生产环境后才发现。

当 API 框架不支持代码生成时

如果选择的 API 框架没有提供代码生成器，那么先写代码是有意义的。通常会有一个文档生成器，可以根据代码中的注释生成注释规范。即使你已经制作了设计文档，开发人员仍然需要阅读设计并将其转化为代码。

总结

两种方法都有各自的优缺点。但是，对于企业级的 API 开发，建议采用「API 设计优先」。而「代码优先」适用于希望在脑海中创建一个临时 API ，首先启动并运行，然后再重新考虑设计的个人开发人员。