响应

¥Response

Learn how GraphQL returns data to clients

GraphQL 文档被 validated 和 executed 之后，服务器将向请求客户端返回 response。GraphQL 的优势之一是服务器响应反映了客户端原始请求的形状，但如果在执行操作之前或期间发生了意外情况，响应也可能包含有用的信息。在此页面上，我们将深入探讨 GraphQL 请求生命周期中的最后阶段。

¥After a GraphQL document has been validated and executed, the server will return a response to the requesting client. One of GraphQL’s strengths is that the server response reflects the shape of the client’s original request, but a response may also contain helpful information if something unexpected happened before or during the execution of an operation. On this page, we’ll take a deeper exploration of this final phase in the lifecycle of a GraphQL request.

数据

¥Data

正如我们在本指南中的示例中所看到的，当执行 GraphQL 请求时，响应将在顶层 data 键上返回。例如：

¥As we have seen in the examples throughout this guide, when a GraphQL request is executed the response is returned on a top-level data key. For example:

data 键的包含不是底层 GraphQL 实现做出的任意决定 - 它由 GraphQL 规范 描述。在此键下，你将找到请求操作的执行结果，如果在执行某些字段解析器期间引发错误，则结果可能包括请求字段的部分数据。

¥The inclusion of the data key isn’t an arbitrary decision made by the underlying GraphQL implementation—it’s described by the GraphQL specification. Under this key, you will find the result of the execution of the requested operation, which may include partial data for the requested fields if errors were raised during the execution of some field resolvers.

GraphQL 规范不需要的一件事是响应的特定序列化格式。也就是说，响应通常格式化为 JSON，如上例所示。

¥One thing that the GraphQL specification doesn’t require is a specific serialization format for the response. That said, responses are typically formatted as JSON, as in the example above.

此外，GraphQL 规范也不要求对请求使用特定的传输协议，尽管对于无状态查询和突变操作，它是 HTTP 常用的指令。长寿命、有状态的订阅操作通常由 WebSockets 或服务器发送的事件支持。

¥Additionally, the GraphQL specification doesn’t require the use of a particular transport protocol for requests either, although it is common for HTTP to be used for stateless query and mutations operations. Long-lived, stateful subscription operations are often supported by WebSockets or server-sent events instead.

错误

¥Errors

除了 data 键之外，GraphQL 规范还概述了 errors 在响应中的格式。GraphQL 实现是否在响应中提供带有错误信息的部分数据将取决于引发的错误类型。让我们看看在 GraphQL 请求的生命周期中可能发生的不同类型的错误。

¥In addition to the data key, the GraphQL specification outlines how errors should be formatted in the response. Whether the GraphQL implementation provides partial data with the error information in the response will depend on the type of error that was raised. Let’s look at the different kinds of errors that can occur during the lifecycle of a GraphQL request.

请求错误

¥Request errors

请求错误通常是因为客户端犯了错误而发生的。例如，文档中可能存在语法错误，例如缺少括号或使用未知的根操作类型关键字：

¥Request errors typically occur because the client made a mistake. For example, there may be a syntax error in the document, such as a missing bracket or the use of an unknown root operation type keyword:

errors 对象内的 message 键为开发者提供了一些有用的信息，以了解引发了哪种错误，而 locations 键（如果存在）则指示文档中发生错误的位置。

¥The message key inside the errors object provides some helpful information for the developer to understand what kind of error was raised, and the locations key, if present, indicates where the error occurred in the document.

有时，GraphQL 请求可能在语法上是正确的，但是当服务器解析并根据模式对文档进行 validates 时，它会发现部分操作存在问题并引发验证错误。

¥Sometimes, a GraphQL request may be syntactically correct, but when the server parses and validates the document against the schema, it finds an issue with part of the operation and raises a validation error.

例如，客户端可能会请求 Starship 类型上不存在的字段：

¥For example, the client may request a field that does not exist on the Starship type:

当客户端为其相应的字段参数指定不正确的变量类型时，也会出现验证错误：

¥Validation errors also occur when clients specify incorrect variable types for their corresponding field arguments:

在前面的例子中，我们可以看到，当请求错误发生时，data 键将不会被包含，因为服务器在执行字段解析器之前向客户端返回错误响应。

¥In the previous examples, we can see that when a request error occurs the data key will not be included because the server returns an error response to the client before the field resolvers are executed.

字段错误

¥Field errors

如果在执行过程中发生意外情况，则会引发字段错误。例如，解析器可能会直接引发错误，或者可能会返回无效数据，例如具有非空输出类型的字段的空值。

