查询简写

如果一个文档仅包含一个操作，且该操作是一个查询，它没有定义变量，也没有应用任何指令，那么该操作可以用简写形式表示，其中省略了 query 关键字和操作名称。

例如，这个未命名的查询操作是通过查询简写编写的。

Example № 6{
  field
}

参数是无序的

可以以任何语法顺序提供参数，并保持相同的语义含义。

这两个操作在语义上是相同的

Example № 12{
  picture(width: 200, height: 100)
}

Example № 13{
  picture(height: 100, width: 200)
}

片段中的变量使用

变量可以在片段中使用。变量在给定的操作中具有全局作用域，因此在片段中使用的变量必须在任何传递性地使用该片段的顶层操作中声明。如果变量在片段中被引用，但包含该片段的操作未定义该变量，则该操作无效（请参阅 所有变量使用已定义）。

语义

指令顺序很重要

可以以特定的语法顺序提供指令，这可能具有语义解释。

这两个类型定义可能具有不同的语义含义

Example № 34type Person
  @addExternalFields(source: "profiles")
  @excludeField(name: "photo") {
  name: String
}

Example № 35type Person
  @excludeField(name: "photo")
  @addExternalFields(source: "profiles") {
  name: String
}

内置标量

GraphQL 指定了一组定义明确的基本标量类型：Int、Float、String、Boolean 和 ID。GraphQL 框架应支持所有这些类型，并且提供这些名称的 GraphQL 服务必须遵守本文档中描述的行为。例如，服务不得包含名为 Int 的类型，并将其用于表示 64 位数字、国际化信息或本文档中定义以外的任何其他内容。

从 __Schema 内省类型返回类型集时，必须包含所有引用的内置标量。如果内置标量类型在模式中的任何位置都没有被引用（该类型没有字段、参数或输入字段），则不得包含它。

当使用类型系统定义语言表示 GraphQL 模式时，为了简洁起见，必须省略所有内置标量。

自定义标量

除了内置标量之外，GraphQL 服务还可以使用自定义标量类型。例如，GraphQL 服务可以定义一个名为 UUID 的标量，该标量虽然序列化为字符串，但符合 RFC 4122。当查询 UUID 类型的字段时，您可以依赖使用符合 RFC 4122 的解析器解析结果的能力。另一个可能有用的自定义标量的示例是 URL，它序列化为字符串，但服务保证它是有效的 URL。

在定义自定义标量时，GraphQL 服务应通过 @specifiedBy 指令或 specifiedByURL 内省字段提供 标量规范 URL。此 URL 必须链接到标量的数据格式、序列化和强制转换规则的人类可读规范。

例如，提供 UUID 标量的 GraphQL 服务可以链接到 RFC 4122，或定义该 RFC 的合理子集的某些自定义文档。如果存在 标量规范 URL，则知道它的系统和工具应符合其描述的规则。

Example № 43scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986")
scalar DateTime
  @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time")

自定义 标量规范 URL 应提供单一、稳定的格式，以避免歧义。如果链接的规范正在变动，服务应链接到固定版本，而不是可能更改的资源。

自定义 标量规范 URL 一旦定义就不应更改。这样做可能会扰乱工具，或者可能在链接规范的内容中引入破坏性更改。

内置标量类型不得提供 标量规范 URL，因为它们由此文档指定。

结果强制和序列化

GraphQL 服务在准备给定标量类型的字段时，必须遵守标量类型描述的约定，要么强制转换值，要么在无法强制转换值或强制转换可能导致数据丢失时生成 字段错误。

GraphQL 服务可以决定允许将不同的内部类型强制转换为预期的返回类型。例如，当强制转换 Int 类型的字段时，布尔值 true 可能会产生 1，或者字符串值 "123" 可能会被解析为十进制 123。但是，如果内部类型强制转换无法在不丢失信息的情况下合理执行，则必须引发 字段错误。

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

