设计出色API的最佳实践与原则 - James

API 设计的核心是有效的沟通，不仅是开发人员之间的沟通，还包括将产品思维、业务和技术融为一体的沟通。

James Higginbotham 是《Web API 设计原理》的作者和执行 API 顾问。James 还推荐 API Design-First 方法——一种快速且轻量级的基于结果的 API 设计过程——成功设计和交付 API，包括 ADDR 过程和建立 API 边界（与 DDD 相关）。

原则 1：永远不应孤立地设计 API

从设计角度和编码角度重新思考我们处理 API 的方式。放慢脚步，与那些有意见、主题专业知识的各方会面，让他们与我们一起参与 API 设计，而不仅仅是推进代码。而是借此机会将其转变为以更多以产品为导向的体验为中心的东西。

原则 2：基于结果的关注

谁将使用 API 以及他们正在尝试做什么

原则 3：与需求相匹配的设计元素

是否使用 Rest API 风格？我使用 GraphQL 吗？gRPC 怎么样？当我们考虑 API 的设计元素时，我们需要考虑人们将如何使用 API。他们将在什么环境下使用它？它主要来自网络浏览设备、手机、平板电脑、笔记本电脑等吗？是基于语音的吗？是不是我们要与其他系统集成，所以我们需要一些事件？

• GraphQL：它非常适合它的响应深入塑造加工方面，可以制作一个看起来很像数据库复杂的查询，并且我可以非常具体地说明我想要的元素。
• 如果你有一个非常深的资源结构，你有很多嵌套的资源，你不想在查询时进行查询以越来越深入，团队会选择使用 REST 作为基础，并辅以一些 GraphQL。
• 那么也许如果他们需要一些高性能服务来服务通信，他们会决定去 gRPC。通过内置的代码生成加快开发过程，并通过 gRPC 利用 HTTP/2 的一些性能改进来加速开发过程。一些标头和其他内置内容的压缩，以及双向通信。

原则 4：API 文档作为开发人员的 UI

• 作为正在寻找全新 API 的开发人员，参考文档非常重要。参考文档是我们花费大部分时间的地方。

原则 5：API 是永恒的

• 当我们考虑 Web API 时，我们不能只考虑可以重构和更改事物的代码库。只要这一切都开始编译并再次运行，我们就没事了。我们谈论的是分布式系统，其中的许多系统都不受使用它的其他人的控制。因此，那些使用您的 Web API 的人无法控制您作为提供者所做的事情，反之亦然。
• 我们必须制定有关如何管理版本控制（以及）如何处理它的策略，确保我们不会破坏人们，并确保我们不会每周或每个月都创建全新版本的 API。
• 通过不间断更改、附加更改来增强 API 非常棒。那些类型的东西很棒。但是删除东西，重命名东西，那些会破坏使用该操作的人的东西，那些在响应中使用该特定字段的人。
• 重构最终会改变你的 Web API，因为你没有将 Web API 契约与你的实现细节分开，所以你无法让它仍然按照设计的方式工作，即使你已经在内部改变了一些东西。如果您开始引入重大变化，那么您将带来客户流失的机会。

API 设计优先方法

• 相对于代码优先的方法，想想我们如何做一个轻量级、快速的 API 设计优先方法，让我们更接近正确的标记，防止我们编写或设计一个不正确或与真正需要的不匹配的 API，并且仍然快速获得反馈，以便我们并不是在自己的角落里完全孤立地做这件事，而且做出这些改变太昂贵或太晚了。
• 对齐：我们如何确保我们设计的 API 与将要使用 API 的开发人员以及将间接使用该 API 的最终用户对齐？首先要确保我们所有的假设都得到处理，我们不会编写包含错误假设的代码。我们不会设计一个同样具有错误假设的 API。我们了解需求是什么，结果是什么。我们将这些分解到下一个层次，并逐步了解我们需要做什么。然后 API 设计将随之发展。然后我们应用一种或多种 API 样式来设计 API。因此，我们可能会对我们的大部分操作应用 REST 方法。也许提供一个 GraphQL。全部使用定义阶段的输出。一个 API 配置文件，它定义了 API 应该在高层次上做什么。

API 边界和 DDD

• 引入边界，我们可以在其中分割 API 的各个部分。这并不一定意味着您拥有多个 API 产品。这意味着您正在寻找具有凝聚力的不同 API 或不同操作。
• 花时间评估 API 的边界位置将使您更高效，将范围很大的产品或 API 操作的表面区域分解为更容易消化、更易于管理且更易于分解的更小的边界区域由 API 提供商提供。
• 我们使用 EventStorming 作为发现我们可以布置特定流程的好方法，从我们的事件开始，然后开始扩展并找到生成这些事件的命令，然后识别聚合，并详细说明事件风暴过程。通常，这些聚合确实很好地暗示了 API 边界在哪里。
• 我们必须牢记许多 Web API，因为它们通过网络必须比我们的 DDD 代码库更粗粒度，后者往往更细粒度并且可以在进程中运行。因此，当您使用具有 Web API 的分布式架构时，我们不希望有太多的网络流量。我们不想太健谈。所以我们必须开始研究我们如何通过网络进行交互，这是一种不同于我们如何构建独立代码库和流程的架构风格。
• 看看 DDD，我们真的想首先关注聚合，然后让聚合来帮助驱动 API 操作。