GraphQL

2.10.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.10.2片段中的查询变量

查询变量可以在片段中使用。 查询变量在给定操作中具有全局作用域，因此在片段中使用的变量必须在任何传递使用该片段的顶级操作中声明。 如果变量在片段中被引用，并且被不定义该变量的操作包含，则该操作无法执行。

2.10.3内联片段

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

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

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），则它们被解释为整数输入值，否则被解释为浮点输入值。

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"
}

而选择字段的子集

{
  name,
  age
}

必须仅产生该子集

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

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

例如，Person 类型可能包含 relationship

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

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

{
  name,
  relationship
}

但是，此示例有效

{
  name,
  relationship {
    name
  }
}

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

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

结果强制转换

确定强制转换对象的结果是 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 : NamedEntity {
  name: String
  age: Int
}

type Business : 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 User {
      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 可以包含表达循环引用或对接口和联合的引用的字段，这两种都不适合用作输入参数。因此，输入对象在系统中具有单独的类型。

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

结果强制转换

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

输入强制转换

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

3.1.7列表

GraphQL 列表是一种特殊的集合类型，它声明了列表中每个项目的类型（称为列表的项目类型）。列表值序列化为有序列表，其中数组中的每个项目都根据项目类型进行序列化。

结果强制转换

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

输入强制转换

当作为输入接受时，列表中的每个项目都应根据项目类型的输入强制转换进行强制转换。

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

3.1.8非空

默认情况下，GraphQL 中的所有类型都是可为空的；null 值对于上述所有类型都是有效的响应。要声明不允许为空的类型，可以使用 GraphQL 非空类型。此类型声明一个底层类型，并且此类型的行为与该底层类型完全相同，但 null 对于包装类型而言不是有效响应。

结果强制转换

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

输入强制转换

当作为输入接受时，列表中的每个项目都应根据项目类型的输入强制转换进行强制转换。

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

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
}

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

形式规范

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

解释性文本

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

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

fragment fieldNotDefined on Dog {
  meowVolume
}

fragment aliasedLyingFieldTargetNotDefined on Dog {
  barkVolume : kawVolume
}

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

例如，以下是有效的

fragment interfaceFieldSelection on Pet {
  name
}

以下是无效的

fragment definedOnImplementorsButNotInterface : Pet {
  nickname
}

因为字段未在联合上声明，所以在联合类型选择集上直接进行字段选择。即使联合的具体实现者定义了 fieldName，也是如此。

例如，以下是无效的

fragment directFieldSelectionOnUnion : CatOrDog {
  directField
}

fragment definedOnImplementorsQueriedOnUnion : CatOrDog {
  name
}

5.1.2字段选择合并

形式规范

• 令 set 为 GraphQL 文档中定义的任何选择集
• 令 setForKey 为 set 中具有给定响应键的选择集
• setForKey 的所有成员都必须
  • 具有相同的目标字段
  • 具有相同的参数名称-值对集。
  • 具有相同的指令名称-值对集。

解释性文本

选择名称已去重并合并以进行验证，但目标字段、参数和指令必须完全相同。

对于人工管理的 GraphQL，此规则似乎有点违反直觉，因为它看起来是明显的开发人员错误。但是在存在嵌套片段或机器生成的 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 mergeSameFieldsWithSameDirectives on Dog {
  name @if:true
  name @if:true
}

以下是无效的

fragment conflictingDirectiveArgs on Dog {
  name @if: true
  name @unless: false
}

5.1.3叶子字段选择

形式规范

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

解释性文本

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

以下是有效的。

fragment scalarSelection: Dog {
  barkVolume
}

以下是无效的。

fragment scalarSelectionsNotAllowedOnBoolean : Dog {
  barkVolume { sinceWhen }
}

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

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

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

以下示例无效

query directQueryOnObjectWithoutSubFields
{
  human
}

query directQueryOnInterfaceWithoutSubFields
{
  pet
}

query directQueryOnUnionWithoutSubFields
{
  catOrDog
}

5.2.1参数名称

形式规范

• 对于文档中的每个 selection
• 令 arguments 为提供给 selection 的参数集
• 令 targetField 为给定 selection 的目标字段
• 令 argumentDefinitions 为 targetField 的参数定义集
• arguments 中的每个 argumentName 都必须在 targetField 中具有同名的相应参数定义

解释性文本

字段选择可以接受参数。每个字段选择对应于封闭类型上的字段定义，该定义指定了一组可能的参数。提供给选择的每个参数都必须在可能的参数集中定义。

例如，以下是有效的

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

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

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

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

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

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

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

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

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

5.2.2参数值类型正确性

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 {
  notNullBooleanArgField
}

5.3.1片段声明

fragment CorrectType on Dog {
  name
}

