GraphQL 查询语言深度解析:从词法到语义读懂 graphql-spec 的 Language 章节

原创2026-09-21 17:33:101,889 阅读
文章标签:API设计后端

GraphQL 查询语言深度解析:从词法到语义读懂 graphql-spec 的 Language 章节

GraphQL 查询语言(Query Language)是 GraphQL 规范中客户端向服务端发起请求的核心载体,本篇文章以 graphql-spec 仓库中 spec/Section 2 -- Language.md 为骨架,系统讲解该语言的词法文法、语法文法与静态语义:源文本如何处理、记号(Token)如何切分、文档(Document)、操作(Operation)、选择集(Selection Set)、字段、参数、片段(Fragment)、输入值、变量、指令(Directive)与 Schema 坐标(Schema Coordinate)如何被精确定义。读完本文,你将掌握 GraphQL 语言规范中每一个生产式(production)的含义与边界情况,并能在自己的实现或工具中对照规范逐条核验解析行为。

一、语言的整体架构:词法分析与语法解析

GraphQL 查询语言被定义为一套句法文法(syntactic grammar),其终结符号(terminal symbol)是记号(Token),即不可再分的词法单元;而记号本身又由一套**词法文法(lexical grammar)**定义,匹配源字符的模式。规范用两种符号区分这两套文法:

  • 语法文法(syntactic grammar)生产式使用单个冒号 : 定义;
  • 词法文法(lexical grammar)生产式使用双冒号 :: 定义。

关于这两套文法的详细记法(终结符、非终结符、but not 约束、lookahead 限制、?/+ 简写、参数化生产式、算法与数据结构约定),可进一步阅读 spec/Appendix B -- Notation Conventions.md,本文后续出现的所有文法记号均遵循该附录的定义。

一个 GraphQL 文档的源文本必须是一系列 {SourceCharacter};这些字符序列必须能够被一系列 {Token} 与 {Ignored} 词法文法描述;而忽略掉 {Ignored} 之后得到的词法记号序列,必须能被单一的 {Document} 语法文法描述。

处理流程分两步:

  1. 词法分析(Lexical Analysis):源文本从左到右扫描,反复按词法文法生产式取出"下一个可能的代码点序列"作为下一个记号,得到 {Token} 与 {Ignored} 序列;
  2. 语法解析(Syntactic Parse):词法记号序列再从左到右扫描,依据 {Document} 语法文法生成抽象语法树(AST)。

为消除歧义并保证词法分析结果唯一,词法文法生产式大量使用 lookahead 限制(lookahead restrictions):一个词法记号只有在"其后不紧跟其 lookahead 限制中的字符"时才有效。例如 {IntValue} 带有限制 [lookahead != Digit],即其后不能紧跟数字:因此 123 不能表示 12 与 3 两个记号(12 之后紧跟着数字 3),只能表示一个完整的记号 123。如果需要表达多个记号,就必须用空白或其他 {Ignored} 分隔。

补充:这与编程语言理论中的"最长匹配"(maximal munch)原则行为基本一致,但规范的 lookahead 限制还包含额外约束,因此并不完全等同。规范全文中的文法生产式汇总见 spec/Appendix C -- Grammar Summary.md。

二、源文本(Source Text)

SourceCharacter :: "Any Unicode scalar value"

GraphQL 文档由源文本解释而来,源文本是 {SourceCharacter} 的序列。每个 {SourceCharacter} 都是一个 Unicode 标量值(Unicode scalar value),即 U+0000 到 U+D7FF、或 U+E000 到 U+10FFFF 范围内的任意 Unicode 码点(规范中非正式地称之为"字符")。

规范对字符集采取务实策略:

  • 为使文档能被尽可能多的既有工具、语言和序列化格式兼容,并避免在文本编辑器与源码管理工具中出现显示问题,GraphQL 文档建议仅使用 ASCII 范围表达;
  • 非 ASCII 的 Unicode 标量值允许出现在 {StringValue}(字符串值)与 {Comment}(注释)中。

关于 UTF-16 代理对(surrogate pair)的注意事项:使用 UTF-16 在内存中表示 GraphQL 文档的实现(例如 JavaScript 或 Java)可能遇到代理对——它编码一个补充码点(supplementary code point),是一个合法且单一的源字符;但不成对的代理码点(unpaired surrogate code point)不是合法的源字符。另外,自 September 2025 版本起,GraphQL 语言已更新为支持完整 Unicode 范围(参见 changelogs/September2025.md 中的相关记录)。

2.1 空白(White Space)

Whitespace ::
- "Horizontal Tab (U+0009)"
- "Space (U+0020)"

空白用于提升源文本可读性并分隔其他记号。任意数量的空白可以出现在任意记号之前或之后;记号之间的空白对 GraphQL 文档的语义没有影响。但空白字符可以出现在 {String}(字符串)或 {Comment}(注释)记号内部,此时它们是有效内容。

规范特别指出:GraphQL 有意不将 Unicode "Zs" 类别字符视为空白,以避免被文本编辑器和源码管理工具误解。

2.2 行终止符(Line Terminators)

LineTerminator ::
- "New Line (U+000A)"
- "Carriage Return (U+000D)" [lookahead != "New Line (U+000A)"]
- "Carriage Return (U+000D)" "New Line (U+000A)"

