实践案例：通过 API 优化加快上市时间

案例背景

作者曾为一家初创公司的新产品打造 MVP（最小可行性产品）。MVP 的想法非常简单：需要使用单页应用（SPA）框架构建一个小型用户界面，以及一个公开 REST API 的 WEB 服务，API 主要用于与 SPA 和战略业务合作伙伴集成。

但作者在项目实际启动后，遇到了一些严重的问题：

1. 缺乏完整的 API 文档和规范：

· API 文档不完整、错误百出，无法作为准确的参考。

· 没有约定的 API 测试流程，导致后端开发团队可以在未经通知的情况下随意更改和发布 API。这种变动经常是 bug，并且破坏了与 API 客户端的集成。

2. 不恰当的 API 框架和验证：

· 后端团队使用了不适当的 Flask 框架，并自行实现了复杂的有效负载验证，其中大部分没有经过测试。

· 验证部分代码数量庞大，包括日期、时间戳和字符串格式验证，但没有经过充分测试，这严重拖慢了项目进度。

因此，解决上述问题就需要修复和完善 API 文档，确保其准确性和完整性；建立适当的 API 框架，以提高代码质量和可测试性；设立严格的 API 规范，防止不符合规范的版本发布。

修复 API 设计和文档

从上面暴露出来的问题可以看出，该开发团队对 REST API 的最佳实践和 OpenAPI 规范并不了解。因此，开发团队需要先理解 OpenAPI 及其工作原理，将 API 文档整合到 OpenAPI 规范中，从而更清晰地理解 API 的预期行为。

在将文档整合到 OpenAPI 规范的过程中，我们发现了许多先前 API 设计中的问题。例如，以前采用的自定义日期格式需要在服务器和 UI 中使用自定义验证逻辑。我们转而采用 OpenAPI 支持的 ISO 标准来表示日期，解决了这个问题。

另外，一些模式过于灵活，导致验证几乎失效。为了改进验证，我们重构了这些模式，并为每个实体创建了一个具有不同端点的模型，使其更具可用性。

之前设计中不适当地使用了 HTTP 方法和状态码。团队只使用 GET 和 POST 方法，所有响应都返回 200 状态码。这种不当的使用使得在尝试创建、删除或更新资源时变得不清晰。为了解决这个问题，我们重新定义了 HTTP 方法的使用，并正确返回适当的状态码，以便更准确地表明请求的成功或失败。

此前设计的另一个限制是“端点重用”。虽然看似节省代码，但实际上它公开了太多实现细节。所以要强调先设计 API，再考虑实现的理念。

将 API 规范与 OpenAPI 合并是项目的一个重要转折点。此后，我们能够在与后端集成之前运行模拟服务器来构建和测试 UI，也能够根据规范验证后端实现。我们采用 Prism 运行模拟服务器，并使用 Dredd 验证服务器实现（虽然我现在更倾向于使用 Schemathesis）。这使得项目能更清晰、更高效地发展。

修复 API 的发布过程

即便有了 API 文档，但在发布前没有针对 API 规范跑通测试，文档的作用也会变得有限。尽管文档本身能帮助我们理解 API 的运作方式，但其真正强大之处在于它作为验证工具的功能——验证服务器的正确实现。

为确保 API 服务器按照预期运行，我将 Dredd 测试套件纳入了持续集成服务器中。除非通过了 Dredd 验证并符合 API 规范，否则没有人能够将新代码合并并发布，这一步让团队避免了对 API 服务器的不经意修改。从此，所有对服务器的更改都需事先记录，并确保 API 服务器在合并或发布前遵循这些更改。这种做法保证了服务器的稳定性和一致性。

选择适合的 API 开发框架

此前团队在 API 服务器上采用了 Flask 框架来实现，这是一种用于构建 Web 应用程序的流行 Python 框架。他们以基础的 Flask 构建 API，并编写了大量自定义代码来验证 API 有效负载。这是许多经验不足的 API 开发人员常见的一个错误。

