高效码农

什么才是好的 REST API？

如今，任何具备基本编程技能的人都可以构建 API。FastAPI 等框架提供了直观的界面，并且文档齐全，让构建 API 变得非常简单。但是，如何才能交付和维护其他开发人员喜爱的、始终按预期运行且扩展性良好的强大 REST API？

本文提供了 REST API 最佳实践的概述，涵盖：

我不会在每个部分中讲得太详细，但是我会为那些有兴趣深入了解的人提供有关该主题的更多资源的链接。

API 设计：遵循最佳实践

好的 API 具有经过深思熟虑且合乎逻辑的端点设计，以易于使用的方式返回数据，并在出现错误时提供详细的反馈。

目前已有设计 API 端点的最佳实践。这些通常包括：

更多资源：

OpenAPI：自动生成文档和 SDK

好的 API 具有完整的 OpenAPI 规范，可作为 API 提供者与消费者之间的契约。它还用于创建全面的文档和 SDK。

许多 Web 框架都支持从 API 代码库中的端点定义自动生成 OpenAPI 规范，无论是开箱即用还是通过第三方库。您可以使用注释来添加其他详细信息，例如描述和示例。通过与 Web 框架紧密集成来保持单一事实来源有助于使规范与代码库保持最新状态并进行版本控制。

有许多工具使用 OpenAPI 规范来：

更多资源：

推荐工具：

验证

好的 API 会一丝不苟地验证用户输入，并在收到无效输入时提供详细且结构化的错误消息。

作为一项基本任务，许多 Web 框架都很好地支持输入验证。例如，FastAPI 为此使用了 pydantic，并自动生成包含结构良好的验证错误详细信息的响应（见下面的示例）。

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": { ... }
     }
  ]
}

创建验证规则时，请考虑以下标准：

输入验证应尽早进行，并在处理无效请求时快速失败。使用 4xx 范围内的适当 HTTP 状态代码来处理验证错误（例如400 Bad Request）。

一些 Web 框架还可以对 API 响应执行验证（例如，带有 pydantic 的 FastAPI），从而保证返回的数据始终具有正确的结构和类型。或者，API 端点应由自动化测试覆盖，以确保在任何情况下响应数据的格式都正确（根据 API 的规范）。

更多资源：

速率限制

好的 API 采用速率限制来防止过载并确保所有客户端的服务质量。

速率限制可以在堆栈的不同级别实现，包括网络级别、Web 服务器、应用程序代码或这些的组合。

作为第一层保护，大多数 Web 服务器都可以轻松配置为按 IP 地址限制请求速率。为了获得更大的灵活性和更好的控制，您可能需要在应用层实现（额外的）速率限制逻辑。例如，您可以根据用户的定价层应用动态限制。

当由于速率限制而拒绝请求时，最好使用429 Too Many Requests响应状态代码并包含标头，以便Retry-After向客户端提供反馈，以便他们能够优雅地处理速率限制。

确保您的 API 文档清楚地说明了速率限制规则并描述了所使用的速率限制标头。

更多资源：

异步处理

好的 API 使用任务队列和工作系统在后台执行较长时间运行的任务，并避免长时间保持客户端连接打开。

这通常涉及从客户端接受任务，将其添加到任务队列，然后立即发送响应以确认已收到任务并正在处理。202 Accepted响应状态代码通常用于此场景。

这种方法可以改善用户体验，并有助于防止超时，因为客户端无需等待响应。它还允许服务器同时处理多个请求，并在处理长时间运行的任务时保持响应。

API 还应为客户端提供一种方法来检查其任务的状态并获取结果（如果适用）。这可以实现为客户端可以定期轮询的单独端点。

更多资源：

监控

良好的 API 会受到主动监控，以确保其一致的可用性、可靠性和性能。

有了监控工具，您就可以快速检测问题并做出响应，最好是在问题影响用户之前。它还可以帮助您了解 API 的使用方式，并使您能够做出数据驱动的产品和工程决策。

监测至少应涵盖以下关键方面：

更多资源：

推荐工具：

当前页面是本站的「Google AMP」版。查看和发表评论请点击：完整版 »