GraphQL 标量根据正在使用的序列化格式进行序列化。对于每种给定的标量类型，可能存在最合适的序列化原语，并且服务应在适当的情况下生成每种原语。

有关常见 JSON 和其他格式中标量的序列化的更多详细信息，请参阅 序列化格式。

输入强制

如果 GraphQL 服务期望将标量类型作为参数的输入，则强制转换是可观察的，并且规则必须明确定义。如果输入值与强制转换规则不匹配，则必须引发 请求错误（输入值在执行开始前进行验证）。

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

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

字段排序

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

能够表示有序映射的响应序列化格式应保持此排序。只能表示无序映射的序列化格式（例如 JSON）应以文本形式保留此顺序。也就是说，如果按顺序查询了两个字段 {foo, bar}，则生成的 JSON 序列化应包含 {"foo": "...", "bar": "..."}，并且顺序相同。

生成响应，其中字段以它们在请求中出现的相同顺序表示，可以提高调试期间的人类可读性，并使在可以预期属性顺序的情况下更有效地解析响应。

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

Example № 53{
  foo
  ...Frag
  qux
}

fragment Frag on Query {
  bar
  baz
}

产生有序结果

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

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

Example № 55{
  foo
  ...Ignored
  ...Matching
  bar
}

fragment Ignored on UnknownType {
  qux
  baz
}

fragment Matching on Query {
  bar
  qux
  foo
}

产生有序结果

Example № 56{
  "foo": 1,
  "bar": 2,
  "qux": 3
}

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

Example № 57{
  foo @skip(if: true)
  bar
  foo
}

产生有序结果

Example № 58{
  "bar": 1,
  "foo": 2
}

结果强制

确定强制转换对象的结果是 GraphQL 执行器的核心，请参阅 值完成。

输入强制

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

类型验证

如果对象类型定义不正确，则可能无效。GraphQL 模式中的每个对象类型都必须遵守这组规则。

1. 对象类型必须定义一个或多个字段。
2. 对于对象类型的每个字段
   1. 该字段在该对象类型中必须具有唯一名称；没有两个字段可以共享相同的名称。
   2. 该字段不得具有以字符 "__" (两个下划线) 开头的名称。
   3. 该字段必须返回一个类型，其中 IsOutputType(fieldType) 返回 true。
   4. 对于字段的每个参数
      1. 该参数不得具有以字符 "__" (两个下划线) 开头的名称。
      2. 该参数在该字段中必须具有唯一名称；没有两个参数可以共享相同的名称。
      3. 该参数必须接受一个类型，其中 IsInputType(argumentType) 返回 true。
      4. 如果参数类型为 Non-Null 且未定义默认值
         1. @deprecated 指令不得应用于此参数。
3. 对象类型可以声明它实现一个或多个唯一接口。
4. 对象类型必须是它实现的所有接口的超集
   1. 让此对象类型为 objectType。
   2. 对于声明实现的每个接口 interfaceType，IsValidImplementation(objectType, interfaceType) 必须为 true。

接口实现接口

当定义实现另一个接口的接口时，实现接口必须定义已实现接口指定的每个字段。例如，接口 Resource 必须定义字段 id 才能实现 Node 接口

Example № 70interface Node {
  id: ID!
}

interface Resource implements Node {
  id: ID!
  url: String
}

传递实现的接口（正在实现的接口实现的接口）也必须在实现类型或接口上定义。例如，Image 无法在不实现 Node 的情况下实现 Resource

Example № 71interface Node {
  id: ID!
}

interface Resource implements Node {
  id: ID!
  url: String
}

interface Image implements Resource & Node {
  id: ID!
  url: String
  thumbnail: String
}

接口定义不得包含循环引用，也不得实现自身。此示例无效，因为 Node 和 Named 实现了自身，也实现了彼此

Counter Example № 72interface Node implements Named & Node {
  id: ID!
  name: String
}

