2.1.1Unicode

非 ASCII Unicode 字符可以自由出现在 GraphQL 的 StringValue 和 Comment 部分中。

“字节顺序标记”是一种特殊的 Unicode 字符，可以出现在包含 Unicode 的文件的开头，程序可以使用它来确定文本流是 Unicode、文本流的字节序以及要解释的几种 Unicode 编码中的哪一种。

2.1.2空格

空格用于提高源文本的可读性，并充当标记之间的分隔符，任何数量的空格都可以出现在任何标记之前或之后。标记之间的空格对于 GraphQL 查询文档的语义意义并不重要，但是空格字符可以出现在 String 或 Comment 标记中。

2.1.3行终止符

与空格一样，行终止符用于提高源文本的可读性，任何数量的行终止符都可以出现在任何其他标记之前或之后，并且对 GraphQL 查询文档的语义意义没有影响。在任何其他标记中都找不到行终止符。

2.1.4注释

GraphQL 源文档可能包含单行注释，以 # 标记开头。

注释可以包含除 LineTerminator 之外的任何 Unicode 代码点，因此注释始终由以 # 字符开头到但不包括行终止符的所有代码点组成。

注释的行为类似于空格，可以出现在任何标记之后或行终止符之前，并且对 GraphQL 查询文档的语义意义没有影响。

2.1.5无意义的逗号

与空格和行终止符类似，逗号 (,) 用于提高源文本的可读性并分隔词法标记，但在 GraphQL 查询文档中，它们在语法和语义上都是微不足道的。

非重要逗号字符确保逗号的缺失或存在不会有意义地改变文档的解释语法，因为这可能是其他语言中常见的用户错误。它还允许将尾随逗号或行终止符作为列表分隔符的风格用法，这两种用法通常都希望用于源代码的可读性和可维护性。

2.1.6词法标记

GraphQL 文档由几种不可分割的词法标记组成，这些标记在此处通过源 Unicode 字符模式在词法文法中定义。

标记稍后用作 GraphQL 查询文档句法文法中的终结符。

2.1.7忽略的标记

在每个词法标记之前和之后，都可以有任意数量的忽略的标记，包括 WhiteSpace 和 Comment。源文档的忽略区域是不重要的，但是忽略的源字符可能会以重要的方式出现在词法标记中，例如 String 可能包含空格字符。

在解析给定标记时不会忽略任何字符，例如，在定义 FloatValue 的字符之间不允许有空格字符。

2.1.8标点符号

GraphQL 文档包含标点符号，以描述结构。GraphQL 是一种数据描述语言，而不是编程语言，因此 GraphQL 缺乏通常用于描述数学表达式的标点符号。

2.1.9名称

GraphQL 查询文档中充满了命名的事物：操作、字段、参数、指令、片段和变量。所有名称都必须遵循相同的语法形式。

GraphQL 中的名称区分大小写。也就是说，name、Name 和 NAME 都指不同的名称。下划线是重要的，这意味着 other_name 和 othername 是两个不同的名称。

GraphQL 中的名称仅限于此ASCII可能的字符子集，以支持与尽可能多的其他系统互操作。

2.8.1类型条件

片段必须指定它们适用的类型。在此示例中，friendFields 可用于查询 User 的上下文。

片段不能在任何输入值（标量、枚举或输入对象）上指定。

片段可以在对象类型、接口和联合上指定。

仅当片段操作的对象的具体类型与片段的类型匹配时，片段内的选择才会返回值。

例如，在 Facebook 数据模型上的以下查询中：

query FragmentTyping {
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ...userFragment
    ...pageFragment
  }
}

fragment userFragment on User {
  friends {
    count
  }
}

fragment pageFragment on Page {
  likers {
    count
  }
}

profiles 根字段返回一个列表，其中每个元素可以是 Page 或 User。当 profiles 结果中的对象是 User 时，将存在 friends，而不会存在 likers。相反，当结果是 Page 时，将存在 likers，而不会存在 friends。

{
  "profiles" : [
    {
      "handle" : "zuck",
      "friends" : { "count" : 1234 }
    },
    {
      "handle" : "cocacola",
      "likers" : { "count" : 90234512 }
    }
  ]
}

2.8.2内联片段

片段可以内联地定义在选择集中。这样做是为了根据它们的运行时类型有条件地包含字段。标准片段包含的这个特性在 query FragmentTyping 示例中得到了演示。我们可以使用内联片段完成同样的事情。

query inlineFragmentTyping {
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ... on User {
      friends {
        count
      }
    }
    ... on Page {
      likers {
        count
      }
    }
  }
}

内联片段也可以用于将指令应用于一组字段。如果省略了 TypeCondition，则内联片段被认为与封闭上下文的类型相同。

query inlineFragmentNoType($expandedInfo: Boolean) {
  user(handle: "zuck") {
    id
    name
    ... @include(if: $expandedInfo) {
      firstName
      lastName
      birthday
    }
  }
}

2.9.1Int 值

Int 数字的指定不带小数点或指数（例如 1）。

2.9.2Float 值

Float 数字包含小数点（例如 1.0）或指数（例如 1e50）或两者（例如 6.0221413e23）。

2.9.3布尔值

两个关键字 true 和 false 代表两个布尔值。

2.9.4字符串值

