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 数据模型上的查询中

Example № 21query 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 将不存在。

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

2.8.2内联片段

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

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

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

Example № 24query 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"）。空格和其他原本被忽略的字符在字符串值中具有意义。

块字符串

块字符串是用三引号 (""") 包裹的字符序列。空格、行终止符、引号和反斜杠字符都可以不转义地使用，以启用原文文本。字符必须都是有效的 源字符。

由于块字符串表示通常在缩进位置使用的自由格式文本，因此块字符串的字符串值语义通过 BlockStringValue() 排除统一的缩进以及初始和尾随的空白行。

例如，以下包含块字符串的操作

Example № 25mutation {
  sendEmail(message: """
    Hello,
      World!

    Yours,
      GraphQL.
  """)
}

与标准引号字符串相同

Example № 26mutation {
  sendEmail(message: "Hello,\n  World!\n\nYours,\n  GraphQL.")
}

由于块字符串值会去除前导和尾随的空行，因此对于给定的值，没有唯一的规范打印块字符串。由于块字符串通常表示自由格式文本，因此如果它们以空行开始和结束，则认为更易于阅读。

Example № 27"""
This starts with and ends with an empty line,
which makes it easier to read.
"""

Counter Example № 28"""This does not start with or end with any empty lines,
which makes it a little harder to read."""

语义

2.9.5空值

空值表示为关键字 null。

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

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

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

Example № 29{
  field(arg: null)
  field
}

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

2.9.6枚举值

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

2.9.7列表值

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

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

语义

2.9.8输入对象值

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

输入对象字段是无序的

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

这两个查询在语义上是相同的

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

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

语义

3.2.1根操作类型

schema 为其支持的每种操作（查询、突变和订阅）定义初始根操作类型；这决定了这些操作在类型系统中开始的位置。

必须提供 query 根操作类型，并且必须是对象类型。

mutation 根操作类型是可选的；如果未提供，则服务不支持突变。如果提供了，则必须是对象类型。

类似地，subscription 根操作类型也是可选的；如果未提供，则服务不支持订阅。如果提供了，则必须是对象类型。

query 根操作类型上的字段指示在 GraphQL 查询的顶层可用的字段。例如，基本的 GraphQL 查询，如

Example № 34query {
  myName
}

当 query 根操作类型具有名为 “myName” 的字段时有效。

Example № 35type Query {
  myName: String
}

同样地，如果 mutation 根操作类型有一个名为“setName”的字段，则以下 mutation 是有效的。请注意，query 和 mutation 根类型必须是不同的类型。

Example № 36mutation {
  setName(name: "Zuck") {
    newName
  }
}

当使用类型系统定义语言时，一个文档最多只能包含一个 schema 定义。

在此示例中，GraphQL 模式定义了 query 和 mutation 根类型

Example № 37schema {
  query: MyQueryRootType
  mutation: MyMutationRootType
}

type MyQueryRootType {
  someField: String
}

type MyMutationRootType {
  setSomeField(to: String): String
}

默认根操作类型名称

虽然任何类型都可以作为 GraphQL 操作的根操作类型，但当 query、mutation 和 subscription 根类型分别命名为 Query、Mutation 和 Subscription 时，类型系统定义语言可以省略 schema 定义。

同样地，当使用类型系统定义语言表示 GraphQL 模式时，如果模式仅使用默认根操作类型名称，则应省略 schema 定义。

此示例描述了一个有效的完整 GraphQL 模式，尽管未显式包含 schema 定义。Query 类型被推定为模式的 query 根操作类型。

Example № 38type Query {
  someField: String
}

3.2.2模式扩展

模式扩展用于表示从原始模式扩展而来的模式。例如，GraphQL 服务可能会使用它来向现有模式添加额外的操作类型或额外的指令。

模式验证

如果模式扩展定义不正确，则可能无效。

1. 模式必须已定义。
2. 提供的任何指令都不得已应用于原始模式。

3.4.1包装类型

到目前为止，所有类型都被假定为既可为空又为单数：例如，标量字符串返回 null 或单个字符串。

GraphQL 模式可以描述一个字段表示另一种类型的列表；为此提供了 List 类型，并包装了另一种类型。

类似地，Non-Null 类型包装了另一种类型，并表示结果值永远不会是 null（并且错误不会导致 null 值）。

这两种类型被称为“包装类型”；非包装类型被称为“命名类型”。包装类型具有一个底层命名类型，通过不断解包类型直到找到命名类型为止。

3.4.2输入和输出类型

类型在整个 GraphQL 中用于描述作为参数和变量输入接受的值，以及字段输出的值。这两种用途将类型分类为输入类型和输出类型。某些类型的类型，如标量和枚举类型，既可以用作输入类型，也可以用作输出类型；其他类型的类型只能用于其中一种。输入对象类型只能用作输入类型。对象、接口和联合类型只能用作输出类型。列表和非空类型可以用作输入类型或输出类型，具体取决于包装类型的使用方式。

3.4.3类型扩展

类型扩展用于表示从某些原始类型扩展而来的 GraphQL 类型。例如，本地服务可以使用它来表示 GraphQL 客户端仅在本地访问的额外字段。

3.5.1Int

Int 标量类型表示有符号 32 位数字非小数数值。支持 32 位整数或数字类型的响应格式应使用该类型来表示此标量。

结果强制转换

返回 Int 类型的字段期望遇到 32 位整数内部值。

当 GraphQL 服务器在不丢失信息的情况下合理地将非整数内部值强制转换为整数时，它们可能会这样做，否则它们必须引发字段错误。这方面的例子可能包括为浮点数 1.0 返回 1，或为字符串 "123" 返回 123。在强制转换可能丢失数据的情况下，引发字段错误更为合适。例如，浮点数 1.2 应引发字段错误，而不是被截断为 1。

如果整数内部值表示小于 -2³¹ 或大于或等于 2³¹ 的值，则应引发字段错误。

输入强制转换

当预期作为输入类型时，仅接受整数输入值。所有其他输入值，包括具有数字内容的字符串，都必须引发查询错误，指示类型不正确。如果整数输入值表示小于 -2³¹ 或大于或等于 2³¹ 的值，则应引发查询错误。

3.5.2Float

Float 标量类型表示由 IEEE 754 指定的有符号双精度小数数值。支持适当双精度数字类型的响应格式应使用该类型来表示此标量。

结果强制转换

返回 Float 类型的字段期望遇到双精度浮点内部值。

当 GraphQL 服务器在不丢失信息的情况下合理地将非浮点内部值强制转换为 Float 时，它们可能会这样做，否则它们必须引发字段错误。这方面的例子可能包括为整数 1 返回 1.0，或为字符串 "123" 返回 123.0。

输入强制转换

当预期作为输入类型时，整数和浮点输入值都被接受。整数输入值通过添加空的小数部分强制转换为 Float，例如，整数输入值 1 的值为 1.0。所有其他输入值，包括具有数字内容的字符串，都必须引发查询错误，指示类型不正确。如果整数输入值表示 IEEE 754 无法表示的值，则应引发查询错误。

3.5.3String

String 标量类型表示文本数据，表示为 UTF‐8 字符序列。String 类型最常被 GraphQL 用于表示自由形式的人类可读文本。所有响应格式都必须支持字符串表示形式，并且此处必须使用该表示形式。

结果强制转换

返回 String 类型的字段期望遇到 UTF‐8 字符串内部值。

当 GraphQL 服务器在不丢失信息的情况下合理地将非字符串原始值强制转换为 String 时，它们可能会这样做，否则它们必须引发字段错误。这方面的例子可能包括为布尔值 true 返回字符串 "true"，或为整数 1 返回字符串 "1"。

输入强制转换

当预期作为输入类型时，仅接受有效的 UTF‐8 字符串输入值。所有其他输入值都必须引发查询错误，指示类型不正确。

3.5.4Boolean

Boolean 标量类型表示 true 或 false。响应格式应使用内置布尔类型（如果支持）；否则，它们应使用整数 1 和 0 的表示形式。

结果强制转换

返回 Boolean 类型的字段期望遇到布尔内部值。

当 GraphQL 服务器在不丢失信息的情况下合理地将非布尔原始值强制转换为 Boolean 时，它们可能会这样做，否则它们必须引发字段错误。这方面的例子可能包括为非零数字返回 true。

输入强制转换

当预期作为输入类型时，仅接受布尔输入值。所有其他输入值都必须引发查询错误，指示类型不正确。

3.5.5ID

ID 标量类型表示唯一标识符，通常用于重新获取对象或作为缓存的键。ID 类型的序列化方式与 String 相同；但是，它不应该是人类可读的。虽然它通常是数字，但它应始终序列化为 String。

结果强制转换

GraphQL 与 ID 格式无关，并序列化为字符串以确保 ID 可能表示的多种格式的一致性，从小的自动递增数字到大的 128 位随机数，到 base64 编码值，或格式如 GUID 的字符串值。

GraphQL 服务器应根据它们期望的 ID 格式进行适当的强制转换。当无法进行强制转换时，它们必须引发字段错误。

输入强制转换

当预期作为输入类型时，任何字符串（例如 "4"）或整数（例如 4）输入值都应根据给定 GraphQL 服务器期望的 ID 格式强制转换为 ID。任何其他输入值，包括浮点输入值（例如 4.0），都必须引发查询错误，指示类型不正确。

3.5.6标量扩展

标量类型扩展用于表示从某些原始标量类型扩展而来的标量类型。例如，GraphQL 工具或服务可以使用它来向现有标量添加指令。

类型验证

如果标量类型扩展定义不正确，则可能无效。

1. 命名类型必须已定义，并且必须是标量类型。
2. 提供的任何指令都不得已应用于原始标量类型。

3.6.1字段参数

对象字段在概念上是产生值的函数。有时，对象字段可以接受参数以进一步指定返回值。对象字段参数被定义为所有可能的参数名称及其预期输入类型的列表。

字段中定义的所有参数都不得具有以 "__"（两个下划线）开头的名称，因为这由 GraphQL 的内省系统独占使用。

例如，具有 picture 字段的 Person 类型可以接受一个参数来确定要返回的图像大小。

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

GraphQL 查询可以选择性地为其字段指定参数以提供这些参数。

此示例查询

Example № 57{
  name
  picture(size: 600)
}

可能产生结果

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

对象字段参数的类型必须是输入类型（对象、接口或联合类型以外的任何类型）。

3.6.2字段弃用

对象中的字段可以根据应用程序的需要标记为已弃用。查询这些字段仍然是合法的（以确保现有客户端不会因更改而中断），但应在文档和工具中对这些字段进行适当处理。

当使用类型系统定义语言时，@deprecated 指令用于指示字段已被弃用

Example № 59type ExampleType {
  oldField: String @deprecated
}

3.6.3对象扩展

对象类型扩展用于表示从某些原始类型扩展而来的类型。例如，这可以用于表示本地数据，或者由本身是另一个 GraphQL 服务的扩展的 GraphQL 服务使用。

在此示例中，本地数据字段被添加到 Story 类型

Example № 60extend type Story {
  isHiddenLocally: Boolean
}

对象类型扩展可以选择不添加额外的字段，而是仅添加接口或指令。

在此示例中，指令被添加到 User 类型，而没有添加字段

Example № 61extend type User @addedDirective

类型验证

如果对象类型扩展定义不正确，则可能无效。

1. 命名的类型必须已定义，并且必须是对象类型。
2. 对象类型扩展的字段必须具有唯一的名称；任何两个字段都不得共享相同的名称。
3. 对象类型扩展的任何字段都不得已在原始对象类型上定义。
4. 提供的任何指令都不得已应用于原始对象类型。
5. 提供的任何接口都不得已被原始对象类型实现。
6. 最终扩展的对象类型必须是其实现的所有接口的超集。

3.7.1接口扩展

接口类型扩展用于表示从某些原始接口扩展而来的接口。例如，这可以用于表示许多类型上的通用本地数据，或者由本身是另一个 GraphQL 服务的扩展的 GraphQL 服务使用。

在此示例中，扩展数据字段被添加到 NamedEntity 类型以及实现它的类型

Example № 67extend interface NamedEntity {
  nickname: String
}

extend type Person {
  nickname: String
}

extend type Business {
  nickname: String
}

接口类型扩展可以选择不添加额外的字段，而是仅添加指令。

在此示例中，指令被添加到 NamedEntity 类型，而没有添加字段

Example № 68extend interface NamedEntity @addedDirective

类型验证

如果接口类型扩展定义不正确，则可能无效。

1. 命名的类型必须已定义，并且必须是接口类型。
2. 接口类型扩展的字段必须具有唯一的名称；任何两个字段都不得共享相同的名称。
3. 接口类型扩展的任何字段都不得已在原始接口类型上定义。
4. 任何实现了原始接口类型的对象类型也必须是接口类型扩展字段的超集（这可能是由于对象类型扩展）。
5. 提供的任何指令都不得已应用于原始接口类型。

3.8.1联合类型扩展

联合类型扩展用于表示从某些原始联合类型扩展而来的联合类型。例如，这可以用于表示额外的本地数据，或者由本身是另一个 GraphQL 服务的扩展的 GraphQL 服务使用。

类型验证

如果联合类型扩展定义不正确，则可能无效。

1. 命名的类型必须已定义，并且必须是联合类型。
2. 联合类型扩展的成员类型必须全部是对象基本类型；标量、接口和联合类型不得是联合类型的成员类型。同样，包装类型不得是联合类型的成员类型。
3. 联合类型扩展的所有成员类型都必须是唯一的。
4. 联合类型扩展的所有成员类型都不得已经是原始联合类型的成员。
5. 提供的任何指令都不得已应用于原始联合类型。

3.9.1枚举扩展

枚举类型扩展用于表示从某些原始枚举类型扩展而来的枚举类型。例如，这可以用于表示额外的本地数据，或者由本身是另一个 GraphQL 服务的扩展的 GraphQL 服务使用。

类型验证

如果枚举类型扩展定义不正确，则可能无效。

1. 命名的类型必须已定义，并且必须是枚举类型。
2. 枚举类型扩展的所有值都必须是唯一的。
3. 枚举类型扩展的所有值都不得已经是原始枚举的值。
4. 提供的任何指令都不得已应用于原始枚举类型。

3.10.1输入对象扩展

输入对象类型扩展用于表示从某些原始输入对象类型扩展而来的输入对象类型。例如，这可以由本身是另一个 GraphQL 服务的扩展的 GraphQL 服务使用。

类型验证

如果输入对象类型扩展定义不正确，则可能无效。

1. 命名的类型必须已定义，并且必须是输入对象类型。
2. 输入对象类型扩展的所有字段都必须具有唯一的名称。
3. 输入对象类型扩展的所有字段都不得已经是原始输入对象的字段。
4. 提供的任何指令都不得已应用于原始输入对象类型。

3.12.1组合列表和非空

列表和非空包装类型可以组合，表示更复杂的类型。列表和非空类型的结果强制转换和输入强制转换规则以递归方式应用。

例如，如果列表的内部项类型是非空的（例如 [T!]），则该列表可能不包含任何 null 项。但是，如果非空的内部类型是列表（例如 [T]!），则不接受 null，但接受空列表。

以下是具有各种类型和值的结果强制转换示例

3.13.1@skip

directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

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

在此示例中，只有当变量 $someTest 的值为 false 时，才会查询 experimentalField。

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

3.13.2@include

directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

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

在此示例中，只有当变量 $someTest 的值为 true 时，才会查询 experimentalField

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

3.13.3@deprecated

directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE

@deprecated 指令在类型系统定义语言中使用，以指示 GraphQL 服务模式中已弃用的部分，例如类型上已弃用的字段或已弃用的枚举值。

弃用说明包含弃用原因，该原因使用 Markdown 语法格式化（如 CommonMark 所指定）。

在此类型定义示例中，oldField 已被弃用，推荐使用 newField。

Example № 85type ExampleType {
  newField: String
  oldField: String @deprecated(reason: "Use `newField`.")
}

4.5.1__Type 类型

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

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

4.5.2类型种类

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

Example № 89input Point {
  x: Int
  y: Int
}

4.5.3__Field 类型

__Field 类型表示 Object 或 Interface 类型中的每个字段。

字段

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

4.5.4__InputValue 类型

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

字段

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

4.5.5__EnumValue 类型

__EnumValue 类型表示枚举的可能值之一。

字段

• name 必须返回一个 String
• description 可以返回一个 String 或 null
• 如果此字段不应再使用，则 isDeprecated 返回 true，否则返回 false。
• deprecationReason 可选地提供此字段被弃用的原因。

4.5.6__Directive 类型

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

字段

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

5.1.1可执行定义

形式化规范

• 对于文档中的每个定义 definition。
• definition 必须是 OperationDefinition 或 FragmentDefinition（它不能是 TypeSystemDefinition）。

解释性文本

GraphQL 执行将仅考虑可执行定义 Operation 和 Fragment。 类型系统定义和扩展是不可执行的，并且在执行期间不被考虑。

为避免歧义，包含 TypeSystemDefinition 的文档对于执行无效。

不打算直接执行的 GraphQL 文档可能包含 TypeSystemDefinition。

例如，以下文档对于执行无效，因为原始执行模式可能不知道提供的类型扩展

Counter Example № 91query getDogName {
  dog {
    name
    color
  }
}

extend type Dog {
  color: String
}

5.2.1命名操作定义

Example № 92query getDogName {
  dog {
    name
  }
}

query getOwnerName {
  dog {
    owner {
      name
    }
  }
}

Counter Example № 93query getName {
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

Counter Example № 94query dogOperation {
  dog {
    name
  }
}

mutation dogOperation {
  mutateDog {
    id
  }
}

5.2.2匿名操作定义

Example № 95{
  dog {
    name
  }
}

Counter Example № 96{
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

5.2.3订阅操作定义

Example № 97subscription sub {
  newMessage {
    body
    sender
  }
}

Example № 98subscription sub {
  ...newMessageFields
}

fragment newMessageFields on Subscription {
  newMessage {
    body
    sender
  }
}

Counter Example № 99subscription sub {
  newMessage {
    body
    sender
  }
  disallowedSecondRootField
}

Counter Example № 100subscription sub {
  ...multipleSubscriptions
}

fragment multipleSubscriptions on Subscription {
  newMessage {
    body
    sender
  }
  disallowedSecondRootField
}

Counter Example № 101subscription sub {
  newMessage {
    body
    sender
  }
  __typename
}

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

形式化规范

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

解释性文本

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

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

Counter Example № 102fragment fieldNotDefined on Dog {
  meowVolume
}

fragment aliasedLyingFieldTargetNotDefined on Dog {
  barkVolume: kawVolume
}

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

例如，以下是有效的

Example № 103fragment interfaceFieldSelection on Pet {
  name
}

以下是无效的

Counter Example № 104fragment definedOnImplementorsButNotInterface on Pet {
  nickname
}

由于联合不定义字段，因此除非使用元字段 __typename，否则不能直接从联合类型选择集中选择字段。来自联合类型选择集的字段只能通过片段间接查询。

例如，以下是有效的

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

但以下是无效的

Counter Example № 106fragment directFieldSelectionOnUnion on CatOrDog {
  name
  barkVolume
}

5.3.2字段选择合并

形式化规范

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

解释性文本

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

在执行期间，具有相同响应名称的字段的同步执行是通过 MergeSelectionSets() 和 CollectFields() 完成的。

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

以下选择正确合并

Example № 107fragment mergeIdenticalFields on Dog {
  name
  name
}

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

以下选择无法合并

Counter Example № 108fragment conflictingBecauseAlias on Dog {
  name: nickname
  name
}

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

例如，以下选择正确合并

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

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

以下选择无法正确合并

Counter Example № 110fragment 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
}

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

Example № 111fragment 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

Counter Example № 112fragment conflictingDifferingResponses on Pet {
  ... on Dog {
    someValue: nickname
  }
  ... on Cat {
    someValue: meowVolume
  }
}

5.3.3叶子字段选择

形式化规范

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

解释性文本

永远不允许对标量或枚举进行字段选择，因为它们是任何 GraphQL 查询的叶子节点。

以下是有效的。

Example № 113fragment scalarSelection on Dog {
  barkVolume
}

以下是无效的。

Counter Example № 114fragment scalarSelectionsNotAllowedOnInt on Dog {
  barkVolume {
    sinceWhen
  }
}

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

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

Example № 115extend type Query {
  human: Human
  pet: Pet
  catOrDog: CatOrDog
}

以下示例是无效的

Counter Example № 116query directQueryOnObjectWithoutSubFields {
  human
}

query directQueryOnInterfaceWithoutSubFields {
  pet
}

query directQueryOnUnionWithoutSubFields {
  catOrDog
}

5.4.1参数名称

形式化规范

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

解释性文本

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

例如，以下是有效的

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

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

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

Counter Example № 118fragment invalidArgName on Dog {
  doesKnowCommand(command: CLEAN_UP_HOUSE)
}

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

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

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

Example № 120type 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]
  optionalNonNullBooleanArgField(optionalBooleanArg: Boolean! = false): Boolean!
}

extend type Query {
  arguments: Arguments
}

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

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

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

5.4.2参数唯一性

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

形式化规范

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

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

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

Example № 123fragment goodBooleanArgDefault on Arguments {
  booleanArgField
}

Counter Example № 124fragment missingRequiredArg on Arguments {
  nonNullBooleanArgField
}

Counter Example № 125fragment missingRequiredArg on Arguments {
  nonNullBooleanArgField(nonNullBooleanArg: null)
}

5.5.1片段声明

Example № 126{
  dog {
    ...fragmentOne
    ...fragmentTwo
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentTwo on Dog {
  owner {
    name
  }
}

Counter Example № 127{
  dog {
    ...fragmentOne
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentOne on Dog {
  owner {
    name
  }
}

Example № 128fragment correctType on Dog {
  name
}

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

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

Counter Example № 129fragment notOnExistingType on NotInSchema {
  name
}

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

Example № 130fragment fragOnObject on Dog {
  name
}

fragment fragOnInterface on Pet {
  name
}

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

Counter Example № 131fragment fragOnScalar on Int {
  something
}

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

Counter Example № 132fragment nameFragment on Dog { # unused
  name
}

{
  dog {
    name
  }
}

5.5.2片段扩展

字段选择也通过将片段相互扩展来确定。目标片段的选择集与引用目标片段的级别的选择集进行并集运算。

Counter Example № 133{
  dog {
    ...undefinedFragment
  }
}

Counter Example № 134{
  dog {
    ...nameFragment
  }
}

fragment nameFragment on Dog {
  name
  ...barkVolumeFragment
}

fragment barkVolumeFragment on Dog {
  barkVolume
  ...nameFragment
}

Example № 135{
  dog {
    name
    barkVolume
    name
    barkVolume
    name
    barkVolume
    name
    # forever...
  }
}

Counter Example № 136{
  dog {
    ...dogFragment
  }
}

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

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

Example № 137fragment dogFragment on Dog {
  ... on Dog {
    barkVolume
  }
}

Counter Example № 138fragment catInDogFragmentInvalid on Dog {
  ... on Cat {
    meowVolume
  }
}

Example № 139fragment petNameFragment on Pet {
  name
}

fragment interfaceWithinObjectFragment on Dog {
  ...petNameFragment
}

Example № 140fragment catOrDogNameFragment on CatOrDog {
  ... on Cat {
    meowVolume
  }
}

fragment unionWithObjectFragment on Dog {
  ...catOrDogNameFragment
}

Example № 141fragment petFragment on Pet {
  name
  ... on Dog {
    barkVolume
  }
}

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

Counter Example № 142fragment sentientFragment on Sentient {
  ... on Dog {
    barkVolume
  }
}

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

Example № 143fragment unionWithInterface on Pet {
  ...dogOrHumanFragment
}

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

Counter Example № 144fragment nonIntersectingInterfaces on Pet {
  ...sentientFragment
}

fragment sentientFragment on Sentient {
  name
}

5.6.1正确类型的值

格式规范

• 对于文档中的每个输入值 value。
  • 令 type 为在 value 所在位置期望的类型。
  • value 必须可强制转换为 type。

解释性文本

字面量值必须与它们所在位置期望的类型兼容，根据类型系统章节中定义的强制规则。

位置中期望的类型包括为参数提供值定义的类型、为输入对象字段提供值定义的类型，以及为变量定义提供默认值定义的类型。

以下示例是值字面量的有效用法

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

fragment coercedIntIntoFloatArg on Arguments {
  # Note: The input coercion rules for Float allow Int literals.
  floatArgField(floatArg: 123)
}

query goodComplexDefaultValue($search: ComplexInput = { name: "Fido" }) {
  findDog(complex: $search)
}

不可强制转换的值（例如将字符串转换为整数）是无效的。 以下示例是无效的

Counter Example № 146fragment stringIntoInt on Arguments {
  intArgField(intArg: "123")
}

query badComplexValue {
  findDog(complex: { name: 123 })
}

5.6.2输入对象字段名称

形式化规范

• 对于文档中的每个输入对象字段 inputField
• 令 inputFieldName 为 inputField 的名称。
• 令 inputFieldDefinition 为父输入对象类型（名为 inputFieldName）提供的输入字段定义。
• inputFieldDefinition 必须存在。

解释性文本

输入对象值中提供的每个输入字段都必须在输入对象预期类型的可能字段集中定义。

例如，以下示例输入对象是有效的

Example № 147{
  findDog(complex: { name: "Fido" })
}

而以下示例输入对象使用了字段“favoriteCookieFlavor”，该字段未在预期类型上定义

Counter Example № 148{
  findDog(complex: { favoriteCookieFlavor: "Bacon" })
}

5.6.3输入对象字段唯一性

形式化规范

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

解释性文本

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

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

Counter Example № 149{
  field(arg: { field: true, field: false })
}

5.6.4输入对象必填字段

形式化规范

• 对于文档中的每个输入对象。
  • 令 fields 为该输入对象提供的字段。
  • 令 fieldDefinitions 为该输入对象的输入字段定义集。
• 对于 fieldDefinitions 中的每个 fieldDefinition
  • 令 type 为 fieldDefinition 的预期类型。
  • 令 defaultValue 为 fieldDefinition 的默认值。
  • 如果 type 为 Non‐Null 且 defaultValue 不存在
    • 令 fieldName 为 fieldDefinition 的名称。
    • 令 field 为 fields 中名为 fieldName 的输入字段
    • field 必须存在。
    • 令 value 为 field 的值。
    • value 不得为 null 字面量。

解释性文本

输入对象字段可能是必需的。 就像字段可能具有必需的参数一样，输入对象也可能具有必需的字段。 如果输入字段具有非空类型且没有默认值，则它是必需的。 否则，输入对象字段是可选的。

5.7.1指令已定义

形式化规范

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

解释性文本

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

5.7.2指令位于有效位置

形式化规范

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

解释性文本

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

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

Counter Example № 150query @skip(if: $foo) {
  field
}

5.7.3每个位置的指令都是唯一的

形式化规范

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

解释性文本

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

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

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

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

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

5.8.1变量唯一性

形式化规范

• 对于文档中的每个 operation
  • 对于 operation 上定义的每个 variable
    • 令 variableName 为 variable 的名称
    • 令 variables 为 operation 上所有名为 variableName 的变量集
    • variables 必须是只包含一个元素的集合

解释性文本

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

Counter Example № 153query houseTrainedQuery($atOtherHomes: Boolean, $atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

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

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

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

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

5.8.2变量是输入类型

形式化规范

• 对于 document 中的每个 operation
• 对于每个 operation 上的每个 variable
  • 令 variableType 为 variable 的类型
  • IsInputType(variableType) 必须为 true

解释性文本

变量只能是输入类型。 对象、联合类型和接口类型不能用作输入。

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

Example № 155input ComplexInput { name: String, owner: String }

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

以下查询是有效的

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

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

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

以下查询是无效的

Counter Example № 157query takesCat($cat: Cat) {
  # ...
}

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

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

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

5.8.3所有变量使用已定义

形式化规范

• 对于文档中的每个 operation
  • 对于作用域中的每个 variableUsage，变量必须在 operation 的变量列表中。
  • 令 fragments 为该 operation 传递引用的每个片段
  • 对于 fragments 中的每个 fragment
    • 对于 fragment 作用域中的每个 variableUsage，变量必须在 operation 的变量列表中。

解释性文本

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

例如

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

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

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

Counter Example № 159query variableIsNotDefined {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

$atOtherHomes 未由操作定义。

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

例如，以下是有效的

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

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

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

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

Counter Example № 161query variableIsNotDefinedUsedInSingleFragment {
  dog {
    ...isHousetrainedFragment
  }
}

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

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

Counter Example № 162query variableIsNotDefinedUsedInNestedFragment {
  dog {
    ...outerHousetrainedFragment
  }
}

fragment outerHousetrainedFragment on Dog {
  ...isHousetrainedFragment
}

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

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

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

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

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

但是，以下内容无法通过验证

Counter Example № 164query housetrainedQueryOne($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query housetrainedQueryTwoNotDefined {
  dog {
    ...isHousetrainedFragment
  }
}

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

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

5.8.4所有变量都已使用

形式化规范

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

解释性文本

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

例如，以下是无效的

Counter Example № 165query variableUnused($atOtherHomes: Boolean) {
  dog {
    isHousetrained
  }
}

因为 $atOtherHomes 未被引用。

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

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

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

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

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

Counter Example № 167query variableNotUsedWithinFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedWithoutVariableFragment
  }
}

fragment isHousetrainedWithoutVariableFragment on Dog {
  isHousetrained
}

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

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

Counter Example № 168query queryWithUsedVar($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

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

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

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

5.8.5所有变量用法都是允许的

形式化规范

• 对于 document 中的每个 operation
• 令 variableUsages 为传递包含在 operation 中的所有用法。
• 对于 variableUsages 中的每个 variableUsage
  • 令 variableName 为 variableUsage 的名称。
  • 令 variableDefinition 为 operation 中定义的名为 variableName 的 VariableDefinition。
  • IsVariableUsageAllowed(variableDefinition, variableUsage) 必须为 true。

解释性文本

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

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

类型必须匹配

Counter Example № 169query intCannotGoIntoBoolean($intArg: Int) {
  arguments {
    booleanArgField(booleanArg: $intArg)
  }
}

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

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

Counter Example № 170query booleanListCannotGoIntoBoolean($booleanListArg: [Boolean]) {
  arguments {
    booleanArgField(booleanArg: $booleanListArg)
  }
}

空值性也必须受到尊重。 一般来说，可空变量不能传递给非空参数。

Counter Example № 171query booleanArgQuery($booleanArg: Boolean) {
  arguments {
    nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)
  }
}

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

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

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

Counter Example № 173query listToNonNullList($booleanList: [Boolean]) {
  arguments {
    nonNullBooleanListField(nonNullBooleanListArg: $booleanList)
  }
}

这将无法通过验证，因为 [T] 不能传递给 [T]!。 同样，[T] 不能传递给 [T!]。

当存在默认值时允许可选变量

变量类型兼容性的一个显着例外是允许将具有可空类型的变量定义提供给非空位置，只要该变量或该位置提供默认值即可。

Example № 174query booleanArgQueryWithDefault($booleanArg: Boolean) {
  arguments {
    optionalNonNullBooleanArgField(optionalBooleanArg: $booleanArg)
  }
}

在上面的示例中，允许在提供默认值的非空参数中使用可选变量。

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

在上面的示例中，变量提供了默认值，并且可以在非空参数中使用。 为了与本规范的早期版本兼容，显式支持此行为。 GraphQL 创作工具可能希望将其报告为警告，并建议将 Boolean 替换为 Boolean!。