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.1整数值

整数以不带小数点或指数的形式指定（例如，1）。

2.9.2浮点数值

浮点数包括小数点（例如，1.0）或指数（例如，1e50）或两者（例如，6.0221413e23）。

2.9.3布尔值

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

2.9.4字符串值

字符串是以双引号 (") 包裹的字符序列。（例如，"Hello World"）。空白字符和其他原本被忽略的字符在字符串值中很重要。

语义

2.9.5空值

空值用关键字 null 表示。

GraphQL 有两种语义上不同的方式来表示值的缺失

• 显式提供字面值：null。
• 隐式完全不提供值。

例如，以下两个字段调用类似，但并不相同

{
  field(arg: null)
  field
}

第一个显式地为参数 “arg” 提供了 null，而第二个隐式地没有为参数 “arg” 提供值。这两种形式的解释可能不同。例如，一个 mutation 可能表示删除一个字段，而另一个可能表示不更改字段。两种形式都不能用于期望 Non-Null 类型的输入。

2.9.6枚举值

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

2.9.7列表值

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

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

语义

2.9.8输入对象值

输入对象字面值是用大括号 { } 包裹的键值输入值的无序列表。对象字面值的值可以是任何输入值字面值或变量（例如 { 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。

服务器可以从其模式中省略任何内置标量，例如，如果模式不引用浮点数，则它将不包含 Float 类型。但是，如果模式包含名称与此处描述的类型之一相同的类型，则它必须遵守所描述的行为。例如，服务器不得包含名为 Int 的类型并将其用于表示 128 位数字或国际化信息。

结果强制转换

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

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

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

输入强制转换

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

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

对于以下所有类型，除了 Non-Null 之外，如果提供了显式值 null，则输入强制转换的结果为 null。

内置标量

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 对象上的字段具有相同的规则；它们的类型可以是标量、对象、枚举、接口或联合，或任何包装类型，其基本类型是这五种类型之一。

例如，接口可以描述必需的字段，然后诸如 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，则应抛出错误。

强制转换的结果是一个环境特定的无序映射，为输入对象类型定义和原始值提供的每个字段定义了槽位。

对于输入对象类型的每个字段，如果原始值具有同名的条目，并且该条目处的值是字面量值或已提供运行时值的变量，则会将一个条目添加到结果中，其名称与该字段的名称相同。

结果中该条目的值是根据输入字段声明的类型输入强制转换规则对原始条目值进行输入强制转换的结果。

以下是类型为输入对象强制转换的示例

input ExampleInputObject {
  a: String
  b: Int!
}

3.1.7列表

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

结果强制转换

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

输入强制转换

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

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

3.1.8非空

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

可空 vs. 可选

在查询的上下文中，字段始终是可选的，可以省略字段，查询仍然有效。但是，如果查询返回非空类型的字段，则永远不会返回 null 值。

输入（例如字段参数）默认情况下始终是可选的。但是，非空输入类型是必需的。除了不接受值 null 外，它也不接受省略。为了简单起见，可空类型始终是可选的，而非空类型始终是必需的。

结果强制转换

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

输入强制转换

如果未提供非空类型的参数或输入对象字段，或者提供了字面量值 null，或者提供了运行时未提供值或提供了值 null 的变量，则必须引发查询错误。

如果为非空类型提供的值是字面量值（null 除外）或非空变量值，则使用包装类型的输入强制转换对其进行强制转换。

{
  fieldWithNonNullArg
}

{
  fieldWithNonNullArg(nonNullArg: null)
}

query withNullableVariable($var: String) {
  fieldWithNonNullArg(nonNullArg: $var)
}

非空类型验证

1. 非空类型不得包装另一个非空类型。

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文档

内省系统中的所有类型都提供类型为 String 的 description 字段，以允许类型设计者发布文档以及功能。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
}

fragment missingRequiredArg on Arguments {
  notNullBooleanArgField(nonNullBooleanArg: null)
}

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.6.3指令在每个位置都是唯一的

形式规范

• 对于文档中指令可以应用的每个 location
  • 设 directives 为应用于 location 的指令集。
  • 对于 directives 中的每个 directive
    • 设 directiveName 为 directive 的名称。
    • 设 namedDirectives 为 directives 中所有名为 directiveName 的指令集。
    • namedDirectives 必须是一个单元素集合。

解释性文本

指令用于描述它们所应用的定义上的某些元数据或行为更改。当使用多个同名指令时，预期的元数据或行为变得模糊，因此每个位置只允许一个指令。

例如，以下查询将无法通过验证，因为 @skip 已对同一字段使用了两次

query ($foo: Boolean = true, $bar: Boolean = false) {
  field @skip(if: $foo) @skip(if: $bar)
}

但是，以下示例是有效的，因为 @skip 每个位置仅使用一次，尽管在查询中和在同一命名字段上使用了两次

query ($foo: Boolean = true, $bar: Boolean = false) {
  field @skip(if: $foo) {
    subfieldA
  }
  field @skip(if: $bar) {
    subfieldB
  }
}

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，变量必须在 operation 的变量列表中。
  • 设 fragments 为该 operation 传递引用的每个片段
  • 对于 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 为 operation 中变量定义的类型
  • 设 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.1.1验证请求

如“验证”部分所述，只有通过所有验证规则的请求才应执行。如果已知存在验证错误，则应在响应的“errors”列表中报告这些错误，并且请求必须失败，而无需执行。

通常，验证是在紧接执行之前的请求上下文中执行的，但是，如果已知完全相同的请求以前已通过验证，则 GraphQL 服务可以在不立即验证它的情况下执行请求。GraphQL 服务应仅执行在某个时刻已知没有任何验证错误，并且此后未更改的请求。

例如：请求可以在开发期间进行验证，前提是它以后不会更改，或者服务可以验证一次请求并记忆结果，以避免将来再次验证相同的请求。

6.1.2强制变量值

如果操作定义了任何变量，则需要使用变量声明类型的输入强制规则来强制这些变量的值。如果在变量值的输入强制期间遇到查询错误，则操作将失败，而无需执行。

6.3.1正常执行和串行执行

通常，执行器可以以其选择的任何顺序（通常是并行）执行分组字段集中的条目。由于除顶层变更字段以外的字段的解析必须始终是无副作用和幂等的，因此执行顺序不得影响结果，因此服务器可以自由地以其认为最佳的任何顺序执行字段条目。

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

{
  birthday {
    month
  }
  address {
    street
  }
}

有效的 GraphQL 执行器可以以其选择的任何顺序解析这四个字段（当然，birthday 必须在 month 之前解析，address 必须在 street 之前解析）。

执行变更时，最顶层选择集中的选择将按串行顺序执行。

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

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

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

执行器必须串行地

• 运行 changeBirthday 的 ExecuteField()，这在 CompleteValue() 期间将正常执行 { month } 子选择集。
• 运行 changeAddress 的 ExecuteField()，这在 CompleteValue() 期间将正常执行 { street } 子选择集。

作为一个说明性示例，让我们假设我们有一个变更字段 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.3.2字段收集

在执行之前，选择集通过调用 CollectFields() 转换为分组字段集。分组字段集中的每个条目都是共享响应键的字段列表。这确保了通过引用的片段包含的具有相同响应键（别名或字段名称）的所有字段都同时执行。

例如，收集此选择集的字段将收集字段 a 的两个实例和一个字段 b 的实例

{
  a {
    subfield1
  }
  ...ExampleFragment
}

fragment ExampleFragment on Query {
  a {
    subfield2
  }
  b
}

通过 CollectFields() 生成的字段组的深度优先搜索顺序在执行过程中保持不变，从而确保字段以稳定且可预测的顺序出现在执行的响应中。

6.4.1强制转换字段参数

字段可以包含提供给底层运行时的参数，以便正确生成值。这些参数由类型系统中的字段定义为具有特定的输入类型：标量、枚举、输入对象，或这三者的列表或非空包装的变体。

在查询中的每个参数位置，可以是一个字面量值或一个在运行时提供的变量。

6.4.2值解析

虽然几乎所有的 GraphQL 执行都可以被通用地描述，但最终，暴露 GraphQL 接口的内部系统必须提供值。这通过 ResolveFieldValue 公开，它为一个类型上的给定字段生成一个实际值。

例如，这可能接受 objectType Person，field "soulMate"，以及代表 John Lennon 的 objectValue。预计它将产生代表 Yoko Ono 的值。

6.4.3值完成

在解析字段的值之后，通过确保它符合预期的返回类型来完成它。如果返回类型是另一个对象类型，则字段执行过程将递归地继续。

解析抽象类型

当完成具有抽象返回类型的字段时，即接口或联合返回类型，首先必须将抽象类型解析为相关的对象类型。这种确定由内部系统使用任何适当的方式进行。

合并选择集

当并行执行多个同名字段时，它们的选择集在完成值时合并在一起，以便继续执行子选择集。

一个示例查询，说明具有相同名称和子选择的并行字段。

{
  me {
    firstName
  }
  me {
    lastName
  }
}

在解析 me 的值之后，选择集合并在一起，以便可以为一个值解析 firstName 和 lastName。

6.4.4错误和不可为空性

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

如果解析字段的结果是 null （无论是由于解析字段的函数返回 null 还是由于发生了错误），并且该字段是 Non-Null 类型，则会抛出一个字段错误。该错误必须添加到响应中的 "errors" 列表中。

如果字段由于已添加到响应中的 "errors" 列表中的错误而返回 null，则 "errors" 列表不得进一步受到影响。也就是说，每个字段只能向 errors 列表添加一个错误。

由于 Non-Null 类型字段不能为 null，因此字段错误会传播到父字段进行处理。如果父字段可以为 null，则它解析为 null；否则，如果它是 Non-Null 类型，则字段错误会进一步传播到其父字段。

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

7.1.1JSON 序列化

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

对象属性排序

虽然 JSON 对象被指定为 键值对的无序集合，但这些对以有序的方式表示。换句话说，虽然 JSON 字符串 { "name": "Mark", "age": 30 } 和 { "age": 30, "name": "Mark" } 编码相同的值，但它们也具有可观察到的不同属性排序。

由于评估选择集的结果是有序的，因此序列化的 JSON 对象应通过以与查询执行定义的请求字段相同的顺序写入对象属性来保留此顺序。

例如，如果查询是 { name, age }，则以 JSON 响应的 GraphQL 服务器应响应 { "name": "Mark", "age": 30 }，而不应响应 { "age": 30, "name": "Mark" }。

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 条目可能包含执行期间发生的任何错误。如果执行期间发生错误，则应包含这些错误。