📌  相关文章
📜  REST API 设计的最佳编码实践

📅  最后修改于: 2021-10-19 08:20:26             🧑  作者: Mango

JSON、端点、邮递员、CRUD、Curl、HTTP、状态代码、请求、响应、身份验证、

如果您从事后端开发并且从事过 API（应用程序编程接口），那么您对所有这些词都很熟悉。作为一名开发人员，您可能从事过某种 API（尤其是那些有经验的开发人员）。可能是支付网关 API、谷歌地图 API、发送电子邮件 API 或任何其他类型的 API，具体取决于应用程序的类型和要求。

休息 API 设计的最佳编码实践

很多时候，开发人员阅读 API 的文档部分并实现它，但在他们的应用程序中实现任何类型的 API 时，他们并不专注于构建一个干净、可理解和可扩展的架构。当应用程序随着时间的推移而增长时，这些事情会对系统产生很大的影响。

考虑这样一个场景，您已经构建了一个应用程序，现在您需要向用户公开界面。你真的认为你们会坐在同一张桌子上吗？你认为他们会理解你试图在你的系统中描述的东西吗？

在构建 Restful API 时，正确设计它以避免应用程序中的任何错误或问题非常重要。您需要关注 API 使用者的性能、安全性和易用性。遵循一些良好的约定来构建干净、易懂且易于使用的 API 是很好的。

在应用程序中构建 Restful API 时，需要考虑很多方面。在本博客中，我们将详细介绍这些方面。让我们讨论在您的应用程序中构建 REST API 的最佳编码约定。

1.端点的名称应附有HTTP方法

作为后端开发人员，您可能熟悉在应用程序中执行 CRUD 操作的各种 HTTP 请求方法，尤其是常见的GET、POST、PUT、DELETE 和 PATCH 操作。如果你不熟悉 使用这些方法然后阅读博客 HTTP 请求方法。

在实现 API 时，请确保与资源链接的端点的名称与与您在应用程序中使用的操作相关的 HTTP 方法一致。请看下面给出的示例以供参考…… 

- GET /get_customers
- POST /insert_customers
- PUT /modify_customers
- DELETE /delete_customers
+ GET /customers
+ POST /customers
+ PUT /customers
+ DELETE /customers

2.根据我们API的结果返回标准错误码

在实现 API 时，端点会返回操作是否成功的结果。结果总是与一些状态代码相关联。例如：如果您获得状态 200（ok），则表示结果成功，如果您获得状态代码 400（错误请求），则结果失败（您可以使用 Postman 等工具检查响应以获取知道您在应用程序中执行的操作的状态代码）。

优雅地处理错误并返回 HTTP 响应代码以指示生成的错误类型。这有助于 API 维护人员了解问题并对其进行故障排除。

确保您知道现有状态代码以识别您需要应用它们中的每一个的情况。有时会发生返回消息与状态代码不匹配的情况，这会给开发人员以及使用该 REST API 的消费者造成混淆。这对应用程序确实有害。因此，最好处理您在应用程序中执行的操作的状态代码。下面是其中一个例子…… 

// Bad, status code 200 (Success)
// associated with an error object
{
    "status": 200,
    "error": {...}
}// Good
{
    "status": 200,
    "data": [...]
}

下面给出了一些常见的错误代码……

  • 00 Bad Request – 客户端输入未通过验证。
  • 401 Unauthorized – 用户无权访问资源。它通常在用户未通过身份验证时返回。
  • 403 Forbidden – 用户已通过身份验证，但不允许访问资源。
  • 404 Not Found – 未找到资源。
  • 500 内部服务器错误 – 一般服务器错误。它可能不应该被明确抛出。
  • 502 Bad Gateway – 这表示来自上游服务器的无效响应。
  • 503 服务不可用 – 服务器端发生了意外（可能是服务器过载、系统某些部分出现故障等）。

3. 支持过滤、排序和分页

如果您在应用程序中实现 API 并且端点返回数百万的结果，您的服务器会如何反应……？

你的服务器会宕机，它真的会在你面前哭泣……（开玩笑的……）

很多时候，我们只需要从我们的服务器消耗一些特定的或更少的资源。原因可能是任何事情。它可以是系统的性能，搜索系统，也可以是不需要一次性返回的海量信息。您可以使用过滤器根据条件返回某些特定项目。如果您想一次返回几个结果，请在 API 中使用分页。

这些概念将帮助您仅显示特定类型的信息，并通过消耗更少的资源来提高系统的性能。下面给出了例子……

  • 过滤器：使用以下属性过滤客户……姓氏为史密斯，年龄为 30 岁。
    GET /customers?last_name=Smith&age=30
  • 分页：返回从 0 开始的 20 行
    GET /customers?limit=20&offset=0
  • 排序：返回按电子邮件升序排列的行。
    GET /customers?sort_by=asc(email)

