原型优先API设计

API 设计方法的讨论通常分为两大阵营：代码优先和设计优先。每种方法都有不同的权衡，设计优先通常被认为是理想的，但并不总是实用的。

在本文中，我将提出第三种选择，即原型优先，并论证了它结合了其他两种方法的多种优点。

设计优先

如今，设计作为一项独特的活动，在软件开发中并不流行。大多数时候，人们认为软件很容易更改，而且发布新产品的压力总是很大。因此，设计通常被视为应该逐渐出现而不是“完成”的事情。

然而，API 并不总是如此。如果你从事的是为团队、团体或公司以外的人构建 API 的业务，那么糟糕的设计决策的影响可能是严重且长期的。一旦 API 有了客户，你就必须保持向后兼容性和一致性。

考虑到这一点，进行一些前期设计往往是一个好主意，而不是仅仅发布看起来可行的东西并假设以后会找到修复方法。

为什么设计优先失败了

即使您接受上述前提，尽快交付的压力也不会消失。当您的移动、网络或数据开发人员团队正等待新的 API 功能来构建时，您很容易只想尽快发布某些功能，然后再担心设计。这是API 设计优先方法未被受益于此的组织采用或放弃的常见原因。

然后，还有第二个问题：设计（任何类型的设计）只有在有意义的反馈可能的情况下才会得到改进。API 设计可以被检查，并且由此产生一些有用的反馈，但它们不能被使用。软件中的有效反馈通常以一系列“doh！”的时刻出现，当我们实际尝试某件事时，因此我们越早通过将 API 交到消费者手中来启动这一过程，就越好。

这就是为什么我认为 API 设计不应该从白板开始，而应该从原型开始。

那么原型设计有何帮助？

API 原型与设计文档或规范不同，用户可以立即使用。客户端代码已编写，应用功能也已在早期构建。

有了正确的工具，原型的创建、发布和修改应该比真实产品更快、更容易。这意味着可以尽早获得反馈，并将学习成果立即融入设计中进行测试。

即使 API 设计第一次就基本上正确（通常会发生这种情况，对吧？），拥有原型可以使使用团队与 API 生产团队并行推进其功能。

原型设计方法

有些团队会直接在生产代码中以某种形式进行 API 原型设计，即为路由处理程序和数据模型创建最小、无功能或存根的脚手架代码，然后将代码发送到测试环境。他们还可能从代码中生成 OpenAPI，以便记录此设计并促进审核流程。如果您这样做，您可能不一定称之为原型设计，但这本质上就是原型设计。

然而，由于多种原因，这种方法并不理想。

首先，每次对 API 设计的更改都需要经过一个“编码->推送->构建->部署”循环，之后更改才会被其他利益相关者看到。除了最优化的CD 流程之外，在进行一系列设计迭代时，这会增加很多摩擦。

其次，在代码中提供存根响应是有限的。API 制作者是唯一可以增加可用响应范围的群体，这很耗时，无论是在进行更改还是部署更改方面。非快乐路径、错误和故障响应可能很难按需创建，而获取合适的诊断信息可能还需要进一步的努力。

模拟作为原型

API 模拟通常是更好的解决方案。模拟的构建、发布、运行和修改成本本质上远低于运行生产代码的服务（即使在现代无服务器技术堆栈上）。

可以在生产团队和消费团队之间的设计协作会话期间实时生成模拟 API。然后，它们可以立即提供给消费团队开始构建。这可以在生产者做出昂贵的实施决策之前快速反馈 API 设计规范。

某些工具支持从模拟生成 OpenAPI，因此在这些情况下，您可以节省大量创建完整设计规范的精力。您可以专注于添加描述性元素和架构详细信息，而不是从头开始创建整个规范。

在真正的 API 功能发布之后，模拟仍然具有其价值，因为它们可以实现快速、确定性的持续测试——这是当今大多数团队的主要用例。

棕地原型设计

有人反对在生产代码中直接进行 API 模拟和原型设计，因为大多数情况下，我们是在向现有 API 添加功能，而不是创建新 API。我们有一组现有的 API 功能，我们很乐意对其进行测试，我们不想为了模拟新 API 而不得不为所有这些功能构建模拟。

然而，许多模拟工具支持某种基于代理的“部分模拟”模式，即对已实现的 API 端点的调用被传递到测试环境，而仍在开发中的端点则被模拟。对于调用者来说，这些是难以区分的——它们看起来都像一个 API。

长期价值

积极维护的 API 模拟在原型设计阶段之后仍会继续为 API 使用者提供价值。即使 API 的生产实现可用，使用模拟测试使用代码也有很多好处。好处包括更快更可靠的 CI 构建、轻松的故障和混乱测试以及减少数据设置工作量，等等。

很多时候，使用团队会创建他们不拥有的 API 的模拟，以获得这些好处。在较大的组织中，由于多个使用者模拟同一个 API，这会导致重复工作。在这种情况下，拥有 API 的团队提供的维护良好的模拟对提高工作效率大有裨益。

此外，对于向客户发布 API 的组织，模拟可以通过提供低摩擦访问他们可以开始集成的环境并展示特定的交互（特别是在类似生产的沙箱中难以可靠重现的次要路径和悲伤路径），显著增强消费者的开发体验。

总之

制作设计良好、易于使用的 API 对企业成功越来越重要。使用模拟进行 API 原型设计提供了一种在以 API 为中心的公司中平衡上市时间、生产力和质量的方法。

文章来源：Prototype-First API Design