字符串是用双引号 (") 包裹的字符序列。（例如 "Hello World"）。空格和其他通常被忽略的字符在字符串值中是有意义的。

语义

2.9.5枚举值

枚举值表示为不带引号的名称（例如 MOBILE_WEB）。建议枚举值使用“全大写”。枚举值仅在枚举类型精确已知的情况下使用。因此，不必在字面量中提供枚举类型名称。

为了避免混淆，枚举值不能为 “null”。GraphQL 不提供字面量值来表示 null 的概念。

2.9.6列表值

列表是用方括号 [ ] 包裹的有序值序列。列表字面量的值可以是任何值字面量或变量（例如 [1, 2, 3]）。

逗号在整个 GraphQL 中是可选的，因此允许尾随逗号，重复的逗号不代表缺失值。

语义

2.9.7输入对象值

输入对象字面量值是用花括号 { } 包裹的键值对输入值的无序列表。对象字面量的值可以是任何输入值字面量或变量（例如 { name: "Hello world", score: 1.0 }）。我们将输入对象的字面量表示称为“对象字面量”。

输入对象字段是无序的

输入对象字段可以以任何语法顺序提供，并保持相同的语义含义。

以下两个查询在语义上是相同的：

{
  nearestThing(location: { lon: 12.43, lat: -53.211 })
}

{
  nearestThing(location: { lat: -53.211, lon: 12.43 })
}

语义

3.1.1标量

正如名称所暗示的那样，标量表示 GraphQL 中的原始值。GraphQL 响应采用分层树的形式；这些树上的叶子是 GraphQL 标量。

所有 GraphQL 标量都可以表示为字符串，尽管根据所使用的响应格式，对于给定的标量类型，可能存在更合适的原始类型，并且服务器应在适当时使用这些类型。

GraphQL 提供了许多内置标量，但类型系统可以添加具有语义含义的附加标量。例如，GraphQL 系统可以定义一个名为 Time 的标量，虽然序列化为字符串，但承诺符合 ISO-8601。当查询 Time 类型的字段时，您可以依赖使用 ISO-8601 解析器解析结果并使用客户端特定的原始时间类型的功能。另一个可能有用的自定义标量的示例是 Url，它序列化为字符串，但服务器保证它是有效的 URL。

结果强制转换

GraphQL 服务器在准备给定标量类型的字段时，必须遵守标量类型描述的约定，或者通过强制转换值，或者产生错误。

例如，GraphQL 服务器可能正在准备类型为 Int 的标量字段，并遇到浮点数。由于服务器绝不能通过产生非整数来破坏约定，因此服务器应截断小数值，仅产生整数值。如果服务器遇到布尔值 true，则应返回 1。如果服务器遇到字符串，则可能会尝试解析字符串以获得十进制整数值。如果服务器遇到某些无法合理强制转换为 Int 的值，则必须引发字段错误。

由于客户端无法观察到此强制转换行为，因此强制转换的精确规则留给实现来决定。唯一的要求是服务器必须产生符合预期标量类型的值。

输入强制转换

如果 GraphQL 服务器期望标量类型作为参数的输入，则强制转换是可观察的，并且规则必须明确定义。如果输入值与强制转换规则不匹配，则必须引发查询错误。

GraphQL 具有不同的常量字面量来表示整数和浮点输入值，并且强制转换规则可能因遇到的输入值类型而异。GraphQL 可以通过查询变量进行参数化，查询变量的值通常在通过 HTTP 等传输方式发送时进行序列化。由于某些常见的序列化格式（例如 JSON）不区分整数值和浮点值，因此如果它们具有空的小数部分（例如 1.0），则将其解释为整数输入值，否则将其解释为浮点输入值。

内置标量

GraphQL 提供了一组定义良好的基本标量类型。GraphQL 服务器应支持所有这些类型，并且提供这些名称类型的 GraphQL 服务器必须遵守以下描述的行为。

3.1.2对象

GraphQL 查询是分层和组合的，描述了一个信息树。虽然标量类型描述了这些分层查询的叶子值，但对象描述了中间层。

GraphQL 对象表示命名字段的列表，每个字段产生特定类型的值。对象值序列化为有序映射，其中查询的字段名称（或别名）是键，而评估字段的结果是值，并按照它们在查询中出现的顺序排序。

例如，类型 Person 可以描述为

type Person {
  name: String
  age: Int
  picture: Url
}

其中 name 是将产生 String 值的字段，age 是将产生 Int 值的字段，picture 是将产生 Url 值的字段。

对象值的查询必须至少选择一个字段。字段的选择将产生一个有序映射，其中包含查询对象的精确子集，并按照它们被查询的顺序排列。只有在对象类型上声明的字段才能在该对象上有效地查询。

例如，选择 Person 的所有字段

{
  name
  age
  picture
}

将产生对象

{
  "name": "Mark Zuckerberg",
  "age": 30,
  "picture": "http://some.cdn/picture.jpg"
}

而选择字段的子集

{
  age
  name
}

必须只产生该子集

{
  "age": 30,
  "name": "Mark Zuckerberg"
}

对象类型的字段可以是标量、枚举、另一个对象类型、接口或联合。此外，它可以是任何包装类型，其底层基本类型是这五种类型之一。

例如，Person 类型可能包含 relationship

type Person {
  name: String
  age: Int
  picture: Url
  relationship: Person
}

有效查询必须为返回对象的字段提供嵌套字段集，因此此查询无效

{
  name
  relationship
}

但是，此示例是有效的

{
  name
  relationship {
    name
  }
}

并将产生每个查询对象类型的子集

{
  "name": "Mark Zuckerberg",
  "relationship": {
    "name": "Priscilla Chan"
  }
}

字段排序

当查询对象时，字段的结果映射在概念上按照它们在查询执行期间遇到的顺序排序，不包括类型不适用的片段以及通过 @skip 或 @include 指令跳过的字段或片段。当使用 CollectFields() 算法时，可以正确生成此排序。

支持有序映射的响应格式（例如 JSON）必须保持此排序。不支持有序映射的响应格式可以忽略此排序。

如果片段在其他字段之前展开，则片段指定的字段在响应中出现在以下字段之前。

{
  foo
  ...Frag
  qux
}

fragment Frag on Query {
  bar
  baz
}

产生有序结果

{
  "foo": 1,
  "bar": 2,
  "baz": 3,
  "qux": 4
}

如果在选择中多次查询字段，则按首次遇到的顺序排序。但是，类型不适用的片段不会影响排序。

{
  foo
  ...Ignored
  ...Matching
  bar
}

fragment Ignored on UnknownType {
  qux
  baz
}

fragment Matching on Query {
  bar
  qux
  foo
}

产生有序结果

{
  "foo": 1,
  "bar": 2,
  "qux": 3
}

此外，如果指令导致字段被排除，则在字段排序中不考虑它们。

{
  foo @skip(if: true)
  bar
  foo
}

产生有序结果

{
  "bar": 1,
  "foo": 2
}

结果强制转换

确定强制转换对象的结果是 GraphQL 执行器的核心，因此这将在规范的该部分中介绍。

输入强制转换

对象永远不是有效的输入。

type Person {
  name: String
  picture(size: Int): Url
}

{
  name
  picture(size: 600)
}

{
  "name": "Mark Zuckerberg",
  "picture": "http://some.cdn/picture_600.jpg"
}

3.1.3接口

GraphQL 接口表示具名字段及其参数的列表。GraphQL 对象可以实现一个接口，从而保证它们将包含指定的字段。

GraphQL 接口上的字段与 GraphQL 对象上的字段具有相同的规则；它们的类型可以是标量（Scalar）、对象（Object）、枚举（Enum）、接口（Interface）或联合（Union），或者任何包装类型，其基本类型是这五种类型之一。

例如，一个接口可以描述一个必需的字段，然后诸如 Person 或 Business 之类的类型可以实现此接口。

interface NamedEntity {
  name: String
}

type Person implements NamedEntity {
  name: String
  age: Int
}

type Business implements NamedEntity {
  name: String
  employeeCount: Int
}

当期望多种对象类型之一，但应保证某些字段时，产生接口的字段很有用。

继续该示例，Contact 可能引用 NamedEntity。

type Contact {
  entity: NamedEntity
  phoneNumber: String
  address: String
}

这允许我们为 Contact 编写查询，以选择通用字段。

{
  entity {
    name
  }
  phoneNumber
}

当查询接口类型上的字段时，只能查询在该接口上声明的字段。在上面的示例中，entity 返回 NamedEntity，并且 name 在 NamedEntity 上定义，因此它是有效的。但是，以下查询将无效

{
  entity {
    name
    age
  }
  phoneNumber
}

因为 entity 引用 NamedEntity，而 age 未在该接口上定义。仅当 entity 的结果是 Person 时，查询 age 才有效；查询可以使用片段或内联片段来表达这一点

{
  entity {
    name
    ... on Person {
      age
    }
  },
  phoneNumber
}

结果强制转换

接口类型应具有某种方式来确定给定结果对应于哪个对象。一旦完成，接口的结果强制转换与对象的结果强制转换相同。

输入强制转换

接口永远不是有效的输入。

3.1.4联合

GraphQL 联合表示一个对象，该对象可能是 GraphQL 对象类型列表中的一种，但不提供这些类型之间任何有保证的字段。它们与接口的不同之处还在于，对象类型声明它们实现了哪些接口，但不知道哪些联合包含它们。

对于接口和对象，只能直接查询类型上定义的那些字段；要查询接口上的其他字段，必须使用类型化的片段。这与联合相同，但是联合不定义任何字段，因此如果不使用类型化的片段，则无法在此类型上查询任何字段。

例如，我们可能有以下类型系统

union SearchResult = Photo | Person

type Person {
  name: String
  age: Int
}

type Photo {
  height: Int
  width: Int
}

type SearchQuery {
  firstSearchResult: SearchResult
}

当查询类型为 SearchQuery 的 firstSearchResult 字段时，查询将要求片段内的所有字段指示适当的类型。如果查询想要在结果为 Person 时获取名称，而在结果为照片时获取高度，则以下查询是无效的，因为联合本身未定义任何字段

{
  firstSearchResult {
    name
    height
  }
}

相反，查询应为

{
  firstSearchResult {
    ... on Person {
      name
    }
    ... on Photo {
      height
    }
  }
}

结果强制转换

联合类型应具有某种方式来确定给定结果对应于哪个对象。一旦完成，联合的结果强制转换与对象的结果强制转换相同。

输入强制转换

联合永远不是有效的输入。

3.1.5枚举

GraphQL 枚举是标量类型的一种变体，它表示一组有限的可能值之一。

GraphQL 枚举不是数值的引用，而是其自身唯一的值。它们序列化为字符串：所表示值的名称。

结果强制转换

GraphQL 服务器必须返回定义的可能值集之一。如果无法进行合理的强制转换，则必须引发字段错误。

输入强制转换

GraphQL 具有一个常量文字来表示枚举输入值。GraphQL 字符串文字不得作为枚举输入接受，而应引发查询错误。

对于非字符串符号值具有不同表示形式的查询变量传输序列化（例如，EDN）应仅允许此类值作为枚举输入值。否则，对于大多数不这样的传输序列化，字符串可以被解释为具有相同名称的枚举输入值。

3.1.6输入对象

字段可以定义客户端在查询中传递的参数，以配置其行为。这些输入可以是字符串或枚举，但有时它们需要比这更复杂。

上面定义的 Object 类型不适合在此处重用，因为 Object 可以包含表达循环引用或对接口和联合引用的字段，这两种都不适合用作输入参数。因此，输入对象在系统中具有单独的类型。

输入对象定义了一组输入字段；输入字段可以是标量、枚举或其他输入对象。这允许参数接受任意复杂的结构。

结果强制转换

输入对象永远不是有效的结果。

输入强制转换

输入对象的输入应为无序映射，否则应抛出错误。强制转换的结果是无序映射，每个输入字段都有一个条目，其键是输入字段的名称。强制转换映射中条目的值是对输入中具有相同键的条目的值进行输入强制转换的结果；如果输入没有相应的条目，则该值是对 null 进行强制转换的结果。上面的输入强制转换应根据输入字段声明的类型的输入强制转换规则执行。

3.1.7列表

GraphQL 列表是一种特殊的集合类型，它声明列表中每个项的类型（称为列表的项类型）。列表值序列化为有序列表，其中列表中的每个项都按照项类型进行序列化。要表示字段使用列表类型，项类型用方括号括起来，例如：pets: [Pet]。

结果强制转换

GraphQL 服务器必须返回有序列表作为列表类型的结果。列表中的每个项都必须是项类型的结果强制转换的结果。如果无法进行合理的强制转换，则必须引发字段错误。特别是，如果返回非列表，则强制转换应失败，因为这表明类型系统和实现之间的期望不匹配。

输入强制转换

当预期作为输入时，仅当列表中的每个项都可以被列表的项类型接受时，才接受列表值。

如果作为列表类型的输入传递的值不是列表，则应将其强制转换为大小为一的列表，其中传递的值是列表中的唯一项。这是为了允许接受“可变参数”的输入将其输入类型声明为列表；如果仅传递一个参数（常见情况），则客户端可以直接传递该值，而无需构造列表。

3.1.8非空

默认情况下，GraphQL 中的所有类型都是可为空的；对于上述所有类型，null 值都是有效的响应。要声明不允许 null 的类型，可以使用 GraphQL 非空类型。此类型包装一个底层类型，并且此类型的行为与其包装的类型相同，但 null 不是包装类型的有效响应除外。尾随感叹号用于表示使用非空类型的字段，例如：name: String!。

结果强制转换

在上述所有结果强制转换中，null 被认为是有效值。要强制转换非空类型的结果，应执行包装类型的强制转换。如果该结果不是 null，则强制转换非空类型的结果就是该结果。如果该结果是 null，则必须引发字段错误。

输入强制转换

如果未提供非空类型的参数，则必须引发查询错误。

如果为非空类型的参数提供了文字值，则使用包装类型的输入强制转换对其进行强制转换。

如果为非空类型的参数提供了变量，则如果运行时提供的值未提供或在提供的表示形式（通常为 JSON）中为 null，则必须引发查询错误。否则，强制转换的值是使用包装类型的输入强制转换的结果。

{
  field(arg: null)
}

指示参数为 null。相反，参数仅在省略时才为 null

{
  field
}

或者，如果传递了运行时未提供值的可为空类型变量

query withNullableVariable($var: String) {
  field(arg: $var)
}

3.2.1@skip

可以为字段、片段展开和内联片段提供 @skip 指令，并允许在执行期间根据 if 参数描述有条件地排除。

在此示例中，仅当为 $someTest 提供 false 值时，才会查询 experimentalField。

query myQuery($someTest: Boolean) {
  experimentalField @skip(if: $someTest)
}

3.2.2@include

可以为字段、片段展开和内联片段提供 @include 指令，并允许在执行期间根据 if 参数描述有条件地包含。

在此示例中，仅当为 $someTest 提供 true 值时，才会查询 experimentalField。

query myQuery($someTest: Boolean) {
  experimentalField @include(if: $someTest)
}

4.1.1命名约定

GraphQL 内省系统所需的类型和字段在与用户定义的类型和字段相同的上下文中使用时，以两个下划线为前缀。这是为了避免与用户定义的 GraphQL 类型发生命名冲突。相反，GraphQL 类型系统作者不得定义任何带有两个前导下划线的类型、字段、参数或任何其他类型系统工件。

4.1.2文档

内省系统中的所有类型都提供 description 字段（类型为 String），以允许类型设计者发布文档以及功能。GraphQL 服务器可以使用 Markdown 语法返回 description 字段。因此，建议任何显示描述的工具都使用 Markdown 渲染器。

4.1.3弃用

为了支持向后兼容性的管理，GraphQL 字段和枚举值可以指示它们是否已弃用（isDeprecated: Boolean）以及弃用的原因描述（deprecationReason: String）。

使用 GraphQL 内省构建的工具应通过信息隐藏或面向开发人员的警告来尊重弃用，从而阻止弃用使用。

4.1.4类型名称内省

GraphQL 支持在查询中的任何点通过元字段 __typename: String! 对任何对象、接口或联合进行查询时的类型名称内省。它返回当前正在查询的对象类型的名称。

当针对接口或联合类型进行查询以识别已返回的可能类型的实际类型时，这最常用。

此字段是隐式的，并且不出现在任何已定义类型中的字段列表中。

4.2.1__Type 类型

__Type 是类型内省系统的核心。它表示系统中的标量、接口、对象类型、联合、枚举。

__Type 还表示类型修饰符，用于修改它引用的类型（ofType: __Type）。这就是我们表示列表、非空类型及其组合的方式。

4.2.2类型种类

有几种不同的类型种类。在每种种类中，不同的字段实际上是有效的。这些种类在 __TypeKind 枚举中列出。

type Point {
  x: Int
  y: Int
}

4.2.3__Field 类型

__Field 类型表示对象或接口类型中的每个字段。

字段

• name 必须返回 String
• description 可以返回 String 或 null
• args 返回 __InputValue 列表，表示此字段接受的参数。
• type 必须返回 __Type，表示此字段返回的值的类型。
• isDeprecated 如果此字段不应再使用，则返回 true，否则返回 false。
• deprecationReason 可选地提供此字段已弃用的原因。

4.2.4__InputValue 类型

__InputValue 类型表示字段和指令参数以及输入对象的 inputFields。

字段

• name 必须返回 String
• description 可以返回 String 或 null
• type 必须返回 __Type，表示此输入值期望的类型。
• defaultValue 可以返回一个字符串编码（使用 GraphQL 语言），该编码表示在运行时未提供值的情况下此输入值使用的默认值。如果此输入值没有默认值，则返回 null。

4.2.5__Directive 类型

__Directive 类型表示服务器支持的指令。

字段

• name 必须返回 String
• description 可以返回 String 或 null
• locations 返回 __DirectiveLocation 列表，表示此指令可以放置的有效位置。
• args 返回 __InputValue 列表，表示此指令接受的参数。

5.1.1具名操作定义

query getDogName {
  dog {
    name
  }
}

query getOwnerName {
  dog {
    owner {
      name
    }
  }
}

query getName {
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

query dogOperation {
  dog {
    name
  }
}

mutation dogOperation {
  mutateDog {
    id
  }
}

5.1.2匿名操作定义

{
  dog {
    name
  }
}

{
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

5.2.1对象、接口和联合类型上的字段选择

形式规范

• 对于文档中的每个 selection。
• 令 fieldName 为 selection 的目标字段
• fieldName 必须在作用域内的类型上定义

解释性文本

字段选择的目标字段必须在选择集的作用域类型上定义。别名名称没有限制。

例如，以下片段将无法通过验证

fragment fieldNotDefined on Dog {
  meowVolume
}

fragment aliasedLyingFieldTargetNotDefined on Dog {
  barkVolume: kawVolume
}

对于接口，直接字段选择只能在字段上完成。具体实现者的字段与给定接口类型选择集的有效性无关。

例如，以下是有效的

fragment interfaceFieldSelection on Pet {
  name
}

而以下是无效的

fragment definedOnImplementorsButNotInterface on Pet {
  nickname
}

因为联合不定义字段，所以不得直接从联合类型选择集中选择字段，但元字段 __typename 除外。来自联合类型选择集的字段必须仅通过片段间接查询。

例如，以下是有效的

fragment inDirectFieldSelectionOnUnion on CatOrDog {
  __typename
  ... on Pet {
    name
  }
  ... on Dog {
    barkVolume
  }
}

但以下是无效的

fragment directFieldSelectionOnUnion on CatOrDog {
  name
  barkVolume
}

5.2.2字段选择合并

形式规范

• 令 set 为 GraphQL 文档中定义的任何选择集。
• FieldsInSetCanMerge(set) 必须为 true。

解释性文本

如果在执行期间遇到具有相同响应名称的多个字段选择，则要执行的字段和参数以及结果值应是明确的。因此，如果可能为同一对象遇到两个字段选择，则仅当它们等效时才有效。

对于简单的手写 GraphQL，此规则显然是明显的开发人员错误，但是嵌套片段会使手动检测变得困难。

以下选择正确合并

fragment mergeIdenticalFields on Dog {
  name
  name
}

fragment mergeIdenticalAliasesAndFields on Dog {
  otherName: name
  otherName: name
}

以下无法合并

fragment conflictingBecauseAlias on Dog {
  name: nickname
  name
}

如果参数相同，则相同的参数也会合并。值和变量都可以正确合并。

例如，以下正确合并

fragment mergeIdenticalFieldsWithIdenticalArgs on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: SIT)
}

fragment mergeIdenticalFieldsWithIdenticalValues on Dog {
  doesKnowCommand(dogCommand: $dogCommand)
  doesKnowCommand(dogCommand: $dogCommand)
}

以下无法正确合并

fragment conflictingArgsOnValues on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: HEEL)
}

