GraphQL 规范执行篇:从请求到响应的完整执行算法解析(graphql-spec)
GraphQL 规范执行篇:从请求到响应的完整执行算法解析(graphql-spec)
本篇技术指南围绕 GraphQL 规范(graphql-spec 仓库)中的 spec/Section 6 -- Execution.md 展开,系统讲解 GraphQL 服务如何把一次请求执行成响应:从请求的构成、操作选取、变量强制转换,到查询 / 变更 / 订阅三种操作的执行,再到选择集收集、字段执行、值完成与错误传播的完整算法链路。读完本文,你将掌握 GraphQL 执行模型的全貌,理解 CollectFields、CompleteValue、非空错误传播等核心算法为何这样设计,并能对照规范原文与仓库中的类型系统、响应等章节独立实现或审查一个符合规范的执行器。
一、执行请求:一次 GraphQL 请求由什么构成
规范开篇即定义:GraphQL 服务通过**执行(Execution)**从一次请求产生一个响应。一次用于执行的 _request_ 由以下几部分信息组成:
| 请求组成部分 | 说明 |
|---|---|
schema |
执行所用的 Schema,通常完全由 GraphQL 服务提供 |
document |
一个 Document,必须包含 GraphQL OperationDefinition,可以包含 FragmentDefinition |
operationName(可选) |
文档中要执行的操作名(当文档含多个操作时必须指定) |
variableValues(可选) |
操作中定义的各变量在运行时提供的值 |
initialValue(可选) |
与正在执行的根类型对应的初始值。概念上,初始值代表 GraphQL 服务可用的“数据宇宙”,实践中服务通常对每个请求使用同一个初始值 |
extensions(可选) |
为实现相关的附加信息保留的映射 |
基于这些信息,执行 ExecuteRequest(schema, document, operationName, variableValues, initialValue) 产生响应,响应按规范 Section 7 -- Response 的格式组织。
规范对请求组件还有两点硬性约束:
- 实现不得向
_request_添加额外属性,以免与未来版本的 GraphQL 规范冲突;实现特有的附加信息应放入extensions。extensions若存在必须是 map,内容无额外限制,但键应使用唯一前缀以避免冲突。 - GraphQL 请求不要求任何特定序列化格式或传输机制,消息序列化与传输由实现服务自行选择。
另外,规范明确:可执行文档(操作定义、片段定义、变量定义)中的描述与注释在执行期间必须被忽略,不得影响可观察的执行、验证或响应结果;但它们可以用于不可观察的用途,例如日志与开发者工具。
1.1 请求执行的总入口:ExecuteRequest
ExecuteRequest(schema, document, operationName, variableValues, initialValue) 的步骤为:
- 令
operation为GetOperation(document, operationName)的结果。 - 令
coercedVariableValues为CoerceVariableValues(schema, operation, variableValues)的结果。 - 若
operation是查询操作:返回ExecuteQuery(operation, schema, coercedVariableValues, initialValue)。 - 否则若
operation是变更操作:返回ExecuteMutation(operation, schema, coercedVariableValues, initialValue)。 - 否则若
operation是订阅操作:返回Subscribe(operation, schema, coercedVariableValues, initialValue)。
可以看出,三条分支的唯一区别在于把“已强制转换的变量值”交给三种操作专属的算法;而变量强制转换发生在所有操作类型之前、执行之前。
1.2 选取操作:GetOperation
GetOperation(document, operationName) 负责在文档中确定要执行的操作:
- 若
operationName为null:- 若
document中恰好只有一个操作,返回该操作; - 否则抛出要求提供
operationName的 request error(请求错误)。
- 若
- 否则:在
document中查找名为operationName的操作;若未找到则抛出 request error;找到则返回。
这就是为什么当一个文档包含多个操作时,客户端必须显式传递 operationName——执行器无法自行猜测该执行哪一个。
二、验证请求:先验证,后执行
执行章节明确引用 Validation 章节的结论:只有通过全部验证规则的请求才应被执行。若已知存在验证错误,应在响应的 errors 列表中报告,请求必须在不执行的情况下失败。
典型的做法是在请求执行前立即验证;但 GraphQL 服务也可以不立即验证就执行请求——前提是该完全相同的请求此前已知通过验证且此后未发生任何变化。规范给出两个例证:
- 请求在开发阶段验证过,之后未改动;
- 服务对请求验证一次后**记忆化(memoize)**结果,避免未来重复验证同一请求。
换言之,规范要求的是“某个时点上已知无验证错误、且之后未变”的请求才可以执行,而非强制每次执行都重新跑一遍验证器。这与缓存的执行计划、预编译查询等实现优化是相容的。
三、变量值强制转换:CoerceVariableValues
若操作定义了变量,执行前必须按变量声明类型的**输入强制转换规则(input coercion)**对变量值进行转换。若在变量值输入强制转换期间遇到 request error,操作将失败且不执行。
CoerceVariableValues(schema, operation, variableValues) 的算法要点:
- 令
coercedValues为空的无序 Map。 - 对
operation定义的每个variableDefinition:- 取变量名
variableName、期望类型variableType、默认值defaultValue; - 断言:
IsInputType(variableType)必须为true(变量类型必须是输入类型); - 判断
variableValues是否为该变量名提供了值(hasValue); - 若
hasValue不为真且存在默认值(包括null默认值):按variableType的输入强制转换规则转换默认值,加入coercedValues; - 否则若
variableType是非空(Non-Nullable)类型,且要么hasValue不为真、要么值为null:抛出 request error; - 否则若
hasValue为真:- 值为
null时直接以null加入coercedValues; - 否则按输入强制转换规则转换,转换失败则抛出 request error,成功则把转换结果加入
coercedValues。
- 值为
- 取变量名
- 返回
coercedValues。
要点解读:
- 默认值可以为
null:规范明确“存在默认值(包括null)”,因此$x: String = null与未提供默认值在“缺省时的行为”上是不同的——前者用null填充,后者在非空类型下会直接报错。 - 非空变量没有缺省值即报错:
$id: ID!若客户端既不传值也不存在默认值,会直接产生 request error,请求在执行前失败。 - 规范注记:该算法与
CoerceArgumentValues()非常相似,二者是同一套输入强制转换思想在“变量”与“字段参数”两个位置上的应用。
四、执行操作:Query、Mutation 与 Subscription
类型系统(见 spec/Section 3 -- Type System.md)必须提供查询根操作类型;若支持变更或订阅,还必须分别提供变更根操作类型与订阅根操作类型。三种操作共享同一套“根选择集执行”机制,差异集中在执行模式(并行 / 串行 / 每事件执行)上。
4.1 查询:并行执行根选择集
查询操作的结果 = 以查询根操作类型执行操作的根选择集(root selection set)。执行查询时可以提供一个初始值。
ExecuteQuery(query, schema, variableValues, initialValue):
- 令
queryType为schema中的根 Query 类型;断言queryType是对象(Object)类型。 - 令
rootSelectionSet为query中的根选择集。 - 返回
ExecuteRootSelectionSet(variableValues, initialValue, queryType, rootSelectionSet, "normal")。
注意最后一个参数 "normal":查询的根选择集以普通模式执行,即允许并行化。
4.2 变更:串行执行根选择集
变更操作的结果 = 在变更根对象类型上执行操作的根选择集,且该选择集必须串行执行。原因是变更操作顶层字段预期会对底层数据系统产生副作用,串行执行这些变更可以避免副作用期间的竞态条件(race conditions)。
ExecuteMutation(mutation, schema, variableValues, initialValue) 与查询几乎同构,唯一区别是根类型换成 Mutation 类型,且执行模式为 "serial":
- 令
mutationType为schema中的根 Mutation 类型;断言其为对象类型。 - 令
rootSelectionSet为mutation中的根选择集。 - 返回
ExecuteRootSelectionSet(variableValues, initialValue, mutationType, rootSelectionSet, "serial")。
4.3 订阅:把源事件流映射为响应事件流
订阅操作的执行结果不是一个即时值,而是一个被称为**响应流(response stream)的事件流:底层源流(source stream)**上每产生一个新事件,就对该事件执行一次操作,把执行结果作为响应流上的一个事件。执行订阅操作会在服务上创建一个持久的函数,把一个底层源流映射为返回的响应流。
Subscribe(subscription, schema, variableValues, initialValue):
- 令
sourceStream为运行CreateSourceEventStream(subscription, schema, variableValues, initialValue)的结果。 - 令
responseStream为运行MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues)的结果。 - 返回
responseStream。
规范用一个聊天应用举例。客户端订阅聊天室新消息:
subscription NewMessages {
newMessage(roomId: 123) {
sender
text
}
}
订阅期间,每当聊天室 ID 为 "123" 的房间发布新消息,sender 与 text 选择就会被求值并推送给客户端,例如:
{
"data": {
"newMessage": {
"sender": "Hagrid",
"text": "You're a wizard!"
}
}
}
“新消息发布到聊天室”可以用一个“发布-订阅(Pub-Sub)”系统实现:聊天室 ID 即“主题(topic)”,每次“发布”携带 sender 与 text。
事件流的抽象定义
规范为订阅引入了一个核心抽象——event stream(事件流):表示随时间产生、可被观察的一系列离散事件。例如 Pub-Sub 系统在“订阅某个主题”时会产出一个事件流,主题上每次“发布”对应一个事件。
事件流具备三种终态行为:
- 正常完成:事件流可在任意时刻完成,通常是因为不会再产生事件;也可以产生无限序列而永不完成。
- 出错完成:事件流遇到错误时,必须以该错误完成。
- 取消:观察者可以随时取消事件流;被取消后事件流必须完成。内部用户代码也可能因任何原因取消事件流,对外表现为该事件流完成。
大规模订阅的支撑建议
查询与变更操作是无状态的,可以通过克隆 GraphQL 服务实例来水平扩展;订阅则是有状态的,需要在订阅存续期内维护 GraphQL 文档、变量及其他上下文。规范建议:考虑单台机器故障导致状态丢失时系统的行为,可通过设立独立的专用服务来分别管理“订阅状态”与“客户端连接”,从而改善持久性与可用性。
传输无关(Delivery Agnostic)
与查询/变更一致,GraphQL 订阅不要求任何特定序列化格式或传输机制。规范只规定响应流的创建、流上每个负载的内容以及流的关闭算法,刻意不规定消息确认(acknowledgement)、缓冲、重发请求或任何服务质量(QoS)细节——这些都由实现服务自行选择。
源流:CreateSourceEventStream 与 ResolveFieldEventStream
source stream(源流)是表示一系列根值的事件流,其中每个根值都会触发一次 GraphQL 执行。与字段值解析一样,创建源流的逻辑是应用相关的(例如订阅 Pub-Sub 主题)。
CreateSourceEventStream(subscription, schema, variableValues, initialValue):
- 令
subscriptionType为 schema 中的根 Subscription 类型;断言其为对象类型。 - 令
selectionSet为subscription的顶层选择集。 - 令
collectedFieldsMap为CollectFields(subscriptionType, selectionSet, variableValues)的结果。 - 若
collectedFieldsMap不恰有一个条目,抛出 request error(订阅操作顶层必须只有一个根字段)。 - 令
fields为collectedFieldsMap第一个条目的值。 - 令
fieldName为fields中第一个字段的名称(注意:使用别名不影响该值)。 - 令
field为fields中的第一个条目。 - 令
argumentValues为CoerceArgumentValues(subscriptionType, field, variableValues)的结果。 - 令
sourceStream为运行ResolveFieldEventStream(subscriptionType, initialValue, fieldName, argumentValues)的结果。 - 返回
sourceStream。
ResolveFieldEventStream(subscriptionType, rootValue, fieldName, argumentValues) 则调用 subscriptionType 为名为 fieldName 的订阅字段提供的内部函数(resolver),传入 rootValue 与 argumentValues。规范特意注明:该算法与 ResolveFieldValue() 故意保持相似,以便在任何操作类型上定义 resolver 时保持一致性。
响应流:MapSourceToResponseEvent 与 ExecuteSubscriptionEvent
源流上的每个事件都会以该事件值作为 initialValue 触发一次订阅选择集的执行。
MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues) 定义了双向的流编排:
- 当
sourceStream发出sourceValue:- 运行
ExecuteSubscriptionEvent(subscription, schema, variableValues, sourceValue)得到executionResult; - 若抛出内部错误:取消
sourceStream,并以该错误完成responseStream; - 否则在
responseStream上发出executionResult。
- 运行
- 当
sourceStream正常完成:正常完成responseStream。 - 当
sourceStream以错误完成:以该错误完成responseStream。 - 当
responseStream被取消:取消sourceStream,并正常完成responseStream。
规范对此的注记很精妙:由于 ExecuteSubscriptionEvent() 已经处理了所有 execution error,而 request error 只会在 CreateSourceEventStream() 期间发生,因此 ExecuteSubscriptionEvent() 后剩余需要处理的错误只有规范未描述的“内部异常错误”。
ExecuteSubscriptionEvent(subscription, schema, variableValues, initialValue) 与 ExecuteQuery() 刻意保持相似(每次事件结果就是这样产生的):
- 令
subscriptionType为 schema 中的根 Subscription 类型;断言其为对象类型。 - 令
rootSelectionSet为subscription中的根选择集。 - 返回
ExecuteRootSelectionSet(variableValues, initialValue, subscriptionType, rootSelectionSet, "normal")。
退订:Unsubscribe
当客户端不再希望接收某个订阅的负载时,Unsubscribe(responseStream) 取消响应流;这会进一步取消源流,是清理订阅所占用的其他资源的良好时机。
Unsubscribe(responseStream):取消 responseStream。
五、执行选择集:收集、合并与递归执行
执行一次 GraphQL 操作是递归地“收集并执行”操作中的每个被选中字段:先从操作最顶层的根选择集收集所有初始选中字段并逐个执行;每个字段完成后,收集其全部子字段并执行;如此持续,直到没有更多子字段可收集。
5.1 根选择集:ExecuteRootSelectionSet
root selection set(根选择集)是 GraphQL 操作提供的顶层选择集,总是从根操作类型上选择字段。执行根选择集需要知道三件事:正在求值的初始值、根类型,以及字段必须串行执行还是普通(并行)执行。
根选择集对三种操作的行为是一致的——查询并行、变更串行、订阅则对源流上的每个事件执行——流程均为:先把选择集收集为 collected fields map,再执行之,返回结果 data 与 errors。
ExecuteRootSelectionSet(variableValues, initialValue, objectType, selectionSet, executionMode):
- 令
collectedFieldsMap为CollectFields(objectType, selectionSet, variableValues)的结果。 - 令
data为运行ExecuteCollectedFields(collectedFieldsMap, objectType, initialValue, variableValues)的结果;若executionMode为"serial"则串行执行,否则普通执行(允许并行化)。 - 令
errors为执行选择集期间产生的所有 execution error 的列表。 - 返回包含
data和errors的无序 map。
5.2 字段收集:CollectFields
执行前,每个选择集都会被转换为 collected fields map:把所有相同响应名(response name)的字段(包括被引用片段中的字段)收集到同一个 field set 中,确保对相同响应名的多次引用只执行一次。
两个关键数据结构:
- collected fields map:有序 map,每个条目是“响应名 → 其关联的 field set”。可通过
CollectFields()从选择集产生,也可通过CollectSubfields()从 field set 内所有条目的选择集产生。 - field set:共享同一响应名(有别名则取别名,否则取字段名)的已选字段的有序集合。验证保证集合内每个字段的名称与参数相同,但子字段可以不同(参见 Field Selection Merging 规则)。
规范特别说明:collected fields map 与 field set 中字段选择的顺序都是有意义的,因此规范用有序 map 与有序集合建模。由 CollectFields() 产生的每个 field set 的深度优先搜索顺序会贯穿整个执行过程,保证字段以稳定、可预测的顺序出现在执行后的响应中——这正是响应章节“Serialized Map Ordering”所依赖的(见 spec/Section 7 -- Response.md)。
规范给出的收集示例——收集该查询选择集会得到含两个条目 "a"、"b" 的 map,其中字段 a 出现两次、字段 b 出现一次:
{
a {
subfield1
}
...ExampleFragment
}
fragment ExampleFragment on Query {
a {
subfield2
}
b
}
CollectFields(objectType, selectionSet, variableValues, visitedFragments) 的算法步骤:
- 若未提供
visitedFragments,初始化为空集合。 - 初始化
collectedFieldsMap为空的有序 map(值为有序集合)。 - 遍历
selectionSet中的每个selection:- 处理
@skip指令:若selection提供@skip且其if参数为true(或为variableValues中值为true的变量),跳过该 selection。 - 处理
@include指令:若selection提供@include且其if参数不为true(也不是variableValues中值为true的变量),跳过该 selection。 - 若
selection是Field:以响应名(别名或字段名)为键,把该字段加入对应的 field set。 - 若
selection是FragmentSpread(片段展开):- 若片段名已在
visitedFragments中,跳过(防止循环引用); - 将片段名加入
visitedFragments; - 在文档中查找该片段,找不到则跳过;
- 取片段的类型条件
fragmentType,若DoesFragmentTypeApply(objectType, fragmentType)为false则跳过; - 递归调用
CollectFields收集片段顶层选择集,并把结果合并进collectedFieldsMap。
- 若片段名已在
- 若
selection是InlineFragment(内联片段):- 取类型条件,若非
null且DoesFragmentTypeApply为false则跳过; - 递归收集其顶层选择集并合并进
collectedFieldsMap。
- 取类型条件,若非
- 处理
- 返回
collectedFieldsMap。
DoesFragmentTypeApply(objectType, fragmentType) 判断片段类型条件是否适用于当前对象类型:
- 片段类型是对象类型:仅当
objectType与fragmentType相同时返回true。 - 片段类型是接口类型:仅当
objectType实现了fragmentType时返回true。 - 片段类型是联合类型:仅当
objectType是fragmentType的可能类型时返回true。
规范还注明:CollectFields() 中求值 @skip 与 @include 的步骤可按任意顺序应用,因为二者是可交换的(commutative)。
5.3 合并选择集:CollectSubfields
为了执行对象类型字段的子选择,需要把父 field set 中每个相同响应名字段的所有选择集合并为一个 collected fields map,表示下一步要执行的子字段。
继续上面的例子:字段 "a" 的值解析完成后,下面多个选择集被收集并合并,使得 "subfield1" 与 "subfield2" 在同一阶段、以同一个值被解析:
{
a {
subfield1
}
...ExampleFragment
}
fragment ExampleFragment on Query {
a {
subfield2
}
b
}
CollectSubfields(objectType, fields, variableValues):
- 令
collectedFieldsMap为空的有序 map。 - 遍历
fields中的每个field:- 取
field的选择集;若为null或空,继续下一个字段。 - 令
fieldCollectedFieldsMap为CollectFields(objectType, fieldSelectionSet, variableValues)的结果。 - 把其中每个响应名及其子字段合并进
collectedFieldsMap。
- 取
- 返回
collectedFieldsMap。
注记:传给 CollectSubfields() 的所有 fields 共享同一个响应名。
5.4 执行已收集字段:ExecuteCollectedFields
执行 collected fields map 时,需要知道正在求值的对象类型、运行时值,以及任何变量的运行时值。执行会递归地解析并完成 map 中每个条目的值,在结果 map 中以相同响应名作为键产生条目。
ExecuteCollectedFields(collectedFieldsMap, objectType, objectValue, variableValues):
- 初始化
resultMap为空的有序 map。 - 遍历
collectedFieldsMap中每个响应名responseName及其fields:- 令
fieldName为fields中第一个条目的名称(别名不影响该值)。 - 令
fieldType为objectType上fieldName定义的返回类型。 - 若
fieldType已定义:- 令
responseValue为ExecuteField(objectType, objectValue, fieldType, fields, variableValues)的结果。 - 在
resultMap中以responseName为键设置responseValue。
- 令
- 令
- 返回
resultMap。
注记:resultMap 按字段在操作中最先出现的顺序排列,细节见字段收集一节。
5.5 错误与非空类型:错误的向上传播
ExecuteCollectedFields() 期间,若某个非空类型的响应位置(response position)抛出 execution error,则该错误必须传播到父响应位置(字段场景是整个选择集,列表位置场景是整个列表),要么在允许时解析为 null,要么继续向更上层传播。如果发生这种情况,尚未执行或尚未产出值的兄弟响应位置可以取消,以避免不必要的工作。
完整的传播规则与响应格式联动,详见后文“处理执行错误”小节与 spec/Section 7 -- Response.md 中的 Response Position 定义。
5.6 普通执行与串行执行
普通执行(Normal):正常情况下,执行器可以按任意顺序(通常是并行)执行 collected fields map 中的条目。因为除变更顶层字段外的字段解析必须无副作用且幂等,执行顺序不得影响结果,服务可以自由选择最优顺序。例如下面这个 collected fields map:
{
birthday {
month
}
address {
street
}
}
一个合法的 GraphQL 执行器可以任意顺序解析这四个字段(当然 birthday 必须先于 month、address 必须先于 street)。
串行执行(Serial):执行变更时,最顶层选择集中的选择按文本出现顺序串行执行。串行执行 collected fields map 时,执行器必须按 map 提供的顺序逐个考虑每个条目,每个条目在结果 map 中的对应条目求值完成后,才能继续下一个条目。例如下面的变更操作,根选择集必须串行执行:
mutation ChangeBirthdayAndAddress($newBirthday: String!, $newAddress: String!) {
changeBirthday(birthday: $newBirthday) {
month
}
changeAddress(address: $newAddress) {
street
}
}
执行器必须依次:
- 运行
ExecuteField()处理changeBirthday——其CompleteValue()期间以普通模式执行{ month }子选择集; - 运行
ExecuteField()处理changeAddress——其CompleteValue()期间以普通模式执行{ street }子选择集。
规范还给出一个自洽的验证示例:假设变更字段 changeTheNumber 返回一个含 theNumber 字段的对象,串行执行下面的选择集(注意这是选择集而非完整文档,使用了 query shorthand):
{
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
}
}
这个例子直观地展示了串行执行的“顺序即语义”:如果并行执行,三个 changeTheNumber 的副作用顺序将不可预测。
六、执行字段:参数转换、值解析与值完成
结果 map 中的每个条目,都是在一个对象类型上、按 collected fields map 中字段名选中执行一个字段的结果。字段执行分三步:先强制转换提供的参数值,再为字段解析一个值,最后完成该值——要么递归执行另一个选择集,要么把标量值强制转换。
ExecuteField(objectType, objectValue, fieldType, fields, variableValues):
- 令
field为fields中第一个条目。 - 令
fieldName为field的字段名。 - 令
argumentValues为CoerceArgumentValues(objectType, field, variableValues)的结果。 - 令
resolvedValue为ResolveFieldValue(objectType, objectValue, fieldName, argumentValues)的结果。 - 返回
CompleteValue(fieldType, fields, resolvedValue, variableValues)的结果。
6.1 字段参数强制转换:CoerceArgumentValues
字段可以携带参数,这些参数由类型系统中该字段的定义声明为特定的输入类型。操作的每个参数位置可以是字面 Value,也可以是运行时提供的 Variable。
CoerceArgumentValues(objectType, field, variableValues) 与变量转换 CoerceVariableValues() 结构几乎一致,差异在于:
- 以
objectType上fieldName定义的argumentDefinitions为基准遍历; - 参数值可以来自
argumentValues(字面值)或variableValues(变量):- 若
argumentValue是Variable且variableValues提供了该变量的值,则采用变量值; - 否则若
argumentValues直接提供了该参数名的值,则采用该字面值;
- 若
- 缺省时若存在默认值(包括
null)则转换默认值; - 否则若参数类型为非空类型且缺值或值为
null,抛出 execution error; - 有值且为非变量字面值时,按输入强制转换规则转换,失败抛 execution error;变量值则直接采用(因为已在
CoerceVariableValues()中转换过)。
两个重要注记:
- 任何在
CoerceArgumentValues()输入强制转换期间产生的 request error 都应改为按 execution error 处理——因为此时已进入执行阶段,字段级错误只影响该响应位置,而非整个请求。 - 变量值不再二次转换,因为
CoerceVariableValues()已在操作执行前完成转换,且合法操作只允许使用合适类型的变量。 - 实现鼓励对参数默认值的强制转换只做一次并缓存结果,以优化性能。
6.2 值解析:ResolveFieldValue
GraphQL 执行几乎可以全部用通用算法描述,但最终必须由暴露 GraphQL 接口的内部系统提供值。这个接入点就是 ResolveFieldValue,它为“某个类型上的某个字段,针对某个真实值”产生一个值。
规范用了一个经典例子:传入对象类型 Person、字段 "soulMate"、表示 John Lennon 的对象值,应产出表示 Yoko Ono 的值。
ResolveFieldValue(objectType, objectValue, fieldName, argumentValues):
- 令
resolver为objectType为名为fieldName的字段提供的内部函数。 - 返回调用
resolver(传入objectValue与argumentValues)的结果。
规范明确提示:resolver 通常是异步的,因为往往要读取底层数据库或网络服务来产出值,这要求 GraphQL 执行器的其余部分处理异步执行流;若字段是列表类型,resolver 返回集合中的每个值本身也可能异步获取。
6.3 值完成:CompleteValue
解析出字段值后,还需“完成”它,确保其符合期望的返回类型。若返回类型是另一个对象类型,则字段执行过程通过收集并执行子字段递归继续。
CompleteValue(fieldType, fields, result, variableValues) 按类型分派:
- 非空类型(Non-Null):对内部类型递归调用
CompleteValue;若结果为null,抛出 execution error;否则返回结果。 - 结果为
null(或类似的内部值如undefined):直接返回null。 - 列表类型(List):若
result不是值集合,抛 execution error;否则返回一个新列表,其中每个列表项是对result中对应项递归调用CompleteValue的结果。 - 标量或枚举类型:返回
CoerceResult(fieldType, result)的结果。 - 对象 / 接口 / 联合类型:
- 对象类型直接作为
objectType; - 接口或联合类型先通过
ResolveAbstractType(fieldType, result)解析出objectType; - 然后
CollectSubfields(objectType, fields, variableValues)收集子字段; - 最后以普通模式(允许并行化)执行
ExecuteCollectedFields。
- 对象类型直接作为
结果强制转换:CoerceResult
值完成的首要目的是确保 resolver 返回值符合 GraphQL 类型系统与服务 schema。这种“动态类型检查”让 GraphQL 能在任何服务内部运行时之上,对返回类型提供一致的保证。内置标量的结果强制转换与序列化细节见 spec/Section 3 -- Type System.md 中 Scalars 的 “Result Coercion and Serialization” 小节。
CoerceResult(leafType, value):
- 断言:
value不为null。 - 调用类型系统为
leafType提供的内部“结果强制转换”方法,传入value;该方法必须返回对该类型有效且不为null的值,否则抛 execution error。
注记:若 resolver 返回 null,会在调用 CoerceResult() 之前的 CompleteValue() 中处理,因此 CoerceResult() 的输入与输出都不得为 null。
抽象类型解析:ResolveAbstractType
完成接口或联合这类抽象返回类型字段时,必须先解析出具体的对象类型,由内部系统以合适方式判定。规范提示:在 Java、C# 这类面向对象环境中,常用方法是用 objectValue 的类名判定对象类型。
ResolveAbstractType(abstractType, objectValue):返回调用类型系统提供的内部方法(用于为给定的 objectValue 判定 abstractType 的对象类型)的结果。
6.4 处理执行错误:部分数据 + 错误列表
execution error(执行错误)是在字段执行、值解析或强制转换期间,在特定响应位置抛出的错误。与导致无数据的 request error(请求错误)不同,执行错误必须被报告在响应中,但通过产生部分 data 来“处理”。这是 GraphQL“部分成功”语义的核心。
完整规则:
- 解析字段(直接或嵌套在任意列表内)时抛出执行错误:该响应位置视为解析为
null,错误必须加入执行结果的errors列表。 - 若响应位置解析为
null(无论源于ResolveFieldValue()返回null还是执行错误),且该位置是Non-Null类型:在该位置抛执行错误,并加入errors列表。 - 若响应位置因已加入
errors列表的执行错误而解析为null:errors列表不得再受影响——每个响应位置最多向 errors 列表添加一个错误。 - 由于
Non-Null响应位置不能为null,执行错误传播到父响应位置处理:父位置可空则解析为null;父位置也是Non-Null则继续向更上层传播。 - 列表包非空:若
List类型包裹Non-Null类型,且列表某个元素响应位置解析为null,则整个列表响应位置必须解析为null;若该List本身又被Non-Null包裹,错误继续向上传播。 - 全链非空:若从请求根到执行错误来源的每个响应位置都是
Non-Null类型,则执行结果中的data条目应为null。
结合 spec/Section 7 -- Response.md 的响应位置与错误格式可形成闭环:错误条目中的 path(响应路径)精确标识出错位置,例如 ["hero", "heroFriends", 1, "name"] 表示 hero 的朋友列表中索引 1 的朋友的 name 字段;当非空字段 name 出错时,null 会冒泡到最近的可空父位置(整个列表元素),客户端可据此区分“真 null”与“错误导致的 null”。
七、贯穿全文的关键设计原则
纵观整个执行章节,可以提炼出几条规范反复强调的设计原则:
- 请求错误与执行错误严格二分:请求错误发生在执行前(语法、验证、变量转换失败),结果是“无 data 的请求错误结果”;执行错误发生在执行中(参数转换、值解析、值强制转换失败),结果是“部分 data + errors”。这条分界在 spec/Section 7 -- Response.md 中被形式化为 execution result、response stream 与 request error result 三种响应形态。
- 执行顺序要么无关紧要、要么被严格规定:普通执行(查询、订阅单事件、所有子选择集)允许任意顺序与并行化,因为字段无副作用;串行执行(变更根选择集)被严格规定为文本顺序,因为变更字段有副作用。这是 GraphQL 并发模型的全部依据。
- 收集即去重:
CollectFields()按响应名把重复字段合并为 field set 并只执行一次,@skip/@include在收集阶段求值,保证执行效率与响应确定性。 - 非空类型是错误传播的管道:
Non-Null既是类型约束,也是执行错误向上冒泡的机制,配合响应路径让客户端能精确定位失败点。 - 传输与序列化无关:请求、订阅流、响应都不绑定特定传输;规范只负责定义算法与语义,工程细节(序列化格式、QoS、Pub-Sub 实现)全部留给实现服务。
八、延伸阅读与源码对照
- spec/Section 6 -- Execution.md:本文主体对应的规范原文,含全部算法的完整伪代码。
- spec/Section 3 -- Type System.md:根操作类型、
Non-Null/List包装类型、输入强制转换、标量 Result Coercion 与 Serialization 的定义来源。 - spec/Section 5 -- Validation.md:执行前的验证规则,特别是 Field Selection Merging 等与字段收集相关的规则。
- spec/Section 7 -- Response.md:执行结果的响应格式、响应位置/响应路径、错误格式与 JSON 序列化约定。
- spec/Appendix B -- Notation Conventions.md:规范中算法、数据集合(列表/集合/映射)与有序性记号的形式化说明。
- spec/Appendix D -- Specified Definitions.md:
@skip、@include等内置指令与预定义标量的规范定义汇总。
若需进一步深入实现细节,可结合规范的 Conformance 附录(spec/Appendix A -- Conformance.md)检验执行器的合规性要求,并以本仓库的 changelogs(如 changelogs/September2025.md)追踪规范演进历史。