GraphQL 规范执行篇:从请求到响应的完整执行算法解析(graphql-spec)

原创2026-09-21 23:34:041,627 阅读
文章标签:API设计后端

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) 的步骤为:

  1. 令 operation 为 GetOperation(document, operationName) 的结果。
  2. 令 coercedVariableValues 为 CoerceVariableValues(schema, operation, variableValues) 的结果。
  3. 若 operation 是查询操作:返回 ExecuteQuery(operation, schema, coercedVariableValues, initialValue)。
  4. 否则若 operation 是变更操作:返回 ExecuteMutation(operation, schema, coercedVariableValues, initialValue)。
  5. 否则若 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) 的算法要点:

  1. 令 coercedValues 为空的无序 Map。
  2. 对 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。
  3. 返回 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):

  1. 令 queryType 为 schema 中的根 Query 类型;断言 queryType 是对象(Object)类型。
  2. 令 rootSelectionSet 为 query 中的根选择集。
  3. 返回 ExecuteRootSelectionSet(variableValues, initialValue, queryType, rootSelectionSet, "normal")。

注意最后一个参数 "normal":查询的根选择集以普通模式执行,即允许并行化。

4.2 变更:串行执行根选择集

变更操作的结果 = 在变更根对象类型上执行操作的根选择集,且该选择集必须串行执行。原因是变更操作顶层字段预期会对底层数据系统产生副作用,串行执行这些变更可以避免副作用期间的竞态条件(race conditions)。

ExecuteMutation(mutation, schema, variableValues, initialValue) 与查询几乎同构,唯一区别是根类型换成 Mutation 类型,且执行模式为 "serial":

  1. 令 mutationType 为 schema 中的根 Mutation 类型;断言其为对象类型。
  2. 令 rootSelectionSet 为 mutation 中的根选择集。
  3. 返回 ExecuteRootSelectionSet(variableValues, initialValue, mutationType, rootSelectionSet, "serial")。

4.3 订阅:把源事件流映射为响应事件流

订阅操作的执行结果不是一个即时值,而是一个被称为**响应流(response stream)的事件流:底层源流(source stream)**上每产生一个新事件,就对该事件执行一次操作,把执行结果作为响应流上的一个事件。执行订阅操作会在服务上创建一个持久的函数,把一个底层源流映射为返回的响应流。

Subscribe(subscription, schema, variableValues, initialValue):

  1. 令 sourceStream 为运行 CreateSourceEventStream(subscription, schema, variableValues, initialValue) 的结果。
  2. 令 responseStream 为运行 MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues) 的结果。
  3. 返回 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):

  1. 令 subscriptionType 为 schema 中的根 Subscription 类型;断言其为对象类型。
  2. 令 selectionSet 为 subscription 的顶层选择集。
  3. 令 collectedFieldsMap 为 CollectFields(subscriptionType, selectionSet, variableValues) 的结果。
  4. 若 collectedFieldsMap 不恰有一个条目,抛出 request error(订阅操作顶层必须只有一个根字段)。
  5. 令 fields 为 collectedFieldsMap 第一个条目的值。
  6. 令 fieldName 为 fields 中第一个字段的名称(注意:使用别名不影响该值)。
  7. 令 field 为 fields 中的第一个条目。
  8. 令 argumentValues 为 CoerceArgumentValues(subscriptionType, field, variableValues) 的结果。
  9. 令 sourceStream 为运行 ResolveFieldEventStream(subscriptionType, initialValue, fieldName, argumentValues) 的结果。
  10. 返回 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() 刻意保持相似(每次事件结果就是这样产生的):

  1. 令 subscriptionType 为 schema 中的根 Subscription 类型;断言其为对象类型。
  2. 令 rootSelectionSet 为 subscription 中的根选择集。
  3. 返回 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):

  1. 令 collectedFieldsMap 为 CollectFields(objectType, selectionSet, variableValues) 的结果。
  2. 令 data 为运行 ExecuteCollectedFields(collectedFieldsMap, objectType, initialValue, variableValues) 的结果;若 executionMode 为 "serial" 则串行执行,否则普通执行(允许并行化)。
  3. 令 errors 为执行选择集期间产生的所有 execution error 的列表。
  4. 返回包含 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) 的算法步骤:

  1. 若未提供 visitedFragments,初始化为空集合。
  2. 初始化 collectedFieldsMap 为空的有序 map(值为有序集合)。
  3. 遍历 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。
  4. 返回 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):

  1. 令 collectedFieldsMap 为空的有序 map。
  2. 遍历 fields 中的每个 field:
    • 取 field 的选择集;若为 null 或空,继续下一个字段。
    • 令 fieldCollectedFieldsMap 为 CollectFields(objectType, fieldSelectionSet, variableValues) 的结果。
    • 把其中每个响应名及其子字段合并进 collectedFieldsMap。
  3. 返回 collectedFieldsMap。

