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.2.1操作

GraphQL 建模了两种类型的操作

• query – 只读获取。
• mutation – 写入后跟获取。

每个操作都由一个可选的操作名称和一个选择集表示。

例如，此 mutation 操作可能会“喜欢”一个故事，然后检索新的喜欢数量

mutation {
  likeStory(storyID: 12345) {
    story {
      likeCount
    }
  }
}

查询简写

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

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

{
  field
}

2.2.2选择集

操作选择它需要的信息集，并将接收到精确的信息，不多也不少，从而避免过度获取和获取不足数据。

{
  id
  firstName
  lastName
}

在此查询中，id、firstName 和 lastName 字段形成一个选择集。选择集也可以包含片段引用。

2.2.3字段

选择集主要由字段组成。字段描述可以在选择集中请求的一个离散的信息片段。

某些字段描述复杂的数据或与其他数据的关系。为了进一步探索这些数据，字段本身可以包含一个选择集，从而允许深度嵌套的请求。所有 GraphQL 操作都必须将其选择指定到返回标量值的字段，以确保明确形状的响应。

例如，此操作选择复杂数据和关系的字段，直到标量值。

{
  me {
    id
    firstName
    lastName
    birthday {
      month
      day
    }
    friends {
      name
    }
  }
}

操作的顶层选择集中的字段通常表示您的应用程序及其当前查看者全局可访问的某些信息。这些顶级字段的一些典型示例包括对当前登录查看者的引用，或访问由唯一标识符引用的某些类型的数据。

# `me` could represent the currently logged in viewer.
{
  me {
    name
  }
}

# `user` represents one of many users in a graph of data, referred to by a
# unique identifier.
{
  user(id: 4) {
    name
  }
}

2.2.4参数

字段在概念上是返回值的函数，并且有时接受改变其行为的参数。这些参数通常直接映射到 GraphQL 服务器实现中的函数参数。

在此示例中，我们要查询特定用户（通过 id 参数请求）及其特定 size 的个人资料图片

{
  user(id: 4) {
    id
    name
    profilePic(size: 100)
  }
}

一个给定的字段可以存在许多参数

{
  user(id: 4) {
    id
    name
    profilePic(width: 100, height: 50)
  }
}

参数是无序的

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

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

{
  picture(width: 200, height: 100)
}

{
  picture(height: 100, width: 200)
}

2.2.5字段别名

默认情况下，响应对象中的键将使用查询的字段名称。但是，您可以通过指定别名来定义不同的名称。

在此示例中，我们可以获取两个不同大小的个人资料图片，并确保结果对象不会有重复的键

{
  user(id: 4) {
    id
    name
    smallPic: profilePic(size: 64)
    bigPic: profilePic(size: 1024)
  }
}

返回结果

{
  "user": {
    "id": 4,
    "name": "Mark Zuckerberg",
    "smallPic": "https://cdn.site.io/pic-4-64.jpg",
    "bigPic": "https://cdn.site.io/pic-4-1024.jpg"
  }
}

由于查询的顶层是一个字段，因此也可以给它一个别名

{
  zuck: user(id: 4) {
    id
    name
  }
}

返回结果

{
  "zuck": {
    "id": 4,
    "name": "Mark Zuckerberg"
  }
}

字段的响应键是其别名（如果提供了别名），否则是字段的名称。

2.2.6片段

片段是 GraphQL 中组合的主要单元。

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

例如，如果我们想获取有关共同朋友以及某个用户的朋友的一些常见信息

query noFragments {
  user(id: 4) {
    friends(first: 10) {
      id
      name
      profilePic(size: 50)
    }
    mutualFriends(first: 10) {
      id
      name
      profilePic(size: 50)
    }
  }
}

重复的字段可以提取到片段中，并由父片段或查询组成。

query withFragments {
  user(id: 4) {
    friends(first: 10) {
      ...friendFields
    }
    mutualFriends(first: 10) {
      ...friendFields
    }
  }
}