与空白类似,行终止符用于提升可读性并分隔词法记号,可出现在任意记号前后,对文档语义无影响。注意第三行:\r\n 组合被视为一个行终止符。规范还要求:任何按源文件行号报告语法错误的实现,应使用前面出现的 {LineTerminator} 数量来产生行号。

2.3 注释(Comments)

Comment :: `#` CommentChar* [lookahead != CommentChar]
CommentChar :: SourceCharacter but not LineTerminator

GraphQL 源文档支持以 # 标记开头的单行注释。注释可包含除 {LineTerminator} 外的任意 {SourceCharacter},因此一个注释总是从 # 开始、到行终止符(或源文本结束)之前的所有字符。注释与空白一样属于 {Ignored},可以出现在任意记号之后或行终止符之前,对文档语义没有影响。

2.4 无意义的逗号(Insignificant Commas)

Comma :: ,

与空白、行终止符类似,逗号 , 用于提升可读性并分隔词法记号,但在 GraphQL 文档中在语法与语义上均无意义。这一设计保证了:逗号的有无不会改变文档被解释的语法——这恰是其他语言中常见的用户错误;同时允许开发者按风格自由选择"尾随逗号"或"行终止符"作为列表分隔符,两者都是提升源码可读性与可维护性的常见做法。

2.5 词法记号(Lexical Tokens)

Token ::
- Punctuator
- Name
- IntValue
- FloatValue
- StringValue

GraphQL 文档由若干种不可再分的词法记号组成,这些记号由词法文法以源 Unicode 字符的模式定义。词法记号之间可以由 {Ignored} 记号分隔。记号随后作为 GraphQL 语法文法规则中的终结符号被使用。

2.6 忽略记号(Ignored Tokens)

Ignored ::
- UnicodeBOM
- Whitespace
- LineTerminator
- Comment
- Comma

{Ignored} 记号用于提升可读性、为词法记号提供分隔,除此之外无意义,语法文法生产式不会引用它们。任意数量的 {Ignored} 可以出现在每个词法记号之前与之后;源文档中没有任何被忽略的区域是"有意义"的,但出现在 {Ignored} 中的 {SourceCharacter} 也可能以有意义的方式出现在词法 {Token} 内部——例如 {StringValue} 可以包含空白字符。反过来,任何 {Ignored} 都不得出现在 {Token} 内部,例如 {FloatValue} 的组成字符之间不允许出现空白。

字节顺序标记(Byte Order Mark)

UnicodeBOM :: "Byte Order Mark (U+FEFF)"

BOM 是特殊的 Unicode 码点,可能出现在文件开头,程序据此判断文本流是否为 Unicode 及其具体编码。由于文件经常被拼接,BOM 可能出现在任意词法记号之前或之后,因此被定义为 {Ignored}。

2.7 标点(Punctuators)

Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | }

GraphQL 文档使用标点描述结构。GraphQL 是数据描述语言而非编程语言,因此缺少常用于数学表达式的标点。

2.8 名称(Names)

Name ::
- NameStart NameContinue* [lookahead != NameContinue]

NameStart ::
- Letter
- `_`

NameContinue ::
- Letter
- Digit
- `_`

Letter :: one of
- `A` `B` `C` `D` `E` `F` `G` `H` `I` `J` `K` `L` `M`
- `N` `O` `P` `Q` `R` `S` `T` `U` `V` `W` `X` `Y` `Z`
- `a` `b` `c` `d` `e` `f` `g` `h` `i` `j` `k` `l` `m`
- `n` `o` `p` `q` `r` `s` `t` `u` `v` `w` `x` `y` `z`