构建自定义 API 验证层并非不可取，但过度依赖此方法可能导致重复造轮子。API 需要复杂的验证逻辑来处理有效负载和 URL（路径与查询参数），这些逻辑必须贯穿整个 API。因此，如果坚持自建 API 验证层，最终会产生一个 API 框架。然而，现有许多优秀的 API 开发框架可供选择，为何不选择其中之一呢？

特别是针对 Flask，有多种选择可供考虑。但并非所有框架都一样。例如，flasgger、restx（flask-restplus 的后继产品）、flask-RESTful 和 flask-smorest 等。在这么多选择中，如何做出决策呢？

在选择 REST API 开发框架时，主要考虑以下因素：

· 支持 OpenAPI：框架应允许轻松构建 REST API 并自动生成 API 文档，确保有效载荷验证的正确性。可参考框架有 Flasgger 和 flask-smorest。

· 健壮的数据验证：验证有效载荷需要强大的数据验证库来处理各种属性和类型。库应支持可选和必需的属性，如字符串格式（ISO 日期和 UUID），以及严格和宽松的类型验证。在 Python 生态系统中，pydantic 和 marshmallow 是优秀的数据验证库，Flasgger 和 flask-smorest 可以使用 marshmallow。

· 全面验证：框架应支持请求有效载荷、响应有效载荷、URL 路径参数和 URL 查询参数的验证。某些库可能只验证请求有效负载，而忽略 URL 参数或响应有效负载。确保框架提供至少一种方式来强制执行验证规则。如果使用 marshmallow，可直接使用其模型验证响应有效负载。

· 成熟度：选择成熟、稳定且拥有活跃社区支持的库。它应具备良好的文档和快速解决用户问题的能力。

根据以上因素评估后，选择 flask-smorest 这款 Flask 插件，支持使用 marshmallow 轻松构建 REST API 的数据验证。能够简化数据验证流程，减少了自定义代码量。现在，请求和响应有效载荷都得到了正确的验证，并且 marshmallow 也处理了 URL 查询和路径参数的验证。

选择合适的 API 框架让我们拥有了一个正常运作的 API。由于框架能够处理 API 层的细节，我们能够更专注于业务逻辑和应用程序的数据模型，从而提高了开发速度并且能够更频繁地发布更加优质的软件。

综合考量以构建卓越 API

在当下的互联网，API 无处不在且无可避免。然而，真正构建良好的 API 却是一项复杂的任务，与编写可读性强且易于维护的代码一样，构建高质量、易用且易于修改的接口也是 API 开发中的挑战。

提供优质 API 是有难度的，因为它需要与业务需求保持一致，即客户端和服务器端必须使用相同的约定和规范，否则集成将难以实现。

实现这一目标需要考虑多个方面：收集客户需求，将需求转化为技术细节，设计 API，编写文档，选择合适的 API 框架并正确使用它，测试 API，并确保实现符合设计规范。这还不包括 API 的安全性、部署和操作等方面。

对于构建关键业务 API，建议是不要让初级开发人员单独承担。他们可以参与，但需要高级开发人员来指导他们的工作。如果没有 API 开发经验，就遵循最佳实践路径：先设计 API，再编写文档，按照规范进行实现，并对其进行验证。不要重新发明轮子，选择合适的框架！

尽管学习 OpenAPI、了解 API 测试框架、研究 API 开发框架等可能需要付出一定时间成本，但这是值得的。如若不然，则会陷入 API 集成和软件质量问题的恶性循环，这将阻碍项目进展并造成巨额成本来修复问题。

如果本身资源充足且拥有经验丰富的 API 开发人员，正确构建 API 的概率大幅提升，且能节省下大量的资金。除此之外，还要重视 API 的管理，很多问题不仅在于前期的开发与支出成本，开发过程中隐藏的代码问题、负责员工的离职交接不清都可能造成隐患。因此幂简集成认为，API 的管理可以借助第三方工具一站式管理 API，多角色参与，避免责任推诿，还可以提升开发效率。

原文链接: Faster time-to-market with API-first | by Jose Haro Peralta | Medium --- api优先加快上市速度| Jose Haro Peralta | Medium