fragment friendFields on User {
  id
  name
  profilePic(size: 50)
}

片段通过使用扩展运算符 (...) 来使用。片段选择的所有字段都将添加到查询字段选择中，其级别与片段调用级别相同。这通过多个级别的片段扩展发生。

例如

query withNestedFragments {
  user(id: 4) {
    friends(first: 10) {
      ...friendFields
    }
    mutualFriends(first: 10) {
      ...friendFields
    }
  }
}

fragment friendFields on User {
  id
  name
  ...standardProfilePic
}

fragment standardProfilePic on User {
  profilePic(size: 50)
}

查询 noFragments、withFragments 和 withNestedFragments 都生成相同的响应对象。

query FragmentTyping {
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ...userFragment
    ...pageFragment
  }
}

fragment userFragment on User {
  friends {
    count
  }
}

fragment pageFragment on Page {
  likers {
    count
  }
}

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

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

query inlineFragmentNoType($expandedInfo: Boolean) {
  user(handle: "zuck") {
    id
    name
    ... @include(if: $expandedInfo) {
      firstName
      lastName
      birthday
    }
  }
}

2.2.7输入值

字段和指令参数接受各种文字原语的输入值；输入值可以是标量、枚举值、列表或输入对象。

如果未定义为常量（例如，在 DefaultValue 中），则输入值可以指定为变量。列表和输入对象也可以包含变量（除非定义为常量）。

2.2.8变量

GraphQL 查询可以使用变量进行参数化，从而最大化查询的重用性，并避免客户端在运行时进行代价高昂的字符串构建。

如果未定义为常量（例如，在 DefaultValue 中），则可以为输入值提供 Variable。

变量必须在操作的顶部定义，并且在该操作的整个执行过程中都处于作用域内。

在此示例中，我们希望根据特定设备的大小获取个人资料图片大小

query getZuckProfile($devicePicSize: Int) {
  user(id: 4) {
    id
    name
    profilePic(size: $devicePicSize)
  }
}

这些变量的值与请求一起提供给 GraphQL 服务，以便在执行期间可以替换它们。如果为变量的值提供 JSON，我们可以运行此查询并请求宽度为 60 的 profilePic

{
  "devicePicSize": 60
}

2.2.9输入类型

GraphQL 描述了查询变量期望的数据类型。输入类型可以是另一个输入类型的列表，或者任何其他输入类型的非空变体。

语义

2.2.10指令

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

在某些情况下，您需要提供选项来更改 GraphQL 的执行行为，而字段参数不足以满足这些需求，例如有条件地包含或跳过字段。指令通过向执行器描述附加信息来提供此功能。

指令具有名称以及参数列表，这些参数列表可以接受任何输入类型的值。

指令可用于描述字段、片段和操作的附加信息。

随着 GraphQL 的未来版本采用新的可配置执行能力，它们可能会通过指令公开。

query hasConditionalFragment($condition: Boolean) {
  ...maybeFragment @include(if: $condition)
}

fragment maybeFragment on Query {
  me {
    name
  }
}

query hasConditionalFragment($condition: Boolean) {
  ...maybeFragment
}

fragment maybeFragment on Query @include(if: $condition) {
  me {
    name
  }
}

3.1.1标量

顾名思义，标量表示 GraphQL 中的原始值。GraphQL 响应采用分层树的形式；这些树上的叶子是 GraphQL 标量。

所有 GraphQL 标量都可以表示为字符串，但根据所使用的响应格式，对于给定的标量类型，可能存在更合适的原始类型，并且服务器应在适当时使用这些类型。

GraphQL 提供了许多内置标量，但类型系统可以添加具有语义含义的其他标量。例如，GraphQL 系统可以定义一个名为 Time 的标量，它虽然序列化为字符串，但承诺符合 ISO-8601。当查询 Time 类型的字段时，您可以依赖使用 ISO-8601 解析器解析结果并为时间使用客户端特定原始类型的功能。另一个可能有用的自定义标量的示例是 Url，它序列化为字符串，但服务器保证它是有效的 URL。

