graphql - GraphQL API 中的 HTTP 状态代码处理

Question

很多资源都说，即使发生错误，GraphQL 也应该始终以 200 状态代码进行响应:

• https://www.graph.cool/docs/faq/api-eep0ugh1wa/#how-does-error-handling-work-with-graphcool
• https://github.com/rmosolgo/graphql-ruby/issues/1130#issuecomment-347373937
• https://blog.hasura.io/handling-graphql-hasura-errors-with-react/

因为 GraphQL 可以在一个响应中返回多个响应，所以这是有道理的。当用户在一次请求中请求两个资源，并且只能访问第一个资源时，您可以发回第一个资源，并对第二个资源返回 forbidden 错误。

然而，这只是我在阅读多个 GraphQL 库的文档和博客文章时发现的。 我在官方规范中没有找到任何有关 HTTP 状态代码的信息，这里 https://spec.graphql.org/或这里https://graphql.org/

所以我还有几个问题:

1. 如果出现意外的服务器错误，可以返回 HTTP 500 状态代码吗？
2. 如果凭据错误，是否可以返回 HTTP 401 状态代码？
3. 我是否应该像这样在 GraphQL 响应的 errors 键中包含潜在 HTTP 状态代码

{
  "errors" => [{
    "message" => "Graphql::Forbidden",
    "locations" => [],
    "extensions" => {
      "error_class" => "Graphql::Forbidden", "status" => 403
    }
  }]
}

我是否应该将常见错误(例如错误的字段名称)与 HTTP 状态代码 400 Bad Request 相匹配？

{
  "errors" => [{
    "message" => "Field 'foobar' doesn't exist on type 'UserConnection'",
    "locations" => [{
      "line" => 1,
      "column" => 11
    }],
    "path" => ["query", "users", "foobar"],
    "extensions" => {
      "status" => 400, "code" => "undefinedField", "typeName" => "UserConnection", "fieldName" => "foobar"
    }
  }]
}

如果您能分享在 GraphQL 中处理 HTTP 状态代码时的经验/资源/最佳实践，我会非常高兴。

Answer 1

GraphQL 与传输无关。虽然 GraphQL 服务通常是通过 HTTP 接受请求的 Web 服务，但它们也可以并且确实接受通过其他传输的请求。事实上，GraphQL 服务可以在根本没有网络请求的情况下执行查询——它所需要的只是一个查询，以及一个可选的变量对象和操作名称。

因此，GraphQL 规范不关心方法、状态代码或任何其他特定于 HTTP 的内容(它仅在讨论序列化时提到 HTTP)。与这些事情有关的任何实践充其量都是随着时间的推移而演变的约定，或者只是一些为 GraphQL 编写的原始库的产物。因此，对您的问题的任何类型的答案都将主要基于意见。

也就是说，因为你的 GraphQL 服务不应该关心它的查询是如何被接收的，所以可以说它的代码和处理接收请求和发回响应的任何代码之间应该是分离的(就像 Node.js 中的 Express 应用程序)。换句话说，我们可以说您的解析器代码永远不能改变响应状态代码之类的内容。这是社区当前的想法，大多数库仅返回两个代码之一 - 如果请求本身无效则返回 400，否则返回 200。

如果您的整个 GraphQL 端点受到某些身份验证逻辑的保护(假设您的服务器检查某些 header 值)，则 GraphQL 请求可能会返回 401 状态。但这是我们在 Web 服务器级别处理的事情，而不是作为架构的一部分。如果您的 Web 服务器代码出现严重错误并且必须返回 500 状态，或者位于您前面的 nginx 服务器返回 494(请求 header 太大)等，这也没有什么不同。

传统上，执行期间遇到的错误应该被抛出，仅此而已。 GraphQL 扩展可用于在收集和序列化错误时提供额外的上下文 - 错误名称、堆栈跟踪等。但是，在这些中包含 HTTP 状态代码没有什么意义。再次强调，这些错误与 HTTP 无关。这样做不必要地混合了不相关的概念 - 如果您想识别错误的类型，最好使用 GENERIC_SERVER、INVALID_INPUT 等描述性代码。

但是，有关错误处理的约定也在发生变化。某些服务希望更好地区分客户端错误与其他执行错误。验证错误或其他错误将作为数据的一部分返回给最终用户，而不是被视为执行错误，这种情况变得越来越常见。

type Mutation {
  login(username: String!, password: String!): LoginPayload!
}

type LoginPayload {
  user: User
  error: Error
}

您可以通过 Shopify 等公共(public) API 查看此类有效负载类型的实际情况。此方法的一个变体是利用联合来表示许多可能的响应。

type Mutation {
  login(username: String!, password: String!): LoginPayload!
}

union LoginPayload = User | InvalidCredentialsError | ExceededLoginAttemptsError

最终结果是客户端错误是强类型的，并且很容易与最终用户不关心的其他错误区分开来。采用这些约定有很多好处，但它们是否适合您的服务器最终取决于您。