¥Field errors are raised if something unexpected happens during execution. For example, a resolver may raise an error directly, or may return invalid data such as a null value for a field that has a Non-Null output type.

在这些情况下，GraphQL 将尝试继续执行其他字段并返回部分响应，其中 data 键与 errors 键一起出现。

¥In these cases, GraphQL will attempt to continue executing the other fields and return a partial response, with the data key appearing alongside the errors key.

让我们看一个例子：

¥Let’s look at an example:

上面的突变试图在单个操作中删除两艘星际飞船，但没有 ID 为 3010 的星际飞船存在，因此服务器会抛出错误。在响应中，我们可以看到有关别名为 secondShip 的字段发生的错误的信息。在 data 键下，我们还看到返回了第一艘船的 ID 以表示成功删除，而第二艘船由于其解析器函数中引发的错误而产生了空结果。

¥The mutation above attempts to delete two starships in a single operation, but no starship exists with an ID of 3010 so the server throws an error. In the response, we can see information about the error that occurred for the field that was aliased as secondShip. Under the data key, we also see that the ID of the first ship was returned to indicate successful deletion, while the second ship produced a null result due to the error raised in its resolver function.

网络错误

¥Network errors

与对任何类型的 API 的网络调用一样，在请求期间的任何时候都可能发生非特定于 GraphQL 的网络错误。这些类型的错误将在请求完成之前阻止客户端和服务器之间的通信，例如 SSL 错误或连接超时。根据你选择的 GraphQL 服务器和客户端库，它们中可能内置有支持特殊网络错误处理的功能，例如重试失败的操作。

¥As with network calls to any type of API, network errors that are not specific to GraphQL may happen at any point during a request. These kinds of errors will block communication between the client and server before the request is complete, such as an SSL error or a connection timeout. Depending on the GraphQL server and client libraries that you choose, there may be features built into them that support special network error handling such as retries for failed operations.

扩展

¥Extensions

GraphQL 规范允许在响应中使用的最终顶层键是 extentions 键。此键为 GraphQL 实现保留，以提供有关响应的其他信息，尽管如果存在它必须是一个对象，但对它可能包含的内容没有其他限制。

¥The final top-level key allowed by the GraphQL specification in a response is the extentions key. This key is reserved for GraphQL implementations to provide additional information about the response and though it must be an object if present, there are no other restrictions on what it may contain.

例如，某些 GraphQL 服务器可能包含此键下的遥测数据或有关速率限制消耗的信​​息。请注意，extensions 中可用的数据以及这些数据是否在生产或开发环境中可用将完全取决于特定的 GraphQL 实现。

¥For example, some GraphQL servers may include telemetry data or information about rate limit consumption under this key. Note that what data is available in extensions and whether this data is available in production or development environments will depend entirely on the specific GraphQL implementation.

后续步骤

¥Next steps

回顾这些关于使用缓存和 GraphQL API 的建议：

¥To recap what we’ve learned about GraphQL response formats:

• GraphQL 规范允许响应中有三个顶层键：data、errors 和 extensions

  ¥The GraphQL specification allows three top-level keys in a response: data, errors, and extensions

• 响应中至少会出现 data 或 errors 中的一个（当它同时包含两者时，它就是 “部分响应”）

  ¥At least one of data or errors will be present on the response (when it contains both it is a “partial response”)

• data 键包含执行操作的结果

  ¥The data key contains the result of the executed operation

• 有关引发错误的信息包含在响应的 errors 键中

  ¥Information about raised errors is included in the errors key of the response

• 请求错误（例如语法或验证错误）在执行开始之前引发，因此 data 不会包含在响应中

  ¥Request errors (such as syntax or validation errors) are raised before execution begins so data won’t be included in the response

• 当执行过程中发生字段错误时，errors 键中会有该问题的描述，data 键中可能包含部分数据

  ¥When a field error occurs during execution, there will be a description of the issue in the errors key and there may be partial data included with the data key

• GraphQL 实现可能在 extensions 键中包含有关响应的其他任意信息

  ¥GraphQL implementations may include additional arbitrary information about the response in the extensions key

现在你了解了 GraphQL 请求的不同阶段以及如何向客户端提供响应，请转到 内省 页面了解 GraphQL 服务器如何查询有关其自身模式的信息。

¥Now that you understand the different phases of a GraphQL request and how responses are provided to clients, head over to the Introspection page to learn about how a GraphQL server can query information about its own schema.