Digit :: one of
- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`

GraphQL 文档中有大量被命名的事物:操作、字段、参数、类型、指令、片段、变量。所有名称都必须遵循同一文法形式:

  • 名称以字母或下划线 _ 开头,后跟零或多个字母、数字、下划线;
  • 名称区分大小写:name、Name 与 NAME 是三个不同的名称;
  • 下划线有意义:other_name 与 othername 是两个不同的名称;
  • 名称不能后跟 {NameContinue},即名称记号总是"最长可能有效序列":源字符 a1 不能被解释为两个记号,因为 a 后紧跟 {NameContinue} 字符 1;
  • 名称被限定在拉丁 ASCII 子集内,以支持与尽可能多的其他系统互操作。

保留名称(Reserved Names):类型系统中的任何名称都不得以双下划线 __ 开头,除非它属于规范定义的 内省系统(introspection system) 的一部分。

三、描述(Descriptions)

Description : StringValue

文档化是 GraphQL 的一等特性:可执行 {Document} 与 GraphQL 类型系统中的所有具名定义都可以附带书面描述,且这些描述可通过内省(introspection)获取,确保服务文档与其能力保持一致(见 Type System 章节的描述部分)。

GraphQL 描述使用 Markdown(按 CommonMark 规范)书写;描述字符串(通常是 {BlockString} 块字符串)必须紧挨在被描述的定义之前。

关键语义:可执行文档中的描述纯粹用于文档目的,绝不能影响 GraphQL 文档的执行、验证或响应。从可执行文档中删除所有描述和注释是绝对安全的,不会改变其行为或结果。(值得一提的是,自 September 2025 版起,描述也被引入可执行文档以更好地服务 AI 消费场景,参见 changelogs/September2025.md。)

规范给出的"良好描述操作"示例:

"""
Request the current status of a time machine and its operator.
You can also check the status for a particular year.
**Warning:** certain years may trigger an anomaly in the space-time continuum.
"""
query GetTimeMachineStatus(
  "The unique serial number of the time machine to inspect."
  $machineId: ID!
  "The year to check the status for."
  $year: Int
) {
  timeMachine(id: $machineId) {
    ...TimeMachineDetails
    status(year: $year)
  }
}

"Details about a time machine and its operator."
fragment TimeMachineDetails on TimeMachine {
  id
  model
  lastMaintenance
  operator {
    name
    licenseLevel
  }
}

注意示例展示了两种描述写法:块字符串("""...""")用于操作与变量的整体说明,普通字符串("...")用于变量与片段的说明。

四、文档(Document)

Document : Definition+

Definition :
- ExecutableDefinition
- TypeSystemDefinitionOrExtension

ExecutableDocument : ExecutableDefinition+

ExecutableDefinition :
- OperationDefinition
- FragmentDefinition

GraphQL 文档描述一个完整的文件或请求字符串,由 GraphQL 服务或客户端操作。文档包含多个定义(definition),既可以是可执行的,也可以代表 GraphQL 类型系统。

关于可执行性的规则值得精确掌握:

  • 只有 {ExecutableDocument} 且至少包含一个 {OperationDefinition} 的文档才能被 GraphQL 服务执行;
  • 包含 {TypeSystemDefinitionOrExtension} 的文档不得被执行,收到此类文档的 GraphQL 执行服务应返回描述性错误;
  • 只寻求执行请求、不构建新 schema 的 GraphQL 服务,可以选择只允许 {ExecutableDocument};
  • 不含 {OperationDefinition} 或含 {TypeSystemDefinitionOrExtension} 的文档仍然可以被解析和验证,以便客户端工具表示跨多个文件的多种 GraphQL 用法。

操作命名的规则:若文档只含一个操作,该操作可以匿名;若该操作是没有变量、没有指令的查询,还可以用简写形式省略 query 关键字与操作名。若文档含多个操作,则每个操作都必须命名;向服务提交含多个操作的文档时,还必须提供要执行的操作名。

五、操作(Operations)

OperationDefinition :
- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet
- SelectionSet

OperationType : one of `query` `mutation` `subscription`

GraphQL 建模三种操作:

  • query:只读获取(read-only fetch);
  • mutation:先写入、后获取(write followed by a fetch);
  • subscription:长连接请求,按时间顺序响应一系列事件来获取数据。

每个操作由一个可选的操作名和一个**选择集(selection set)**表示。例如,下面的 mutation 操作"点赞"一个故事并取回新的点赞数:

"""
Mark story 12345 as "liked"
and return the updated number of likes on the story
"""
mutation {
  likeStory(storyID: 12345) {
    story {
      likeCount
    }
  }
}

查询简写(Query Shorthand)

如果文档只含一个操作,且该操作是不定义变量、不应用指令的查询,则可以用简写形式省略 query 关键字与操作名:

{
  field
}

注意:查询简写上不允许出现描述。后续规范示例大量使用这种简写语法。

六、选择集(Selection Sets)

SelectionSet : { Selection* }

Selection :
- Field
- FragmentSpread
- InlineFragment

操作选择它所需的信息集合,并且将恰好收到这些信息,不多不少,从而避免数据过度获取(over-fetching)与获取不足(under-fetching)。选择集是针对对象(object)、联合(union)或接口(interface)类型的有序选择集合(字段、片段展开、内联片段)。

{
  id
  firstName
  lastName
}

在此查询操作中,id、firstName、lastName 字段构成一个选择集。选择集也可以包含片段引用。

七、字段(Fields)

Field : Alias? Name Arguments? Directives? SelectionSet?

选择集主要由字段组成。一个字段描述选择集内可请求的一小块离散信息。有些字段描述复杂数据或与其他数据的关系,此时字段可以自身包含选择集,支持深层嵌套请求。所有 GraphQL 操作都必须将选择一路指定到叶子字段(leaf fields),以保证响应形状明确无歧义。

下面的操作把复杂数据与关系一路选择到标量值:

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

操作顶层选择集中的字段通常代表全局可访问的信息,例如当前登录查看者(viewer)的引用,或通过唯一标识符访问的某类数据:

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

八、参数(Arguments)

Arguments[Const] : ( Argument[?Const]+ )
Argument[Const] : Name : Value[?Const]

字段在概念上是返回值、偶尔接受参数以改变行为的函数。这些参数通常直接映射到 GraphQL 服务实现中的函数参数。

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

一个字段可以有很多参数:

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

参数是无序的(Arguments Are Unordered)

参数可以以任意语法顺序提供,且保持完全相同的语义。下面两个操作语义相同:

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

注意语法中的 [Const] 参数化标记:当参数出现于要求常量(const)的上下文中(例如 {DefaultValue} 默认值)时,参数值不允许包含变量;非 const 上下文(例如普通字段调用)中则允许变量。

九、字段别名(Field Alias)

Alias : Name :

**响应名(response name)**是响应对象中与字段结果对应的键。默认情况下响应名使用字段名;但你可以通过指定别名(alias)定义不同的响应名。

例如,我们可以获取两张不同尺寸的个人头像,并确保响应对象不会出现重复键:

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

十、片段(Fragments)

FragmentSpread : ... FragmentName Directives?
FragmentDefinition : Description? fragment FragmentName TypeCondition Directives? SelectionSet
FragmentName : Name but not `on`

片段是 GraphQL 中最主要的组合单元(primary unit of composition)。客户端应用中每个消费数据的组件(函数、类、UI 元素等)都应在独立的片段中声明其数据需求;这些片段随后按照组件自身的用法被组合成发给服务器的 GraphQL 操作。

例如,渲染个人资料需要 id、name、profilePic,我们希望对用户的好友和共同好友都应用这段逻辑:

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) {
      ...friendProfile
    }
    mutualFriends(first: 10) {
      ...friendProfile
    }
  }
}
"Fields required to render a friend's profile"
fragment friendProfile on User {
  id
  name
  profilePic(size: 50)
}

可维护性价值:如果资料渲染逻辑不再需要 name,只需从 friendProfile 片段中删除 name 字段,两个消费位置便都不再获取它。

片段通过展开运算符(...)被消费。片段选择的所有字段都会添加到与片段调用同一层级的选择中,且这种展开会穿透多层片段嵌套。例如:

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 三个操作产生完全相同的响应对象。

10.1 类型条件(Type Conditions)

TypeCondition : on NamedType

片段必须指定其适用的类型。片段不能指定在输入值(标量、枚举或输入对象)上;可以指定在对象类型、接口和联合上。片段内的选择只有在被操作对象的**具体类型(concrete type)**与片段类型匹配时才返回值。

例如在 Facebook 数据模型下:

query FragmentTyping {
  profiles(handles: ["zuck", "coca-cola"]) {
    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": "coca-cola",
      "likers": { "count": 90234512 }
    }
  ]
}

10.2 内联片段(Inline Fragments)

InlineFragment : ... TypeCondition? Directives? SelectionSet

片段也可以在选择集内部内联定义。这适用于:基于类型条件条件性地包含字段,或对一组选择应用指令。

上文 query FragmentTyping 的示例可以用内联片段实现同样效果:

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

内联片段还可以用于对一组字段应用指令。若省略 TypeCondition,内联片段被视为与所在上下文类型相同:

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

十一、输入值(Input Values)

Value[Const] :
- [~Const] Variable
- IntValue
- FloatValue
- StringValue
- BooleanValue
- NullValue
- EnumValue
- ListValue[?Const]
- ObjectValue[?Const]

字段和指令参数接受各种字面量基本类型的输入值;输入值可以是标量、枚举值、列表或输入对象。若未定义为常量(例如 {DefaultValue} 中的情形),输入值还可以指定为变量;列表和输入对象也可以包含变量(除非定义为常量)。

11.1 整数值(Int Value)

IntValue :: IntegerPart [lookahead != {Digit, `.`, NameStart}]

IntegerPart ::
- NegativeSign? 0
- NegativeSign? NonZeroDigit Digit*

NegativeSign :: -
NonZeroDigit :: Digit but not `0`

{IntValue} 不带小数点或指数,但可以为负(如 -123),且不得有前导 0(即 0123 非法,0 与 -0 合法)。

它的 lookahead 限制十分关键:

  • 不得紧跟数字:12 不能被解释为两个记号(1 后紧跟数字 2);同理源文本 00 非法,因为它既不能解释为单个记号,也不能解释为两个 0 记号;
  • 不得紧跟 . 或 {NameStart}:如果其后紧跟 . 或指数指示符(e/E),则该记号只能被解释为可能的 {FloatValue};其余 {NameStart} 字符也不得紧跟。例如 0x123 与 123L 都没有合法的词法表示。

11.2 浮点值(Float Value)

FloatValue ::
- IntegerPart FractionalPart ExponentPart [lookahead != {Digit, `.`, NameStart}]
- IntegerPart FractionalPart [lookahead != {Digit, `.`, NameStart}]
- IntegerPart ExponentPart [lookahead != {Digit, `.`, NameStart}]

FractionalPart :: . Digit+
ExponentPart :: ExponentIndicator Sign? Digit+
ExponentIndicator :: one of `e` `E`
Sign :: one of + -

{FloatValue} 包含小数点(如 1.0)或指数(如 1e50)或两者(如 6.0221413e23),可以为负;与 {IntValue} 一样不得有前导 0。

lookahead 限制同样严格:

  • 不得紧跟数字:1.23 不能被解释为两个记号(1.2 后紧跟数字 3);
  • 不得紧跟 .:例如 1.23.4 不能被解释为两个记号(1.2、3.4);
  • 不得紧跟 {NameStart}:例如 0x1.2p3 没有合法的词法表示。

设计意图:{IntValue} 与 {FloatValue} 都限制其后紧跟字母(或其他 {NameStart}),是为了减少困惑或意外行为——GraphQL 只支持十进制数字。

11.3 布尔值(Boolean Value)

BooleanValue : one of `true` `false`

关键字 true 与 false 表示两个布尔值。

11.4 字符串值(String Value)

StringValue ::
- `""` [lookahead != `"`]
- `"` StringCharacter+ `"`
- BlockString