fragment conflictingArgsValueAndVar on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: $dogCommand)
}

fragment conflictingArgsWithVars on Dog {
  doesKnowCommand(dogCommand: $varOne)
  doesKnowCommand(dogCommand: $varTwo)
}

fragment differingArgs on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand
}

以下字段不会合并在一起，但是两者都不能针对同一对象遇到，因此它们是安全的

fragment safeDifferingFields on Pet {
  ... on Dog {
    volume: barkVolume
  }
  ... on Cat {
    volume: meowVolume
  }
}

fragment safeDifferingArgs on Pet {
  ... on Dog {
    doesKnowCommand(dogCommand: SIT)
  }
  ... on Cat {
    doesKnowCommand(catCommand: JUMP)
  }
}

但是，字段响应必须是可以合并的形状。例如，标量值不得不同。在此示例中，someValue 可能是 String 或 Int

fragment conflictingDifferingResponses on Pet {
  ... on Dog {
    someValue: nickname
  }
  ... on Cat {
    someValue: meowVolume
  }
}

5.2.3叶子字段选择

形式规范

• 对于文档中的每个 selection
• 令 selectionType 为 selection 的结果类型
• 如果 selectionType 是标量
  • 该选择的子选择集必须为空
• 如果 selectionType 是接口、联合或对象
  • 该选择的子选择集不得为空

