API错误处理的最佳实践 | Postman 博客

Published: at 12:00 AM

API错误处理的最佳实践 | Postman 博客

摘要

学习API错误处理的一般最佳实践，以及针对REST、GraphQL、gRPC等不同架构的特定最佳实践。

原文 Best Practices for API Error Handling 由 Gbadebo Bello 撰写。

2024年2月8日 · 10分钟

错误处理是使用API时的一个关键部分。当API遇到问题，如无效的输入数据或缺失的资源时，可能会导致错误。至关重要的是，这些错误被正确处理并清晰地展示给客户端或最终用户。

API生命周期涉及API的生产者和消费者。API生产者工作在服务器端，负责API的设计和开发。另一方面，API消费者工作在客户端，负责将API集成到最终用户交互的各种系统中。在这一过程的任何阶段都可能发生错误。如果这些错误没有得到适当的处理，可能会导致停机、糟糕的用户体验、金钱和时间的损失。

在本文中，我们将首先回顾一些在客户端和服务器端处理API错误的最佳实践——不侧重于任何特定的API架构。然后，我们将讨论针对API错误处理的特定架构的最佳实践——并探讨Postman API平台如何帮助团队更高效地处理错误。

服务器端处理API错误的一些最佳实践是什么？

有多种API架构模式，每种都有其独特的错误处理方法。也就是说，所有API错误都需要以一致和逻辑的方式呈现。因此，无论您的API采用何种架构模式，都应遵循以下最佳实践进行服务器端错误处理：

客户端处理API错误的一些最佳实践是什么？

开发者在API集成过程中经常遇到错误。这些错误可能是由不正确的实现、用户操作或API自身的内部服务器错误引起的。重要的是，开发者需要正确处理这些错误，并以直接、非技术性的方式将它们呈现给最终用户。以下最佳实践为API集成期间成功处理错误奠定了基础——无论API的架构模式如何：

针对流行的API架构模式，错误处理的一些最佳实践是什么？

不同的API架构模式有不同的API错误处理方法，开发者社区为这些不同架构确定了错误处理的最佳实践。在本节中，我们将探讨这些特定架构的API错误处理最佳实践。

REST的错误处理

REST为客户端和服务器之间资源共享提供了简单且统一的界面。它使用标准的HTTP方法对资源执行CRUD（创建、读取、更新和删除）操作。REST API使用标准的HTTP状态代码来指示请求的结果。这些状态代码可以立即用于确定请求是否成功或是否发生了错误。

当使用REST API时处理错误的一些最佳实践包括：

作为示例，让我们考虑以下假设用于通过其ID获取特定用户信息的HTTP REST API请求：

curl -i -X GET https://api.example.com/api/v1/users/12345

如果提供的用户ID错误，且数据库中不存在给定ID的用户，则格式良好且提供适当细节的错误消息应如下所示：

{
  "status": "error", // 这可以是‘error’或‘success’
  "statusCode": 404,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "未找到请求的资源。",
    "details": "ID为'12345'的用户在我们的记录中不存在。",
    "timestamp": "2023-12-08T12:30:45Z",
    "path": "/api/v1/users/12345",
    "suggestion": "请检查用户ID是否正确或参考我们的文档 https://api.example.com/docs/errors#RESOURCE_NOT_FOUND 获取更多信息。"
  },
  "requestId": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "documentation_url": "https://api.example.com/docs/errors"
}

此响应有效因为它：

GraphQL的错误处理

GraphQL是一个用于API的查询语言，以及用于使用您为数据定义的类型系统执行查询的服务器端运行时。它向客户端暴露了一个用于查询和变更数据的单一端点——并允许客户端请求并接收所需的特定数据，而无需将请求串在一起。GraphQL使用三种操作——变更、查询和订阅——来进行数据变更、查询以及促进客户端和服务器之间的实时通信。

GraphQL是传输不可知的，虽然HTTP是其最常用的传输协议，但它也可以使用其他传输协议，如WebSockets。这意味着状态代码不能用来传达GraphQL API请求的状态，即使在使用HTTP作为传输协议时，即使有错误响应，也可能会有200 OK状态代码。

GraphQL规范清楚地定义了如何处理GraphQL错误，以及如何在响应请求时结构化和返回错误。GraphQL中的错误作为errors字段返回，该字段是错误对象的数组。每个对象可以包含以下字段：

在处理GraphQL API错误时的一些最佳实践包括：

考虑以下对https://api.example.com/graphql端点的GraphQL query，它通过用户的ID获取有关用户的信息：

query {
  user(id: "12345") {
    id
    name
    email
  }
}

如果提供的用户ID错误，且数据库中不存在给定ID的用户，则格式良好且提供适当细节的错误消息应如下所示：

{
  "data": {
    "user": null
  },
  "errors": [
    {
      "message": "未找到用户",
      "locations": [{ "line": 1, "column": 8 }],
      "path": ["user"],
      "extensions": {
        "code": "USER_NOT_FOUND",
        "timestamp": "2023-12-08T12:30:45Z",
        "details": "ID为'12345'的用户在我们的记录中不存在。",
        "documentation_url": "https://api.example.com/docs/errors#USER_NOT_FOUND"
      }
    }
  ]
}

此错误有效因为它：

如果您想了解更多关于GraphQL中错误处理的信息，请查看我们学习中心的这篇文章。

gRPC的错误处理

gRPC是一个支持分布式环境中的服务到服务通信的架构驱动框架。它是RPC（远程过程调用）协议的一种语言不可知实现，支持使用HTTP/2和协议缓冲区（Protobuf）进行流式传输和强类型服务合同。

gRPC使用其自己的一套状态代码来表示gRPC调用中的各种错误状态。这些状态代码可以与一个可选的错误消息结合使用，提供有关错误的额外信息。然而，使用这两种方法仍然非常有限，并且无法提供关于错误充分的信息。官方gRPC文档表示，使用Protobuf的人应该利用Google开发的更丰富的错误模型，但这种方法有其自身的局限性。例如，从语言到语言，该错误模型的实现可能会有所不同，并且并不是所有语言都完全支持它。

这里是一些处理gRPC中错误的推荐最佳实践：

Postman如何帮助您更高效地处理API错误？

Postman API平台包括许多功能，可以帮助API生产者和消费者更高效地处理错误。通过Postman，您可以：