interface Named implements Node & Named {
  id: ID!
  name: String
}

结果强制

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

输入强制

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

类型验证

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

1. 接口类型必须定义一个或多个字段。
2. 对于接口类型的每个字段
   1. 字段在该接口类型中必须具有唯一的名称；任何两个字段都不得共享相同的名称。
   2. 该字段不得具有以字符 "__" (两个下划线) 开头的名称。
   3. 该字段必须返回一个类型，其中 IsOutputType(fieldType) 返回 true。
   4. 对于字段的每个参数
      1. 该参数不得具有以字符 "__" (两个下划线) 开头的名称。
      2. 该参数在该字段中必须具有唯一名称；没有两个参数可以共享相同的名称。
      3. 该参数必须接受一个类型，其中 IsInputType(argumentType) 返回 true。
3. 接口类型可以声明它实现了一个或多个唯一接口，但不得实现自身。
4. 接口类型必须是其实现的所有接口的超集
   1. 令此接口类型为 implementingType。
   2. 对于声明为实现的每个接口 implementedType，IsValidImplementation(implementingType, implementedType) 必须为 true。

结果强制

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

输入强制

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

类型验证

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

1. 联合类型必须包含一个或多个唯一的成员类型。
2. 联合类型的成员类型都必须是对象基本类型；标量、接口和联合类型不得作为联合的成员类型。 同样，包装类型也不得作为联合的成员类型。

结果强制

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

输入强制

GraphQL 具有表示枚举输入值的常量文字。GraphQL 字符串文字不得接受为枚举输入，而应引发请求错误。

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

类型验证

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

1. 枚举类型必须定义一个或多个唯一的枚举值。

循环引用

输入对象允许将其他输入对象作为字段类型引用。当输入对象直接或通过引用的输入对象引用自身时，就会发生循环引用。

通常允许循环引用，但是它们不能定义为非空单数字段的不间断链。此类输入对象无效，因为无法为其提供合法值。

此循环引用输入类型的示例有效，因为字段 self 可以省略或值为 null。

Example № 81input Example {
  self: Example
  value: String
}

此示例也有效，因为字段 self 可以是空列表。

Example № 82input Example {
  self: [Example!]!
  value: String
}

此循环引用输入类型的示例无效，因为无法为字段 self 提供有限值。

Counter Example № 83input Example {
  value: String
  self: Example!
}

此示例也无效，因为通过 First.second 和 Second.first 字段存在非空单数循环引用。

Counter Example № 84input First {
  second: Second!
  value: String
}

input Second {
  first: First!
  value: String
}

结果强制

输入对象永远不是有效的结果。输入对象类型不能是对象或接口字段的返回类型。

输入强制

输入对象的值应为输入对象文字或由变量提供的无序映射，否则必须引发 请求错误。 在任何一种情况下，输入对象文字或无序映射都不得包含任何名称未由此输入对象类型的字段定义的条目，否则必须引发请求错误。

强制转换的结果是一个无序映射，其中包含由输入对象类型定义且存在值的每个字段的条目。生成的映射按照以下规则构造

• 如果未为定义的输入对象字段提供值，并且该字段定义提供了默认值，则应使用默认值。 如果未提供默认值，并且输入对象字段的类型为非空，则应引发错误。 否则，如果该字段不是必需的，则不会将任何条目添加到强制转换的无序映射中。
• 如果为输入对象字段提供了值 null，并且该字段的类型不是非空类型，则强制转换的无序映射中的条目将被赋予值 null。 换句话说，显式提供的值 null 与未提供值之间存在语义差异。
• 如果为输入对象字段提供了文字值，则强制转换的无序映射中的条目将根据该字段类型的输入强制转换规则，被赋予强制转换该值的结果。
• 如果为输入对象字段提供了变量，则必须使用该变量的运行时值。 如果运行时值为 null 且字段类型为非空，则必须引发 字段错误。 如果未提供运行时值，则应使用变量定义的默认值。 如果变量定义未提供默认值，则应使用输入对象字段定义的默认值。