解释性文本

永远不允许对标量进行字段选择：标量是任何 GraphQL 查询的叶节点。

以下是有效的。

fragment scalarSelection on Dog {
  barkVolume
}

以下是无效的。

fragment scalarSelectionsNotAllowedOnBoolean on Dog {
  barkVolume {
    sinceWhen
  }
}

相反，GraphQL 查询的叶子字段选择必须是标量。不允许对没有子字段的对象、接口和联合进行叶子选择。

让我们假设以下添加到模式的查询根类型

extend type QueryRoot {
  human: Human
  pet: Pet
  catOrDog: CatOrDog
}

以下示例是无效的

query directQueryOnObjectWithoutSubFields {
  human
}

query directQueryOnInterfaceWithoutSubFields {
  pet
}

query directQueryOnUnionWithoutSubFields {
  catOrDog
}

5.3.1参数名称

形式规范

• 对于文档中的每个 argument
• 令 argumentName 为 argument 的名称。
• 令 argumentDefinition 为父字段或名为 argumentName 的定义提供的参数定义。
• argumentDefinition 必须存在。

解释性文本

提供给字段或指令的每个参数都必须在字段或指令的可能参数集中定义。

例如，以下是有效的

fragment argOnRequiredArg on Dog {
  doesKnowCommand(dogCommand: SIT)
}

