响应

了解 GraphQL 如何向客户端返回数据

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

数据

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

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

GraphQL 规范没有要求的一点是响应的特定序列化格式。话虽如此，响应通常格式化为 JSON，如上例所示。

此外，GraphQL 规范也不要求请求使用特定的传输协议，尽管 通常使用 HTTP 来处理无状态的查询和变更操作。持久的、有状态的订阅操作通常由 WebSockets 或服务器发送事件来支持。

错误

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

请求错误

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

errors 对象中的 message 键为开发人员提供了有助于理解引发了何种错误的信息，并且 locations 键（如果存在）指示了文档中发生错误的位置。

有时，GraphQL 请求在语法上可能是正确的，但在服务器解析和 验证 文档以检查模式时，会在操作的某一部分发现问题并引发验证错误。

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

当客户端为其对应的字段参数指定了不正确的变量类型时，也会发生验证错误

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

字段错误

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

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

让我们看一个例子：

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

网络错误

与对任何类型 API 的网络调用一样，与 GraphQL *不*特定的网络错误可能会在请求的任何时候发生。这类错误会阻止客户端和服务器之间的通信，直到请求完成，例如 SSL 错误或连接超时。根据您选择的 GraphQL 服务器和客户端库，其中可能内置了支持特殊网络错误处理的功能，例如对失败操作的重试。

扩展

GraphQL 规范允许响应中出现的最后一个顶层键是 extensions 键。此键保留供 GraphQL 实现用于提供有关响应的附加信息，虽然如果存在则它必须是一个对象，但对其可能包含的内容没有任何其他限制。

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

后续步骤

总结我们对 GraphQL 响应格式的了解

• GraphQL 规范允许响应中有三个顶层键：data、errors 和 extensions
• 响应中至少会出现 data 或 errors 中的一个（当两者都存在时，它是一个“部分响应”）
• data 键包含已执行操作的结果
• 有关引发的错误的*信息*包含在响应的 errors 键中
• 请求错误（如语法错误或验证错误）在执行开始之前就会引发，因此响应中不会包含 data
• 当执行过程中发生字段错误时，errors 键中会有错误的描述，并且 data 键可能会包含部分数据
• GraphQL 实现可以在 extensions 键中包含有关响应的附加任意信息

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

下一课

内省 (Introspection)

使用内省来探索模式本身——一种动态检查类型和字段的强大方法。

前往下一课 教程