fragment InlineFragment on Dog {
  ... on Dog {
    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.3.2片段展开

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

fragment nameFragment on Dog { name }
{ dog { ...undefinedFragment} }

{
  dog {
    ...nameFragment
  }
}

fragment nameFragment on Dog {
  name
  ...barkVolumeFragment
}

fragment barkVolumeFragment on Dog {
  barkVolume
  ...nameFragment
}

{
  dog {
    name, barkVolume, name, barkVolume, name, barkVolume, name, # etc...
  }
}

{
  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 { ...CatOrDogFragment }

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 Pet { ...dogOrHumanFragment }
fragment dogOrHumanFragment on DogOrHuman { ... on Dog { barkVolume } }

fragment nonIntersectingInterfaces on Pet { ...sentientFragment }
fragment sentientFragment on Sentient { name }

5.4.1指令已定义

形式规范

• 对于文档中的每个 directiveUse。
• 该指令的名称必须由 GraphQL 服务器的类型系统定义。

解释性文本

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

5.4.2指令参数类型正确

形式规范

• 对于文档中的每个 directiveUse。
• 令 directiveType 为服务器上定义的相应指令的输入类型。
• 如果 directiveType 未定义
  • 该指令旨在仅用作标志，不应提供任何参数。
• 如果 directiveType 已定义且为非空
  • directiveUse 必须具有一个参数
• 令 argumentType 为提供给 directiveUse 的参数的类型
• argumentType 和 directiveType 必须相同，或者 argumentType 必须可以强制转换为 directiveType

解释性文本

指令参数遵循与字段参数类似的规则。与字段参数非常相似，指令的参数必须与指令类型的输入类型相同或可强制转换为指令类型的输入类型。

指令参数与字段参数的不同之处在于，它们可以在不提供参数的情况下使用。如果指令的类型不是非空，则指令可以可选地在不带参数的情况下使用。如果指令的类型未定义，则它是标志指令：它不能有参数。如果为标志指令提供了值，则会发生验证错误。

5.5.1变量

  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)
    }
  }

  query TakesBoolean($atOtherHomes: Boolean) { /* ... */ }
  query TakesComplexInput($complexInput: ComplexInput) { /* ... */ }
  query TakesListOfBooleanBang($booleans: [Boolean!]) { /* ... */ }

  query TakesCat($cat: Cat) { /* ... */ }
  query TakesDogBang($dog: Dog!) { /* ... */ }
  query TakesListOfPet($pets: [Pet]) { /* ... */ }
  query TakesCatOrDog($catOrDog: CatOrDog) { /* ... */ }

query VariableIsDefined($atOtherHomes: Boolean) {
  dog { isHousetrained(atOtherHomes: $booleanArg)
}

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

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

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

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}
}

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

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

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $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)
}

Query IntCannotGoIntoBoolean($intArg: Int) {
  arguments { booleanArgField(booleanArg: $intArg) }
}

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) }
}

6.4.1字段条目

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

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

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

6.4.2正常评估

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

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

{
  birthday {
    month
  },
  address {
    street
  }
}

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

6.4.3串行执行

请注意，根据以上部分，执行器将以串行执行顺序运行的唯一时间是在突变操作的顶层选择集及其相应的分组字段集上。

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

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

{
  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.4.4错误处理

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

6.4.5可空性

如果解析字段的结果为 null（无论是由于解析字段的函数返回 null 还是由于发生错误），并且该字段在类型系统中被标记为非空，则包含此字段的整个字段集的评估结果现在为 null。

如果字段由于错误而为 null，则错误已被记录，并且响应中的“errors”列表不得受到影响。

如果字段解析函数返回 null，并且该字段为非空，则尚未记录任何错误，因此必须将适当的错误添加到“errors”列表中。

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

8.1.1忽略的源

在每个词法标记之前，可以有任意数量的忽略的源字符，例如空格和注释。空格，字符串内除外，并不重要。

GraphQL 将逗号 , 视为类似于空格。这确保了逗号的存在与否不会有意义地改变文档的解释语法，这在其他语言中是一个常见的用户错误。它还允许样式化地使用尾随逗号或换行符作为分隔符，这通常是期望的，以提高源代码的可读性和可维护性。当逗号和其他空格可以提高可读性时，建议使用它们。

GraphQL 忽略以下字符序列

8.2.1文档

GraphQL 文档描述了一个完整的文件或请求字符串。文档包含多个定义，包括操作。

8.2.2操作

操作描述了对 GraphQL 的某种类型的请求。最常见的操作是 query，即从 GraphQL 读取数据的只读请求。查询操作存在简写语法。

8.2.3片段

片段允许重用字段的常见选择，减少文档中的重复文本。内联片段可以直接在选择中内联使用，以在针对接口或联合进行查询时应用类型条件。

8.2.4值

字段可以接受参数值。值可以是任何 JSON 风格的值、变量或枚举值。

8.2.5指令

指令提供了一种描述 GraphQL 文档中运行时执行和类型验证行为的方法。

8.2.6类型

GraphQL 使用类型系统描述其提供的数据的模式。在定义查询变量时，文档中会引用这些类型。

语义