StringCharacter ::
- SourceCharacter but not `"` or `\` or LineTerminator
- `\u` EscapedUnicode
- `\` EscapedCharacter

EscapedUnicode ::
- `{` HexDigit+ `}`
- HexDigit HexDigit HexDigit HexDigit

HexDigit :: one of
- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`
- `A` `B` `C` `D` `E` `F`
- `a` `b` `c` `d` `e` `f`

EscapedCharacter :: one of `"` `\` `/` `b` `f` `n` `r` `t`

BlockString :: `"""` BlockStringCharacter* `"""`
BlockStringCharacter ::
- SourceCharacter but not `"""` or `\"""`
- `\"""`

一个 {StringValue} 通过按下文静态语义解释所有转义序列,被求值为一个 Unicode 文本(Unicode text) 值,即 Unicode 标量值序列。词法记号之间被忽略的空白等字符在字符串值内部是有意义的。

空字符串 "" 后不得紧跟另一个 ",否则会被解释为块字符串的开始。例如源文本 """""" 只能被解释为一个空块字符串,而不是三个空字符串。

转义序列(Escape Sequences)

在单引号字符串中,任意 Unicode 标量值都可以用转义序列表达。GraphQL 字符串同时支持:

  • C 风格转义序列(例如 \n);
  • 两种 Unicode 转义:固定宽度 4 位十六进制(例如 \u000A),以及变宽形式(例如 \u{1F4A9}),后者最适合表示补充字符(如 Emoji)。

Unicode 转义编码的十六进制数必须描述一个 Unicode 标量值,否则必须产生解析错误。例如 "\uDEAD" 与 "\u{110000}" 都不是合法的 {StringValue}。

转义序列仅在单引号字符串中有意义:在块字符串中它们只是字面字符序列(例如 """\n""" 表示 Unicode 文本 [U+005C, U+006E]);在注释中也不构成有意义的字符序列;在 GraphQL 文档的其他位置不允许出现。

由于 {StringCharacter} 不能直接包含某些码点(例如行终止符),必须用转义序列表示它们。所有其他转义序列都是可选的,字符串中允许未转义的非 ASCII Unicode 字符;如果使用的系统只支持 ASCII,则可用转义序列表示 ASCII 范围外的所有 Unicode 字符。

遗留形式(legacy surrogate pair):出于历史原因,补充字符可以由两个固定宽度 Unicode 转义构成代理对来表达,例如 "\uD83D\uDCA9" 是合法的 {StringValue},与 "\u{1F4A9}" 表示相同的 Unicode 文本。这种遗留形式虽然被允许,但应避免使用,变宽 Unicode 转义是更清晰的编码方式。

输出建议:产生 {StringValue} 时,实现应使用转义序列表示不可打印的控制字符(U+0000 到 U+001F 与 U+007F 到 U+009F)。其他转义序列并非必需,但实现可以使用转义序列表示任何其他码点范围(例如生成仅 ASCII 的输出)。如果实现选择转义补充字符,应只使用变宽 Unicode 转义序列。

块字符串(Block Strings)

块字符串是用三引号(""")包裹的字符序列。空白、行终止符、引号与反斜杠字符都可以不加转义地使用,从而实现逐字文本(verbatim text)。所有字符都必须是合法的 {SourceCharacter}。

