GraphQL - Response 响应

官方参考文档

GraphQL服务器收到一个请求时，它必须返回一个格式正确的响应。服务器的响应描述了操作的结果或遇到的错误。

1. Serialization Format 序列格式

1.1 概述

GraphQL 不需要特定的序列格式。但是，客户端应该使用支持 GraphQL 响应中主要原语的序列化格式。
序列化格式必须支持以下四个类型的表示：

• Map
• List
• String
• Null

其中，String 可以用这些类型替代：

• Boolean
• Int
• Float
• Enum Value

1.2 JSON 序列化

首选序列化格式

GraphQL 中首选 JSON 作为序列化格式。返回的 JSON 对象与查询所定义的那些字段有相同的顺序。

概念的映射关系

GraphQL 概念和 JSON 中的概念的映射关系：

GraphQL Value	JSON Value
Map	Object
List	Array
Null	null
String	String
Boolean	true or false
Int	Number
Float	Number
Enum Value	String

对象属性排序

JSON 对象是键值对的无序集合，但以有序方式表示。换句话说，虽然JSON字符串 { "name": "Mark", "age": 30 } 和 { "age": 30, "name": "Mark" } 有相同的值，但是排序不同。

GraphQL 返回的序列化的 JSON 对象与查询所定义的那些字段有相同的顺序。

例如，如果查询是{ name, age }，以JSON响应的GraphQL服务器应该响应{ “name”: “Mark”, “age”: 30 }并且不应该响应{ “age”: 30, “name”: “Mark” }。

2. Response Format 响应格式

对GraphQL操作的响应必须是一个 map。
响应有三个顶级属性：data，errors，extensions。

2.1 data

响应的第一个属性是 data，用来填充所有响应的数据。
data 响应中的数据是执行操作的结果。对于查询操作，此输出是模式的查询根类型的一个对象；对于变更操作，这个输出是该模式的变更根类型的一个对象。

• 如果在执行之前由于语法错误、缺少信息或验证错误导致操作失败，此条目不得存在。
• 如果在执行期间遇到阻止有效响应的错误，则响应中的data条目应该是null。

{
  "data": {
    "viewer": {
      "name": null,
      "id": "MDQ6VXNlcjE4NTMyODU5"
    }
  }
}

2.2 errors

只要遇到错误，响应就必须包含属性 errors。该条目的值在“错误”一节中进行了描述。
errors 响应是一个非空的错误列表 List，其中每个错误都是一个 map。

• 如果操作完成而没有遇到任何错误，则 errors 不得存在。
• 每个错误都必须包含属性 message，message 是用于提示开发人员错误的描述信息。
• 如果错误与请求的 GraphQL 文档中的特定点相关联，则这个错误就应该包含 locations 属性。 locations 属性是错误行列位置信息的列表，其中用 line 和 column 表示错误发生在第几行第几列。

如果 data 响应不存在或响应中的值是 null，则 errors 响应不能为空，必须包含至少一个错误，这个错误应该指出为什么没有数据能够被返回。
如果 data 响应不是 null，errors 响应可以包含执行期间发生的任何错误。

{
  "data": null,
  "errors": [
    {
      "message": "Field 'namea' doesn't exist on type 'User'",
      "locations": [
        {
          "line": 3,
          "column": 5
        }
      ]
    },
    {
      "message": "Field 'ida' doesn't exist on type 'User'",
      "locations": [
        {
          "line": 6,
          "column": 5
        }
      ]
    }
  ]
}

2.3 extensions

响应也可能包含属性 extensions。此属性的值是 map。这个属性是为接口定义者保留的，可以扩展协议，对内容没限制。