以下是输入对象类型的输入强制转换示例，该输入对象类型具有 String 字段 a 和必需（非空）Int! 字段 b

Example № 85input ExampleInputObject {
  a: String
  b: Int!
}

类型验证

1. 输入对象类型必须定义一个或多个输入字段。
2. 对于输入对象类型的每个输入字段
   1. 输入字段在该输入对象类型中必须具有唯一的名称；任何两个输入字段都不得共享相同的名称。
   2. 输入字段不得具有以字符 "__" （两个下划线）开头的名称。
   3. 输入字段必须接受 IsInputType(inputFieldType) 返回 true 的类型。
   4. 如果输入字段类型为非空且未定义默认值
      1. @deprecated 指令不得应用于此输入字段。
3. 如果输入对象直接或通过引用的输入对象引用自身，则引用链中的字段必须至少有一个是可为空类型或列表类型。

结果强制

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

如果列表的项目类型可为空，则在列表中单个项目的准备或强制转换期间发生的错误必须导致在该列表位置的值为 null，并在响应中添加 字段错误。 如果列表的项目类型为非空，则在列表中单个项目处发生的字段错误必须导致整个列表的字段错误。

输入强制

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

如果作为列表类型的输入传递的值不是列表且不是 null 值，则输入强制转换的结果是大小为 1 的列表，其中单个项目值是对提供的列表的项目类型进行输入强制转换的结果（请注意，这可以递归地应用于嵌套列表）。

这允许接受一个或多个参数（有时称为“可变参数”）的输入将其输入类型声明为列表，而在单个值的常见情况下，客户端可以直接传递该值，而不是构造列表。

以下是各种列表类型和值的输入强制转换示例

可为空 vs. 可选

字段在 选择集 的上下文中始终是可选的，可以省略字段，并且选择集仍然有效（只要选择集不为空）。 但是，返回非空类型的字段在查询时永远不会返回 null 值。

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

结果强制

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

输入强制

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

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

非空参数不能省略

Counter Example № 86{
  fieldWithNonNullArg
}

值 null 不能提供给非空参数

Counter Example № 87{
  fieldWithNonNullArg(nonNullArg: null)
}

可为空类型的变量不能提供给非空参数

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

类型验证

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

内置指令

内置指令 是本规范中定义的任何指令。

GraphQL 实现应提供 @skip 和 @include 指令。

如果 GraphQL 实现支持类型系统定义语言，则在表示 schema 的已弃用部分时，必须提供 @deprecated 指令。

如果 GraphQL 实现支持类型系统定义语言，则在表示自定义标量定义时，应提供 @specifiedBy 指令。

当使用类型系统定义语言表示 GraphQL schema 时，为了简洁起见，可以省略任何 内置指令。

当内省 GraphQL 服务时，所有提供的指令，包括任何 内置指令，都必须包含在返回的指令集中。

自定义指令

GraphQL 服务和客户端工具可以提供超出本文档中定义的任何其他 自定义指令。 指令是使用自定义或实验性行为扩展 GraphQL 的首选方式。

指令必须仅在其声明所属的位置使用。 在此示例中，定义了一个指令，该指令可用于注释字段

Example № 89directive @example on FIELD

fragment SomeFragment on SomeType {
  field @example
}

指令位置可以使用可选的前导 | 字符进行定义，以帮助在表示更长的可能位置列表时进行格式化

Example № 90directive @example on
  | FIELD
  | FRAGMENT_SPREAD
  | INLINE_FRAGMENT

指令还可以用于注释类型系统定义语言，这可以作为一种有用的工具来提供额外的元数据，以便生成 GraphQL 执行服务、生成客户端生成的运行时代码或 GraphQL 语义的许多其他有用的扩展。