由于块字符串常表示缩进位置中的自由文本,其字符串值语义会通过 {BlockStringValue()} 排除统一的缩进以及空白的首尾行。例如下面的块字符串:

mutation {
  sendEmail(message: """
    Hello,
      World!

    Yours,
      GraphQL.
  """)
}

与标准引号字符串完全相同:

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

由于块字符串值会剥离首尾空行,因此给定的值不存在唯一规范的打印块字符串。因为块字符串通常表示自由文本,规范建议以空行开头和结尾以便阅读:

"""
This starts with and ends with an empty line,
which makes it easier to read.
"""
"""This does not start with or end with any empty lines,
which makes it a little harder to read."""

注意事项:如果字符串值中需要不可打印的 ASCII 字符,必须使用带适当转义序列的标准引号字符串,而不是块字符串。

静态语义(Static Semantics)

{StringValue} 描述一个 Unicode 文本值(Unicode 标量值序列)。以下语义描述如何将 {StringValue} 文法应用于源文本以求出 Unicode 文本;求值过程中的错误被视为"未能将 {StringValue} 文法应用于源",必须导致解析错误。

StringValue :: `""`
  • 返回空序列。
StringValue :: `"` StringCharacter+ `"`
  • 通过拼接所有 {StringCharacter} 的求值结果返回 Unicode 文本。
StringCharacter :: SourceCharacter but not `"` or `\` or LineTerminator
  • 返回 {SourceCharacter} 的 Unicode 标量值。
StringCharacter :: `\u` EscapedUnicode
  • 令 {value} 为 {EscapedUnicode} 内 {HexDigit} 序列所表示的十六进制值;
  • 断言:{value} 在 Unicode 标量值范围内(>= 0x0000 且 <= 0xD7FF,或 >= 0xE000 且 <= 0x10FFFF);
  • 返回 Unicode 标量值 {value}。
StringCharacter :: `\u` HexDigit HexDigit HexDigit HexDigit `\u` HexDigit HexDigit HexDigit HexDigit
  • 令 {leadingValue} 为第一组 {HexDigit} 的十六进制值,{trailingValue} 为第二组的十六进制值;
  • 若 {leadingValue} 在 0xD800 到 0xDBFF 之间(前导代理 Leading Surrogate):
    • 断言:{trailingValue} 在 0xDC00 到 0xDFFF 之间(尾随代理 Trailing Surrogate);
    • 返回 ({leadingValue} - 0xD800) × 0x400 + ({trailingValue} - 0xDC00) + 0x10000;
  • 否则:
    • 断言:{leadingValue} 与 {trailingValue} 都在 Unicode 标量值范围内;
    • 返回先 {leadingValue} 后 {trailingValue} 的标量值序列。

补充:若两个转义序列都编码 Unicode 标量值,则该语义与对每个固定宽度转义分别应用前述语义完全相同。变宽转义序列必须只编码一个 Unicode 标量值。

StringCharacter :: `\` EscapedCharacter
  • 按下表返回 {EscapedCharacter} 表示的 Unicode 标量值:
转义字符 标量值 字符名
" U+0022 双引号(double quote)
\ U+005C 反斜线(reverse solidus)
/ U+002F 正斜线(solidus)
b U+0008 退格(backspace)
f U+000C 换页(form feed)
n U+000A 换行(line feed)
r U+000D 回车(carriage return)
t U+0009 水平制表(horizontal tab)
StringValue :: BlockString
  • 通过求值 {BlockString} 返回 Unicode 文本。
BlockString :: `"""` BlockStringCharacter* `"""`
  • 令 {rawValue} 为拼接所有 {BlockStringCharacter} 求值结果得到的 Unicode 文本(可以为空序列);
  • 返回 {BlockStringValue(rawValue)} 的结果。
BlockStringCharacter :: SourceCharacter but not `"""` or `\"""`
  • 返回 {SourceCharacter} 的 Unicode 标量值。
BlockStringCharacter :: `\"""`
  • 返回字符序列 """。

