查询简写

如果文档仅包含一个操作，且该操作是一个未定义变量且不包含指令的查询，则该操作可以用简写形式表示，其中省略了 query 关键字和操作名称。

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

Example № 6{
  field
}

参数是无序的

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

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

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

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

变量必须在操作的顶部定义，并在该操作的整个执行过程中都在作用域内。这些变量的值作为请求的一部分提供给 GraphQL 服务，以便在执行期间可以进行替换。

在这个例子中，我们想要根据特定设备的大小获取个人资料图片大小

语义

指令顺序很重要

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

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

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 № 42scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986")

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

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

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

结果强制和序列化

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

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

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

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

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

输入强制

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

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

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

字段排序

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

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

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

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

Example № 52{
  foo
  ...Frag
  qux
}

fragment Frag on Query {
  bar
  baz
}

产生有序的结果

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

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

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

fragment Ignored on UnknownType {
  qux
  baz
}

fragment Matching on Query {
  bar
  qux
  foo
}

产生有序的结果

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

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

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

产生有序的结果

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

结果强制

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

输入强制

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

类型验证

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

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

接口实现接口

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

Example № 69interface Node {
  id: ID!
}

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

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

Example № 70interface 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 № 71interface 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. 该参数必须接受一个类型，其中 IsInputType(argumentType) 返回 true。
3. 接口类型可以声明它实现了一个或多个唯一的接口，但不能实现自身。
4. 接口类型必须是它实现的所有接口的超集
   1. 设此接口类型为 implementingType。
   2. 对于声明为 implementedType 实现的每个接口，IsValidImplementation(implementingType, implementedType) 必须为 true。

结果强制

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

输入强制

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

类型验证

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

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

结果强制

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

输入强制

GraphQL 有一个常量字面量来表示枚举输入值。GraphQL 字符串字面量不得被接受为枚举输入，而应引发请求错误。

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

类型验证

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

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

循环引用

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

循环引用通常是允许的，但是它们不能被定义为非空单数字段的 unbroken chain（不间断链）。 这样的输入对象是无效的，因为没有办法为它们提供合法的值。

这个循环引用的输入类型的例子是有效的，因为字段 self 可以被省略或值为 null。

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

这个例子也是有效的，因为字段 self 可以是一个空列表。

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

这个循环引用的输入类型的例子是无效的，因为字段 self 不能被提供一个有限值。

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

这个例子也是无效的，因为通过 First.second 和 Second.first 字段存在一个非空单数循环引用。

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

input Second {
  first: First!
  value: String
}

结果强制

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

输入强制

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

类型强制转换的结果是一个无序映射，其中包含输入对象类型定义的每个字段以及存在值的字段的条目。 结果映射是根据以下规则构建的

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

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

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

类型验证

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

结果强制

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

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

输入强制

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

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

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

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

可为空 vs. 可选

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

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

结果强制

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

输入强制

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

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

非空参数不能省略

Counter Example № 85{
  fieldWithNonNullArg
}

值 null 不能提供给非空参数

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

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

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

类型验证

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

内置指令

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

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

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

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

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

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

自定义指令

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

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

Example № 88directive @example on FIELD

fragment SomeFragment on SomeType {
  field @example
}

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

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

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

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

Example № 90directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION

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

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

Example № 91directive @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 № 92directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION

验证

1. 指令定义不得包含使用直接引用自身的指令。
2. 指令定义不得包含使用通过引用 Type 或 Directive 间接引用自身的指令，而 Type 或 Directive 传递性地包含对此指令的引用。
3. 指令的名称不得以字符 "__"（两个下划线）开头。
4. 对于指令的每个参数
   1. 该参数的名称不能以字符 "__" （两个下划线）开头。
   2. 该参数必须接受一个类型，其中 IsInputType(argumentType) 返回 true。

一流文档

内省系统中的所有类型都提供类型为 String 的 description 字段，以允许类型设计者除了功能之外还发布文档。 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: [__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: [__InputValue!]!
  type: __Type!
  isDeprecated: Boolean!
  deprecationReason: String
}

type __InputValue {
  name: String!
  description: String
  type: __Type!
  defaultValue: String
}

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

type __Directive {
  name: String!
  description: String
  locations: [__DirectiveLocation!]!
  args: [__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
}