在此示例中，指令 @example 注释了字段和参数定义

Example № 91directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION

type SomeType {
  field(arg: Int @example): String @example
}

可以通过包含“repeatable”关键字将指令定义为可重复的。 当应在单个位置使用具有不同参数的同一指令时，可重复指令通常很有用，尤其是在需要通过指令向类型或 schema 扩展提供其他信息的情况下

Example № 92directive @delegateField(name: String!) repeatable on OBJECT | INTERFACE

type Book @delegateField(name: "pageCount") @delegateField(name: "author") {
  id: ID!
}

extend type Book @delegateField(name: "index")

在定义指令时，它不得直接或间接地引用自身

Counter Example № 93directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION

验证

1. 指令定义不得包含使用直接引用自身的指令。
2. 指令定义不得包含使用间接引用自身的指令，即通过引用传递包含对此指令引用的类型或指令。
3. 指令不得具有以字符 "__" （两个下划线）开头的名称。
4. 对于指令的每个参数
   1. 该参数不得具有以字符 "__" (两个下划线) 开头的名称。
   2. 参数在该指令中必须具有唯一的名称；任何两个参数都不得共享相同的名称。
   3. 该参数必须接受一个类型，其中 IsInputType(argumentType) 返回 true。

一流的文档

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

弃用

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

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

模式内省模式

模式内省系统本身表示为 GraphQL 模式。以下是提供模式内省的完整类型系统定义集，这些定义在下面的章节中完全定义。

type __Schema {
  description: String
  types: [__Type!]!
  queryType: __Type!
  mutationType: __Type
  subscriptionType: __Type
  directives: [__Directive!]!
}

type __Type {
  kind: __TypeKind!
  name: String
  description: String
  # must be non-null for OBJECT and INTERFACE, otherwise null.
  fields(includeDeprecated: Boolean = false): [__Field!]
  # must be non-null for OBJECT and INTERFACE, otherwise null.
  interfaces: [__Type!]
  # must be non-null for INTERFACE and UNION, otherwise null.
  possibleTypes: [__Type!]
  # must be non-null for ENUM, otherwise null.
  enumValues(includeDeprecated: Boolean = false): [__EnumValue!]
  # must be non-null for INPUT_OBJECT, otherwise null.
  inputFields(includeDeprecated: Boolean = false): [__InputValue!]
  # must be non-null for NON_NULL and LIST, otherwise null.
  ofType: __Type
  # may be non-null for custom SCALAR, otherwise null.
  specifiedByURL: String
}

enum __TypeKind {
  SCALAR
  OBJECT
  INTERFACE
  UNION
  ENUM
  INPUT_OBJECT
  LIST
  NON_NULL
}

type __Field {
  name: String!
  description: String
  args(includeDeprecated: Boolean = false): [__InputValue!]!
  type: __Type!
  isDeprecated: Boolean!
  deprecationReason: String
}

type __InputValue {
  name: String!
  description: String
  type: __Type!
  defaultValue: String
  isDeprecated: Boolean!
  deprecationReason: String
}

type __EnumValue {
  name: String!
  description: String
  isDeprecated: Boolean!
  deprecationReason: String
}

type __Directive {
  name: String!
  description: String
  locations: [__DirectiveLocation!]!
  args(includeDeprecated: Boolean = false): [__InputValue!]!
  isRepeatable: Boolean!
}

enum __DirectiveLocation {
  QUERY
  MUTATION
  SUBSCRIPTION
  FIELD
  FRAGMENT_DEFINITION
  FRAGMENT_SPREAD
  INLINE_FRAGMENT
  VARIABLE_DEFINITION
  SCHEMA
  SCALAR
  OBJECT
  FIELD_DEFINITION
  ARGUMENT_DEFINITION
  INTERFACE
  UNION
  ENUM
  ENUM_VALUE
  INPUT_OBJECT
  INPUT_FIELD_DEFINITION
}