BlockStringValue(rawValue) 算法——这是理解块字符串"去缩进"行为的关键:

  1. 令 {lines} 为按 {LineTerminator} 分割 {rawValue} 得到的行序列;
  2. 令 {commonIndent} 为 {null};
  3. 对 {lines} 中的每一行 {line}(跳过第一行):令 {length} 为该行字符数,{indent} 为该行前导连续 {Whitespace} 字符数;若 {indent} 小于 {length}(即该行非纯空白),则当 {commonIndent} 为 {null} 或 {indent} 小于 {commonIndent} 时,令 {commonIndent} 为 {indent};
  4. 若 {commonIndent} 不为 {null}:对除第一行外的每一行,从行首移除 {commonIndent} 个字符;
  5. 当第一行只含 {Whitespace} 时,将其从 {lines} 移除(剥离首部空行);
  6. 当最后一行只含 {Whitespace} 时,将其从 {lines} 移除(剥离尾部空行);
  7. 用换行符(U+000A)连接剩余各行(第一行不前置换行),返回格式化后的字符串。

这个算法精确解释了为什么前面的 sendEmail 示例中,块字符串与 "Hello,\n World!\n\nYours,\n GraphQL." 完全等价:各行统一缩进被剥离,首尾空行被丢弃,行间以 \n 连接,而 World! 与 GraphQL. 内部的额外缩进得以保留。

11.5 空值(Null Value)

NullValue : `null`

空值用关键字 null 表示。GraphQL 有两种语义不同的"缺少值"方式:

  • 显式提供字面量:null;
  • 隐式不提供值:完全不提供该值。

例如下面两个字段调用相似但不相同:

{
  field(arg: null)
  field
}

第一个显式向参数 arg 提供了 null,第二个则隐式地没有向参数 arg 提供值。两者可能被不同地解释——例如 mutation 中"删除某字段"与"不修改某字段"的区别。注意:这两种形式都不能用于期望 Non-Null 类型的输入。通过变量也可以实现同样的两种缺值方式:要么把变量值提供为 null,要么完全不提供该变量值。

11.6 枚举值(Enum Value)

EnumValue : Name but not `true`, `false` or `null`

枚举值用不带引号的名称表示(例如 MOBILE_WEB)。规范建议枚举值使用"全大写"。枚举值只在精确枚举类型已知的上下文中使用,因此字面量中无需提供枚举类型名。

11.7 列表值(List Value)

ListValue[Const] :
- [ ]
- [ Value[?Const]+ ]

列表是用方括号 [ ] 包裹的有序值序列。列表字面量的值可以是任意值字面量或变量(例如 [1, 2, 3])。由于逗号在 GraphQL 中全程可选,因此允许尾随逗号,且重复的逗号并不代表缺失值。

语义:空列表 [] 返回新的空列表值;[ Value+ ] 则依次求值每个 {Value} 并追加到新列表中返回。

11.8 输入对象值(Input Object Values)

ObjectValue[Const] :
- { }
- { ObjectField[?Const]+ }

ObjectField[Const] : Name : Value[?Const]

输入对象字面量是用花括号 { } 包裹的无序键值输入值列表,称为"对象字面量"(object literal)。例如 { name: "Hello world", score: 1.0 }。

输入对象字段是无序的:下面两个操作语义相同:

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

语义:空对象 { } 返回无字段的新输入对象值;{ ObjectField+ } 则依次为每个字段添加"名称-求值后的值"条目并返回。规范在附录 B 中建议:当顺序可观察时,实现应尽量保持源顺序,以提升输出可读性与稳定性(参见 spec/Appendix B -- Notation Conventions.md 关于数据集合的说明)。

十二、变量(Variables)

Variable : $ Name

VariablesDefinition : ( VariableDefinition+ )
VariableDefinition : Description? Variable : Type DefaultValue? Directives[Const]?
DefaultValue : = Value[Const]

GraphQL 操作可以用变量参数化,从而最大化复用,避免客户端在运行时进行昂贵的字符串拼接。若未定义为常量(例如在 {DefaultValue} 中),则 {Variable} 可以作为输入值提供。

变量必须在操作顶部定义,并在该操作的整个执行期间处于作用域内。变量的值作为请求的一部分提供给 GraphQL 服务,在执行期间被代入。