4.端点名称应为复数

如果您在应用程序中实现了任何类型的 API，那么您可能会遇到端点名称应该是单数还是复数的问题。请记住，您需要在整个应用程序中保持一致性。因此，最好以复数形式构建端点以在数据库中保持一致。

您不必总是获得单个项目。您可以在一个表中包含多个项目，但即使您考虑只获得一个结果的场景，并且在任何地方都将其放置为单数，那么您将无法保持路线名称的一致性。 

- GET /article
- GET /article/:id
+ GET /articles
+ GET /articles/:id

5.分层对象的嵌套资源

在实现 API 时，您需要注意端点的路径。端点的路径处理嵌套资源。要创建此路径，请将嵌套资源视为路径名称并将其附加在父资源之后。确保嵌套资源与您存储在数据库中的表相匹配，否则它会给您带来混乱。

如果您没有理解上述要点，请以您的数据库中有学生列表的方式来理解这一点。他们每个人都选择了他们感兴趣的科目。 将“主题”表视为数据库中“学生”表的子项。

现在，如果您想为与学生关联的科目创建端点，请将 /subjects 路径附加到 /student 路径的末尾。如果您使用的是 GET 方法，那么端点路径的示例将如下所示……

‘/students/:studentId/subjects’

我们获取由 studentId 标识的学生的科目，然后将返回响应。在这里，学生是家长的资源，科目是学生的孩子的资源。因此，正如所讨论的，我们在“/students/:studentId”之后添加主题。每个学生都有自己的科目。相同类型的嵌套结构也将应用于其他方法，例如 POST、PUT 和 DELETE 端点。

6. 遵循良好的安全实践

当您实现 API 时，请确保客户端和服务器之间的通信是私密的，因为您经常发送和接收私密信息。出于安全目的，您可以使用 SSL/TLS。

使用 SSL 证书并不太难。您可以轻松地将其加载到服务器上，而且 SSL 证书的成本也是免费且非常低的。不要让你的 REST API 开放。它应该通过安全通道进行通信。

当用户访问信息时，他们不应该能够访问他们请求的更多数据。作为用户，您不得访问其他用户的信息或管理员的数据。

为了实现最小权限原则，为每个用户添加单个角色或更细粒度的角色检查。如果您想将用户分组为几个角色，那么应该允许他们涵盖他们需要的所有内容，仅此而已。

对于用户有权访问的每个功能，如果您拥有更精细的权限，请确保管理员可以轻松地为每个用户添加和删除这些功能。添加一些可应用于群组用户的预设角色。您不必为每个用户手动执行此操作。

7.缓存数据以提高性能

您可能在应用程序中实现某些功能期间使用了缓存。缓存确实是一个强大的工具，可以加快应用程序的性能。使用缓存，您将获得更快的结果，并且您不必为同一查询多次从数据库中提取数据。

在实现 API 期间使用缓存。它将加快应用程序的性能，并减少资源的消耗。缓存数据而不是运行相同的查询并要求数据库给出相同的结果是很好的（你的数据库会在你面前开始哭泣……lolzzz）。

您需要注意的预防措施之一是您不会获得过时的数据。由于旧数据，可能会发生一些错误，并且您的系统可能会在生产环境中产生大量错误。不要在缓存中长时间保存信息。最好将数据在缓存中保留一小段时间。

您可以根据需要更改缓存数据的方式。实现缓存的一项伟大服务是 Redis

8. 版本控制

保留 API 的不同版本将帮助您跟踪更改，并在最新版本出现问题时帮助您恢复以前的版本。考虑一个场景，你实现了一个 API，部署它，很多客户开始使用它。现在，在某些时候，您想要进行一些更改并从资源中添加或删除数据。

有可能它会在使用该接口的外部服务上产生错误。这就是您应该保留不同版本 API 的原因。从以前的版本中，您可以获得备份并进一步处理它。

可以根据语义版本进行版本控制。不要强迫每个人同时在同一个版本上工作，一旦您发现不再需要旧版本的 API，您可以逐渐删除它。大多数情况下，版本控制是通过在 API 路径的开头添加 /v1/、/v2/ 等来完成的。 

GET /v1/customers
GET /v2/students

结论

JSON、SSL/TLS、HTTP 状态代码是现代 Web 应用程序 API 的标准构建块。要设计高质量的 Restful API，请遵循我们上面讨论过的最佳约定。

作为后端开发人员，您的工作不仅仅是实现您被要求执行的功能。您还需要注意以最佳方式进行操作。在实现 API 时应用最佳原则，以便使用和使用它的人能够像它一样工作。