fragment argOnOptional on Dog {
  isHousetrained(atOtherHomes: true) @include(if: true)
}

以下是无效的，因为 command 未在 DogCommand 上定义。

fragment invalidArgName on Dog {
  doesKnowCommand(command: CLEAN_UP_HOUSE)
}

这也是无效的，因为 unless 未在 @include 上定义。

fragment invalidArgName on Dog {
  isHousetrained(atOtherHomes: true) @include(unless: false)
}

为了探索更复杂的参数示例，让我们将以下内容添加到我们的类型系统中

type Arguments {
  multipleReqs(x: Int!, y: Int!): Int!
  booleanArgField(booleanArg: Boolean): Boolean
  floatArgField(floatArg: Float): Float
  intArgField(intArg: Int): Int
  nonNullBooleanArgField(nonNullBooleanArg: Boolean!): Boolean!
  booleanListArgField(booleanListArg: [Boolean]!): [Boolean]
}

extend type QueryRoot {
  arguments: Arguments
}

参数中的顺序无关紧要。因此，以下两个示例都是有效的。

fragment multipleArgs on Arguments {
  multipleReqs(x: 1, y: 2)
}

fragment multipleArgsReverseOrder on Arguments {
  multipleReqs(y: 1, x: 2)
}

5.3.2参数唯一性

字段和指令将参数视为从参数名称到值的映射。参数集中存在多个同名参数是模棱两可且无效的。

形式规范

• 对于文档中的每个 argument。
• 令 argumentName 为 argument 的名称。
• 设 arguments 为参数集中所有名为 argumentName 的参数，该参数集包含 argument。
• arguments 必须是仅包含 argument 的集合。

5.3.3参数值类型正确性

fragment goodBooleanArg on Arguments {
  booleanArgField(booleanArg: true)
}

fragment coercedIntIntoFloatArg on Arguments {
  floatArgField(floatArg: 1)
}

fragment stringIntoInt on Arguments {
  intArgField(intArg: "3")
}

fragment goodBooleanArg on Arguments {
  booleanArgField(booleanArg: true)
}

fragment goodNonNullArg on Arguments {
  nonNullBooleanArgField(nonNullBooleanArg: true)
}

fragment goodBooleanArgDefault on Arguments {
  booleanArgField
}

fragment missingRequiredArg on Arguments {
  nonNullBooleanArgField
}

5.4.1片段声明