例如,根据特定设备的尺寸获取头像大小:

query getZuckProfile(
  "The size of the profile picture to fetch."
  $devicePicSize: Int
) {
  user(id: 4) {
    id
    name
    profilePic(size: $devicePicSize)
  }
}

如果以 JSON 提供变量值,可以请求尺寸为 60 的 profilePic:

{
  "devicePicSize": 60
}

片段中的变量使用(Variable Use Within Fragments)

变量可以在片段中使用。变量在给定操作内具有全局作用域,因此片段中使用的变量必须被任何传递性地消费该片段的顶层操作声明。如果片段中引用了变量,而包含该片段的操作没有定义该变量,则该操作无效(参见 Validation 章节的 "All Variable Uses Defined" 规则)。

十三、类型引用(Type References)

Type :
- NamedType
- ListType
- NonNullType

NamedType : Name
ListType : [ Type ]
NonNullType :
- NamedType !
- ListType !

GraphQL 描述参数与变量期望的数据类型。输入类型可以是另一输入类型的列表,也可以是任何其他输入类型的非空(non-null)变体。

语义:

  • Type : Name:令 {name} 为 {Name} 的字符串值;令 {type} 为 Schema 中名为 {name} 的类型;{type} 必须存在;返回 {type}。
  • Type : [ Type ]:令 {itemType} 为求值 {Type} 的结果;令 {type} 为以 {itemType} 为包含类型的 List 类型;返回 {type}。
  • Type : Type !:令 {nullableType} 为求值 {Type} 的结果;令 {type} 为以 {nullableType} 为包含类型的 Non-Null 类型;返回 {type}。

十四、指令(Directives)

Directives[Const] : Directive[?Const]+
Directive[Const] : @ Name Arguments[?Const]?

指令提供了一种在 GraphQL 文档中描述替代运行时执行与类型验证行为的方式。当需要提供字段参数无法满足的执行选项(例如条件性包含或跳过某字段)时,指令通过向执行器描述附加信息来实现。

指令拥有名称和参数列表,参数可接受任意输入类型的值。指令可以用于描述类型、字段、片段和操作的附加信息。随着未来版本的 GraphQL 采纳新的可配置执行能力,它们可能通过指令暴露;GraphQL 服务与工具也可以提供规范所述之外的任意自定义指令(custom directive)。

指令顺序是有意义的(Directive Order Is Significant)

指令可以以特定的语法顺序提供,该顺序可能具有语义解释。例如下面两个类型定义可能具有不同的语义:

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

这与字段参数、输入对象字段的"无序"语义形成鲜明对比,是 GraphQL 语言中少数顺序敏感的位置之一。

十五、Schema 坐标(Schema Coordinates)

SchemaCoordinate ::
- TypeCoordinate
- MemberCoordinate
- ArgumentCoordinate
- DirectiveCoordinate
- DirectiveArgumentCoordinate

TypeCoordinate :: Name
MemberCoordinate :: Name . Name
ArgumentCoordinate :: Name . Name ( Name : )
DirectiveCoordinate :: @ Name
DirectiveArgumentCoordinate :: @ Name ( Name : )

Schema 坐标是唯一标识 GraphQL Schema 内**模式元素(schema element)**的人类可读字符串,供工具引用类型、字段等元素。典型用途包括:文档中引用 schema 中的类型与字段、在日志工具中作为查找键以追踪生产环境中特定字段被查询的频率等。模式元素可以是具名类型、字段、输入字段、枚举值、字段参数、指令或指令参数(包括内建类型与内建指令)。

边界情况:

  • 元字段(meta-field)不是在 schema 中定义的,因此不是模式元素;由此内省类型也不是模式元素;
  • **包含元素(containing element)**定义为在语法上包含该元素、少一个 {Name} 记号的模式元素:{ArgumentCoordinate} 的包含元素是 {MemberCoordinate};{MemberCoordinate} 的包含元素是 {TypeCoordinate};{DirectiveArgumentCoordinate} 的包含元素是 {DirectiveCoordinate};{TypeCoordinate} 与 {DirectiveCoordinate} 没有包含元素;
  • Schema 坐标总是唯一的:每个模式元素恰好可由一个 schema 坐标引用;
  • Schema 坐标可以引用已定义的或内建的模式元素,例如 String 与 @deprecated(reason:) 都是指向内建模式元素的合法坐标;
  • 联合成员(union member)引用 schema 中的类型,类型由 {TypeCoordinate} 标识;不存在指示联合成员的 schema 坐标,这保证了上述唯一性。