注记:传给 CollectSubfields() 的所有 fields 共享同一个响应名。

5.4 执行已收集字段:ExecuteCollectedFields

执行 collected fields map 时,需要知道正在求值的对象类型、运行时值,以及任何变量的运行时值。执行会递归地解析并完成 map 中每个条目的值,在结果 map 中以相同响应名作为键产生条目。

ExecuteCollectedFields(collectedFieldsMap, objectType, objectValue, variableValues):

  1. 初始化 resultMap 为空的有序 map。
  2. 遍历 collectedFieldsMap 中每个响应名 responseName 及其 fields:
    • 令 fieldName 为 fields 中第一个条目的名称(别名不影响该值)。
    • 令 fieldType 为 objectType 上 fieldName 定义的返回类型。
    • 若 fieldType 已定义:
      • 令 responseValue 为 ExecuteField(objectType, objectValue, fieldType, fields, variableValues) 的结果。
      • 在 resultMap 中以 responseName 为键设置 responseValue。
  3. 返回 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
  }
}

执行器必须依次:

  1. 运行 ExecuteField() 处理 changeBirthday——其 CompleteValue() 期间以普通模式执行 { month } 子选择集;
  2. 运行 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):

  1. 令 field 为 fields 中第一个条目。
  2. 令 fieldName 为 field 的字段名。
  3. 令 argumentValues 为 CoerceArgumentValues(objectType, field, variableValues) 的结果。
  4. 令 resolvedValue 为 ResolveFieldValue(objectType, objectValue, fieldName, argumentValues) 的结果。
  5. 返回 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):

  1. 令 resolver 为 objectType 为名为 fieldName 的字段提供的内部函数。
  2. 返回调用 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):

  1. 断言:value 不为 null。
  2. 调用类型系统为 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“部分成功”语义的核心。

完整规则:

  1. 解析字段(直接或嵌套在任意列表内)时抛出执行错误:该响应位置视为解析为 null,错误必须加入执行结果的 errors 列表。
  2. 若响应位置解析为 null(无论源于 ResolveFieldValue() 返回 null 还是执行错误),且该位置是 Non-Null 类型:在该位置抛执行错误,并加入 errors 列表。
  3. 若响应位置因已加入 errors 列表的执行错误而解析为 null:errors 列表不得再受影响——每个响应位置最多向 errors 列表添加一个错误。
  4. 由于 Non-Null 响应位置不能为 null,执行错误传播到父响应位置处理:父位置可空则解析为 null;父位置也是 Non-Null 则继续向更上层传播。
  5. 列表包非空:若 List 类型包裹 Non-Null 类型,且列表某个元素响应位置解析为 null,则整个列表响应位置必须解析为 null;若该 List 本身又被 Non-Null 包裹,错误继续向上传播。
  6. 全链非空:若从请求根到执行错误来源的每个响应位置都是 Non-Null 类型,则执行结果中的 data 条目应为 null。

结合 spec/Section 7 -- Response.md 的响应位置与错误格式可形成闭环:错误条目中的 path(响应路径)精确标识出错位置,例如 ["hero", "heroFriends", 1, "name"] 表示 hero 的朋友列表中索引 1 的朋友的 name 字段;当非空字段 name 出错时,null 会冒泡到最近的可空父位置(整个列表元素),客户端可据此区分“真 null”与“错误导致的 null”。

七、贯穿全文的关键设计原则

纵观整个执行章节,可以提炼出几条规范反复强调的设计原则:

  1. 请求错误与执行错误严格二分:请求错误发生在执行前(语法、验证、变量转换失败),结果是“无 data 的请求错误结果”;执行错误发生在执行中(参数转换、值解析、值强制转换失败),结果是“部分 data + errors”。这条分界在 spec/Section 7 -- Response.md 中被形式化为 execution result、response stream 与 request error result 三种响应形态。
  2. 执行顺序要么无关紧要、要么被严格规定:普通执行(查询、订阅单事件、所有子选择集)允许任意顺序与并行化,因为字段无副作用;串行执行(变更根选择集)被严格规定为文本顺序,因为变更字段有副作用。这是 GraphQL 并发模型的全部依据。
  3. 收集即去重:CollectFields() 按响应名把重复字段合并为 field set 并只执行一次,@skip/@include 在收集阶段求值,保证执行效率与响应确定性。
  4. 非空类型是错误传播的管道:Non-Null 既是类型约束,也是执行错误向上冒泡的机制,配合响应路径让客户端能精确定位失败点。
  5. 传输与序列化无关:请求、订阅流、响应都不绑定特定传输;规范只负责定义算法与语义,工程细节(序列化格式、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)追踪规范演进历史。

登录后查看全文
graphql-spec