{
  dog {
    ...fragmentOne
    ...fragmentTwo
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentTwo on Dog {
  owner {
    name
  }
}

{
  dog {
    ...fragmentOne
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentOne on Dog {
  owner {
    name
  }
}

fragment correctType on Dog {
  name
}

fragment inlineFragment on Dog {
  ... on Dog {
    name
  }
}

fragment inlineFragment2 on Dog {
  ... @include(if: true) {
    name
  }
}

fragment notOnExistingType on NotInSchema {
  name
}

fragment inlineNotExistingType on Dog {
  ... on NotInSchema {
    name
  }
}

fragment fragOnObject on Dog {
  name
}

fragment fragOnInterface on Pet {
  name
}

fragment fragOnUnion on CatOrDog {
  ... on Dog {
    name
  }
}

fragment fragOnScalar on Int {
  something
}

fragment inlineFragOnScalar on Dog {
  ... on Boolean {
    somethingElse
  }
}

fragment nameFragment on Dog { # unused
  name
}

{
  dog {
    name
  }
}

5.4.2片段扩展

字段选择也由将片段相互扩展来决定。目标片段的选择集与引用目标片段的级别的选择集合并。

{
  dog {
    ...undefinedFragment
  }
}

{
  dog {
    ...nameFragment
  }
}

fragment nameFragment on Dog {
  name
  ...barkVolumeFragment
}

fragment barkVolumeFragment on Dog {
  barkVolume
  ...nameFragment
}

{
  dog {
    name
    barkVolume
    name
    barkVolume
    name
    barkVolume
    name
    # forever...
  }
}

{
  dog {
    ...dogFragment
  }
}

fragment dogFragment on Dog {
  name
  owner {
    ...ownerFragment
  }
}

fragment ownerFragment on Dog {
  name
  pets {
    ...dogFragment
  }
}

fragment dogFragment on Dog {
  ... on Dog {
    barkVolume
  }
}

fragment catInDogFragmentInvalid on Dog {
  ... on Cat {
    meowVolume
  }
}

fragment petNameFragment on Pet {
  name
}

fragment interfaceWithinObjectFragment on Dog {
  ...petNameFragment
}

fragment catOrDogNameFragment on CatOrDog {
  ... on Cat {
    meowVolume
  }
}

fragment unionWithObjectFragment on Dog {
  ...catOrDogNameFragment
}

fragment petFragment on Pet {
  name
  ... on Dog {
    barkVolume
  }
}

fragment catOrDogFragment on CatOrDog {
  ... on Cat {
    meowVolume
  }
}

fragment sentientFragment on Sentient {
  ... on Dog {
    barkVolume
  }
}

fragment humanOrAlienFragment on HumanOrAlien {
  ... on Cat {
    meowVolume
  }
}

fragment unionWithInterface on Pet {
  ...dogOrHumanFragment
}

fragment dogOrHumanFragment on DogOrHuman {
  ... on Dog {
    barkVolume
  }
}

fragment nonIntersectingInterfaces on Pet {
  ...sentientFragment
}

fragment sentientFragment on Sentient {
  name
}

5.5.1输入对象字段唯一性

形式规范

• 对于文档中的每个输入对象值 inputObject。
• 对于 inputObject 中的每个 inputField
  • 设 name 为 inputField 的名称。
  • 设 fields 为 inputObject 中所有名为 name 的输入对象字段。
  • fields 必须是仅包含 inputField 的集合。

解释性文本

输入对象不能包含多个同名字段，否则会存在歧义，其中包括被忽略的语法部分。

例如，以下查询将无法通过验证。

{
  field(arg: { field: true, field: false })
}

5.6.1指令已定义

形式规范

• 对于文档中的每个 directive。
• 设 directiveName 为 directive 的名称。
• 设 directiveDefinition 为名为 directiveName 的指令。
• directiveDefinition 必须存在。

解释性文本

GraphQL 服务器定义了它们支持的指令。对于指令的每次使用，该指令必须在服务器上可用。

5.6.2指令位于有效位置

形式规范

• 对于文档中的每个 directive。
• 设 directiveName 为 directive 的名称。
• 设 directiveDefinition 为名为 directiveName 的指令。
• 设 locations 为 directiveDefinition 的有效位置。
• 设 adjacent 为指令影响的 AST 节点。
• adjacent 必须由 locations 中的一个项表示。

解释性文本

GraphQL 服务器定义了它们支持的指令以及它们支持指令的位置。对于指令的每次使用，该指令必须在服务器已声明支持的位置使用。

例如，以下查询将无法通过验证，因为 @skip 未将 QUERY 作为有效位置提供。

query @skip(if: $foo) {
  field
}

5.7.1变量唯一性

形式规范

• 对于文档中的每个 operation
  • 对于在 operation 上定义的每个 variable
    • 设 variableName 为 variable 的名称
    • 设 variables 为 operation 上所有名为 variableName 的变量的集合
    • variables 必须是由一个变量组成的集合

解释性文本

如果任何操作定义了多个同名变量，则它是模棱两可且无效的。即使重复变量的类型相同，它也是无效的。

query houseTrainedQuery($atOtherHomes: Boolean, $atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

多个操作定义具有相同名称的变量是有效的。如果两个操作引用相同的片段，则实际上可能是必要的

query A($atOtherHomes: Boolean) {
  ...HouseTrainedFragment
}

query B($atOtherHomes: Boolean) {
  ...HouseTrainedFragment
}

fragment HouseTrainedFragment {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

5.7.2变量默认值类型正确

形式规范

• 对于文档中的每个 operation
• 对于每个 operation 上的每个 variable
  • 设 variableType 为 variable 的类型
  • 如果 variableType 是非空类型，则它不能具有默认值
  • 如果 variable 具有默认值，则它必须与 variableType 的类型相同或能够强制转换为 variableType

解释性文本

操作定义的变量如果其类型不是非空类型，则允许定义默认值。

例如，以下查询将通过验证。

query houseTrainedQuery($atOtherHomes: Boolean = true) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

但是，如果变量被定义为非空类型，则默认值是无法访问的。因此，诸如以下查询将无法通过验证

query houseTrainedQuery($atOtherHomes: Boolean! = true) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

默认值必须与变量的类型兼容。类型必须匹配，或者它们必须可强制转换为该类型。

不匹配的类型将失败，例如在以下示例中

query houseTrainedQuery($atOtherHomes: Boolean = "true") {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

但是，如果类型是可强制转换的，则查询将通过验证。

例如：

query intToFloatQuery($floatVar: Float = 1) {
  arguments {
    floatArgField(floatArg: $floatVar)
  }
}

5.7.3变量是输入类型

形式规范

• 对于 document 中的每个 operation
• 对于每个 operation 上的每个 variable
  • 设 variableType 为 variable 的类型
  • 当 variableType 是 LIST 或 NON_NULL 时
    • 设 variableType 为 variableType 的引用类型
  • variableType 必须是 SCALAR、ENUM 或 INPUT_OBJECT 类型

解释性文本

变量只能是标量、枚举、输入对象或这些类型的列表和非空变体。这些被称为输入类型。对象、联合类型和接口类型不能用作输入。

对于这些示例，请考虑以下类型系统添加

input ComplexInput { name: String, owner: String }

extend type QueryRoot {
  findDog(complex: ComplexInput): Dog
  booleanList(booleanListArg: [Boolean!]): Boolean
}

以下查询是有效的

query takesBoolean($atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

query takesComplexInput($complexInput: ComplexInput) {
  findDog(complex: $complexInput) {
    name
  }
}

query TakesListOfBooleanBang($booleans: [Boolean!]) {
  booleanList(booleanListArg: $booleans)
}

以下查询是无效的

query takesCat($cat: Cat) {
  # ...
}

query takesDogBang($dog: Dog!) {
  # ...
}

query takesListOfPet($pets: [Pet]) {
  # ...
}

query takesCatOrDog($catOrDog: CatOrDog) {
  # ...
}

5.7.4所有变量使用已定义

形式规范

• 对于文档中的每个 operation
  • 对于范围内的每个 variableUsage，变量必须是操作的变量列表。
  • 设 fragments 为该操作传递引用的每个片段
  • 对于 fragments 中的每个 fragment
    • 对于 fragment 范围内的每个 variableUsage，变量必须是 operation 的变量列表。

解释性文本

变量的作用域是基于每个操作的。这意味着在操作上下文中使用的任何变量都必须在该操作的顶层定义

例如：

query variableIsDefined($atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

是有效的。$atOtherHomes 由操作定义。

相比之下，以下查询是无效的

query variableIsNotDefined {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

$atOtherHomes 未由操作定义。

片段使此规则变得复杂。操作传递包含的任何片段都可以访问该操作定义的变量。片段可以出现在多个操作中，因此变量的使用必须与所有这些操作中的变量定义相对应。

例如，以下是有效的

query variableIsDefinedUsedInSingleFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

因为 isHousetrainedFragment 在操作 variableIsDefinedUsedInSingleFragment 的上下文中被使用，并且变量由该操作定义。

另一方面，如果片段包含在未定义引用变量的操作中，则查询是无效的。

query variableIsNotDefinedUsedInSingleFragment {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

这也适用于传递性，因此以下操作也会失败

query variableIsNotDefinedUsedInNestedFragment {
  dog {
    ...outerHousetrainedFragment
  }
}

fragment outerHousetrainedFragment on Dog {
  ...isHousetrainedFragment
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

变量必须在片段使用的所有操作中定义。

query housetrainedQueryOne($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query housetrainedQueryTwo($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

但是，以下操作无法通过验证

query housetrainedQueryOne($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query housetrainedQueryTwoNotDefined {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

这是因为 housetrainedQueryTwoNotDefined 未定义变量 $atOtherHomes，但该变量被 isHousetrainedFragment 使用，而 isHousetrainedFragment 包含在该操作中。

5.7.5所有变量已使用

形式规范

• 对于文档中的每个 operation。
• 设 variables 为该 operation 定义的变量
• variables 中的每个 variable 必须在操作范围本身或该操作传递引用的任何片段中至少使用一次。

解释性文本

操作定义的所有变量都必须在该操作或该操作传递包含的片段中使用。未使用的变量会导致验证错误。

例如，以下操作是无效的

query variableUnused($atOtherHomes: Boolean) {
  dog {
    isHousetrained
  }
}

因为 $atOtherHomes 未被引用。

这些规则也适用于传递片段扩展

query variableUsedInFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

以上操作是有效的，因为 $atOtherHomes 在 isHousetrainedFragment 中使用，而 isHousetrainedFragment 由 variableUsedInFragment 包含。

如果该片段没有对 $atOtherHomes 的引用，则它将无效

query variableNotUsedWithinFragment($atOtherHomes: Boolean) {
  ...isHousetrainedWithoutVariableFragment
}

fragment isHousetrainedWithoutVariableFragment on Dog {
  isHousetrained
}

文档中的所有操作都必须使用它们的所有变量。

因此，以下文档无法通过验证。

query queryWithUsedVar($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query queryWithExtraVar($atOtherHomes: Boolean, $extra: Int) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

此文档无效，因为 queryWithExtraVar 定义了一个无关的变量。

5.7.6所有变量使用均被允许

形式规范

• 对于 document 中的每个 operation
• 设 variableUsages 为传递包含在 operation 中的所有用法
• 对于 variableUsages 中的每个 variableUsage
  • 设 variableType 为操作中变量定义的类型
  • 设 argumentType 为变量传递到的参数的类型。
  • 如果变量定义定义了默认值，则设 hasDefault 为 true。
  • AreTypesCompatible(argumentType, variableType, hasDefault) 必须为 true
• AreTypesCompatible(argumentType, variableType, hasDefault)
  • 如果 hasDefault 为 true，则将 variableType 视为非空类型。
  • 如果 argumentType 和 variableType 的内部类型不同，则返回 false
  • 如果 argumentType 和 variableType 具有不同的列表维度，则返回 false
  • 如果 variableType 的任何列表级别不是非空类型，并且 argument 中对应的级别是非空类型，则类型不兼容。

解释性文本

变量的使用必须与它们传递到的参数兼容。

当变量在完全不匹配的类型的上下文中，或者当可为空类型中的变量传递给非空参数类型时，会发生验证失败。

类型必须匹配

query intCannotGoIntoBoolean($intArg: Int) {
  arguments {
    booleanArgField(booleanArg: $intArg)
  }
}

类型为 Int 的 $intArg 不能用作类型为 Boolean 的 booleanArg 的参数。

列表基数也必须相同。例如，列表不能传递到单个值中。

query booleanListCannotGoIntoBoolean($booleanListArg: [Boolean]) {
  arguments {
    booleanArgField(booleanArg: $booleanListArg)
  }
}

空值性也必须受到尊重。通常，可为空的变量不能传递给非空参数。

query booleanArgQuery($booleanArg: Boolean) {
  arguments {
    nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)
  }
}

一个值得注意的例外是提供默认参数时。实际上，它们被视为非空值。

query booleanArgQueryWithDefault($booleanArg: Boolean = true) {
  arguments {
    nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)
  }
}

对于列表类型，围绕空值性的相同规则适用于外部类型和内部类型。可为空的列表不能传递给非空列表，并且可为空值的列表不能传递给非空值的列表。以下是有效的

query nonNullListToList($nonNullBooleanList: [Boolean]!) {
  arguments {
    booleanListArgField(booleanListArg: $nonNullBooleanList)
  }
}

但是，可为空的列表不能传递给非空列表

query listToNonNullList($booleanList: [Boolean]) {
  arguments {
    nonNullBooleanListField(nonNullBooleanListArg: $booleanList)
  }
}

这将导致验证失败，因为 [T] 不能传递给 [T]!。

同样，[T] 不能传递给 [T!]。

6.6.1字段条目

分组字段集中的每个条目都可能在结果映射中创建一个条目。结果映射中的该条目是对分组字段集中的相应条目调用 GetFieldEntry 的结果。GetFieldEntry 可以返回 null，这表示此条目在结果映射中不应存在。请注意，这与返回一个带有字符串键和空值的条目是不同的，后者表示应为该键添加一个条目，并且其值应为空。

GetFieldEntry 假定存在两个未在本规范的此部分中定义的函数。预计类型系统会提供这些方法

• ResolveFieldOnObject，它接受对象类型、字段和对象，并返回在该对象上解析该字段的结果。
• GetFieldTypeFromObjectType，它接受对象类型和字段，并返回该字段在对象类型上的类型；如果该字段在对象类型上无效，则返回 null。

6.6.2正常评估

当在没有串行执行顺序要求的情况下评估分组字段集时，执行器可以按其选择的任何顺序确定结果映射中的条目。由于除了顶级 mutation 字段之外的字段的解析始终是无副作用且幂等的，因此执行顺序不得影响结果，因此服务器可以自由地按其认为最佳的任何顺序评估字段条目。

例如，给定以下要正常评估的分组字段集

{
  birthday {
    month
  }
  address {
    street
  }
}

有效的 GraphQL 执行器可以按其选择的任何顺序解析这四个字段。

6.6.3串行执行

请注意，根据以上各节，执行器将以串行执行顺序运行的唯一情况是在 mutation 操作的顶级选择集及其对应的分组字段集上。

当串行评估分组字段集时，执行器必须按照分组字段集中提供的顺序考虑分组字段集中的每个条目。它必须在继续处理分组字段集中的下一个条目之前，确定每个条目在结果映射中的对应条目并完成操作。

例如，给定以下要串行评估的选择集

{
  changeBirthday(birthday: $newBirthday) {
    month
  }
  changeAddress(address: $newAddress) {
    street
  }
}

执行器必须串行地执行以下操作

• 为 changeBirthday 运行 getFieldEntry，它在 CompleteValue 期间将正常评估 { month } 子选择集。
• 为 changeAddress 运行 getFieldEntry，它在 CompleteValue 期间将正常评估 { street } 子选择集。

作为一个说明性示例，假设我们有一个 mutation 字段 changeTheNumber，它返回一个包含一个字段 theNumber 的对象。如果我们串行执行以下选择集

{
  first: changeTheNumber(newNumber: 1) {
    theNumber
  }
  second: changeTheNumber(newNumber: 3) {
    theNumber
  }
  third: changeTheNumber(newNumber: 2) {
    theNumber
  }
}

执行器将串行评估以下内容

• 解析 changeTheNumber(newNumber: 1) 字段
• 正常评估 first 的 { theNumber } 子选择集
• 解析 changeTheNumber(newNumber: 3) 字段
• 正常评估 second 的 { theNumber } 子选择集
• 解析 changeTheNumber(newNumber: 2) 字段
• 正常评估 third 的 { theNumber } 子选择集

正确的执行器必须为该选择集生成以下结果

{
  "first": {
    "theNumber": 1
  },
  "second": {
    "theNumber": 3
  },
  "third": {
    "theNumber": 2
  }
}

6.6.4可空性

如果解析字段的结果为 null（无论是由于解析字段的函数返回 null 还是由于发生错误），并且该字段的类型为 Non-Null 类型，则会抛出一个字段错误。

如果字段为 null 是因为已添加到响应中的 "errors" 列表中的错误，则 "errors" 列表不得进一步受到影响。

如果字段解析函数返回 null，则必须将生成的字段错误添加到响应中的 "errors" 列表。

6.6.5错误处理

如果在解析字段时发生错误，则应将其视为字段返回了 null，并且必须将错误添加到响应中的 "errors" 列表。

但是，如果该字段的类型为 Non-Null 类型，由于字段不能为 null，因此错误会传播到父字段进行处理。

如果从请求的根到错误源的所有字段都返回 Non-Null 类型，则响应中的 "data" 条目应为 null。

7.1.1JSON 序列化

JSON 是 GraphQL 的首选序列化格式，尽管如上所述，GraphQL 不要求特定的序列化格式。为了保持一致性和易于表示，整个规范中的响应示例均以 JSON 给出。特别是，在我们的 JSON 示例中，我们将使用以下 JSON 概念表示原语

7.2.1数据

响应中的 data 条目将是执行所请求操作的结果。如果操作是查询，则此输出将是模式的查询根类型的对象；如果操作是 mutation，则此输出将是模式的 mutation 根类型的对象。

如果在执行开始之前遇到错误，则 data 条目不应出现在结果中。

如果在执行期间遇到阻止有效响应的错误，则响应中的 data 条目应为 null。

7.2.2错误

响应中的 errors 条目是一个非空错误列表，其中每个错误都是一个映射。

如果在请求的操作期间未遇到任何错误，则 errors 条目不应出现在结果中。

每个错误都必须包含一个键为 message 的条目，其中包含错误描述的字符串，供开发人员理解和纠正错误。

如果错误可以与请求的 GraphQL 文档中的特定点关联，则它应包含一个键为 locations 的条目，其中包含位置列表，其中每个位置都是一个包含键 line 和 column 的映射，两者都是从 1 开始的正数，用于描述关联的语法元素的开头。

GraphQL 服务器可以根据需要为错误提供其他条目，以生成更有帮助或机器可读的错误，但是，规范的未来版本可能会描述错误的附加条目。

如果响应中的 data 条目为 null 或不存在，则响应中的 errors 条目不得为空。它必须至少包含一个错误。它包含的错误应指示为什么无法返回任何数据。

如果响应中的 data 条目不为 null，则响应中的 errors 条目可能包含执行期间发生的任何错误。如果在执行期间发生错误，则应包含这些错误。