Schema Coordinates 是 September 2025 版规范引入的标准(见 changelogs/September2025.md 中的 RFC #794 记录),旨在为 GraphQL 工具与上报提供统一标准。

15.1 解析 Schema 坐标(Parsing a Schema Coordinate)

SchemaCoordinateToken ::
- SchemaCoordinatePunctuator
- Name

SchemaCoordinatePunctuator :: one of ( ) . : @

{SchemaCoordinate} 是一套自包含的文法,拥有自己的一组词法记号,它不包含在 {Document} 之内。Schema 坐标的源文本必须是 {SourceCharacter} 序列。

与 GraphQL 文档 不同,{SchemaCoordinate} 的字符序列内不得包含 {Whitespace} 或其他 {Ignored} 文法。这保证了每个 schema 坐标都有单一、无歧义、唯一的词法形式。

15.2 求解 Schema 坐标(Resolving a Schema Coordinate)

要引用模式元素,必须在某个 GraphQL {schema} 的上下文中解释 schema 坐标。如果找不到模式元素,求解函数将不产生值(且不抛错);但如果 schema 坐标中的任何非叶节点无法在 {schema} 中找到,则会抛出错误。

注意:虽然在语法上可以用 schema 坐标描述元字段或内省 schema 的元素(例如 Business.__typename 或 __Type.fields(includeDeprecated:)),但它们不是模式元素,求解这类坐标没有定义的行为。

各坐标的求解算法如下:

TypeCoordinate :: Name
  1. 令 {typeName} 为 {Name} 的值;
  2. 若存在,返回 {schema} 中名为 {typeName} 的类型。
MemberCoordinate :: Name . Name
  1. 令 {typeName} 为第一个 {Name} 的值;
  2. 令 {type} 为 {schema} 中名为 {typeName} 的类型;
  3. 断言:{type} 必须存在,且必须是 Enum、Input Object、Object 或 Interface 类型;
  4. 若 {type} 是 Enum 类型:令 {enumValueName} 为第二个 {Name} 的值;若存在,返回 {type} 中名为 {enumValueName} 的枚举值;
  5. 否则若 {type} 是 Input Object 类型:令 {inputFieldName} 为第二个 {Name} 的值;若存在,返回 {type} 中名为 {inputFieldName} 的输入字段;
  6. 否则:令 {fieldName} 为第二个 {Name} 的值;若存在,返回 {type} 中名为 {fieldName} 的字段。
ArgumentCoordinate :: Name . Name ( Name : )
  1. 令 {typeName} 为第一个 {Name} 的值;
  2. 令 {type} 为 {schema} 中名为 {typeName} 的类型;
  3. 断言:{type} 必须存在,且必须是 Object 或 Interface 类型;
  4. 令 {fieldName} 为第二个 {Name} 的值;令 {field} 为 {type} 中名为 {fieldName} 的字段;
  5. 断言:{field} 必须存在;
  6. 令 {fieldArgumentName} 为第三个 {Name} 的值;
  7. 若存在,返回 {field} 中名为 {fieldArgumentName} 的参数。
DirectiveCoordinate :: @ Name
  1. 令 {directiveName} 为 {Name} 的值;
  2. 若存在,返回 {schema} 中名为 {directiveName} 的指令。
DirectiveArgumentCoordinate :: @ Name ( Name : )
  1. 令 {directiveName} 为第一个 {Name} 的值;
  2. 令 {directive} 为 {schema} 中名为 {directiveName} 的指令;
  3. 断言:{directive} 必须存在;
  4. 令 {directiveArgumentName} 为第二个 {Name} 的值;
  5. 若存在,返回 {directive} 中名为 {directiveArgumentName} 的参数。

15.3 Schema 坐标示例

元素种类 Schema 坐标 模式元素
具名类型 Business Business 类型
字段 Business.name Business 类型上的 name 字段
输入字段 SearchCriteria.filter SearchCriteria 输入对象类型上的 filter 输入字段
枚举值 SearchFilter.OPEN_NOW SearchFilter 枚举的 OPEN_NOW 值
字段参数 Query.searchBusiness(criteria:) Query 类型上 searchBusiness 字段的 criteria 参数
指令 @private @private 指令
指令参数 @private(scope:) @private 指令的 scope 参数

上表展示了基于以下 schema 的每种模式元素对应的 schema 坐标示例:

type Query {
  searchBusiness(criteria: SearchCriteria!): [Business]
}

input SearchCriteria {
  name: String
  filter: SearchFilter
}

enum SearchFilter {
  OPEN_NOW
  DELIVERS_TAKEOUT
  VEGETARIAN_MENU
}

type Business {
  id: ID
  name: String
  email: String @private(scope: "loggedIn")
}

directive @private(scope: String!) on FIELD_DEFINITION

十六、小结:如何把这份语言规范用起来

GraphQL 语言章节是整套规范(由 spec/GraphQL.md 总览,完整目录含 Overview、Type System、Introspection、Validation、Execution、Response 等章节)中客户端请求能力的基础。实践中你可以:

  • 对照 词法文法与语法文法汇总 快速检索任意生产式,例如需要确认 FloatValue 是否允许前导零或指数符号时,直接查 FloatValue 的定义;
  • 在实现解析器时,严格遵循"词法分析 → 语法解析"两阶段模型,并落实每条 lookahead 限制(如 IntValue 后禁止数字、.、字母),否则会错误地接受 0x123、1.23.4 这类非法输入;
  • 实现字符串求值时,按 {StringValue} 静态语义处理转义序列与代理对,并用 {BlockStringValue()} 算法处理块字符串的去缩进与首尾空行剥离;
  • 构建工具链(文档引用、日志追踪、lint 规则)时,采用 Schema Coordinates 作为类型、字段、参数、指令的标准寻址方式,注意其"不允许空白、唯一、非叶节点缺失即报错"等特性。

以上所有语法生产式、算法步骤与示例均直接来自本仓库的 spec/Section 2 -- Language.md(共 1559 行),与 Grammar Summary、Notation Conventions 以及 September 2025 版变更记录 changelogs/September2025.md 保持一致,可作为实现 GraphQL 解析器、校验器与相关工具时逐条核对的事实依据。

登录后查看全文
graphql-spec