结果强制转换

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

例如，GraphQL 服务器可能正在准备一个标量类型为 Int 的字段，并遇到一个浮点数。由于服务器不得通过产生非整数来破坏约定，因此服务器应截断小数部分，仅产生整数值。如果服务器遇到布尔值 true，则应返回 1。如果服务器遇到字符串，则可能会尝试解析字符串以获取以 10 为基数的整数值。如果服务器遇到某些无法合理强制转换为 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 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 时获取 name，在结果是 photo 时获取 height，则以下查询是无效的，因为联合类型本身没有定义任何字段

{
  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 的结果。上面的输入强制转换应根据输入字段声明的类型的输入强制转换规则执行。

3.1.7列表

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

结果强制转换

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

输入强制转换

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

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

3.1.8非空

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

结果强制转换

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

输入强制转换

{
  field(arg: null)
}

以指示参数为 null。相反，参数为 null 的情况仅当它被省略时

{
  field
}

或者如果传递了一个可为空类型的变量，该变量在运行时未提供值

query withNullableVariable($var: String) {
  field(arg: $var)
}

因此，如果非空类型的值在查询中是硬编码的，则始终使用包装类型的输入强制转换对其进行强制转换。

当使用变量设置非空输入的的值时，如果提供的值在提供的表示形式中是类 null 的，或者如果提供的值被省略，则强制转换的值应为 null。否则，强制转换的值是对提供的值运行包装类型的输入强制转换的结果。

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

如果 @skip 指令和 @include 指令在同一上下文中都提供，则 @skip 指令优先于 @include 指令。

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
}

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。

5.1.1命名操作定义

query getDogName {
  dog {
    name
  }
}

query getOwnerName {
  dog {
    owner {
      name
    }
  }
}

query getName {
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

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 文档中定义的任何选择集
• 令 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 @include(if: true)
  name @include(if: true)
}

而以下是无效的

fragment conflictingDirectiveArgs on Dog {
  name @include(if: true)
  name @include(if: false)
}

5.2.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.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!)
  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.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 {
  notNullBooleanArgField
}

5.4.1片段声明

{
  ...fragmentOne
  ...fragmentTwo
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentTwo on Dog {
  owner {
    name
  }
}

{
  ...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 inlineFragment 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 {
  ...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 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.7.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，这表示结果映射中不应存在此项的条目。请注意，这与返回具有字符串键和 null 值的条目不同，后者表示应为该键添加结果中的条目，并且其值应为 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 } 子选择集。

作为一个说明性示例，假设我们有一个变更字段 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 条目将是请求操作执行的结果。如果操作是查询，则此输出将是模式的查询根类型的对象；如果操作是变更，则此输出将是模式的变更根类型的对象。

如果在执行开始之前遇到错误，则结果中不应存在 data 条目。

如果在执行期间遇到阻止有效响应的错误，则响应中的 data 条目应为 null。

7.2.2错误

响应中的 errors 条目是一个非空错误列表，其中每个错误都是一个映射。

如果在请求的操作期间未遇到错误，则结果中不应存在 errors 条目。

每个错误都必须包含一个键为 message 的条目，其中包含错误的字符串描述，旨在为开发人员提供指导，以理解和纠正错误。

如果错误可以与请求的 GraphQL 文档中的特定点关联，则它应包含一个键为 locations 的条目，其中包含位置列表，其中每个位置都是一个映射，其中包含键 line 和 column，两者都是从 1 开始的正数，描述关联语法元素的开头。

GraphQL 服务器可以根据需要为错误提供其他条目，以生成更有帮助或机器可读的错误，但是未来版本的规范可能会描述错误的附加条目。

如果响应中的 data 条目为 null 或不存在，则响应中的 errors 条目不得为空。它必须至少包含一个错误。它包含的错误应指示为什么无法返回数据。

如果响应中的 data 条目不为 null，则响应中的 errors 条目可能包含执行期间发生的任何错误。如果执行期间发生错误，则应包含这些错误。