API 设计 / 系统课时
看懂一次 GraphQL 请求链路
看懂一次 GraphQL 请求链路
一次 GraphQL 请求并不是“收到 JSON 后直接调用 Resolver”。服务会经历解析、Schema 校验、operation 与变量处理、字段执行和结果组装。掌握这条链路后,就能把不同故障定位到正确阶段。
学习目标
- 说清解析、校验、变量处理、执行与响应组装的先后关系
- 理解 Resolver 在字段执行中的职责,以及默认字段解析行为
- 根据错误出现的阶段判断 Resolver 是否真正执行过
请求执行依赖哪些输入
GraphQL 执行至少依赖 Schema 和已经解析的 Document;一次请求还可能携带 operationName、变量值以及服务端提供的根值。HTTP 服务通常先从请求体中取出 query、variables 和 operationName,再把这些信息交给 GraphQL 实现。
需要注意,HTTP 传输层和 GraphQL 执行层不是同一件事。HTTP 负责接收请求、鉴权头、内容类型和状态码等;GraphQL 执行器负责理解文档、依据类型系统校验并执行 operation。很多框架把两层封装在一个处理函数里,但排障时应把它们拆开观察。
从查询文本到响应数据
一次常见的服务端链路可以按下面的顺序理解:
- 解析查询文本,生成可执行 Document。语法不合法时在这一阶段失败。
- 使用 Schema 校验 Document,例如字段是否存在、参数是否满足要求、变量使用位置是否兼容。已知未通过校验的请求不应进入执行。
- 选择要执行的 operation,并把变量值按声明的输入类型完成强制转换。文档包含多个 operation 时,通常需要明确
operationName。 - 执行根选择集并递归处理子选择集。Query 的同级字段通常可以独立执行;Mutation 的顶层字段按规范串行执行。
- 对字段求值。框架通常把这一步暴露为 Resolver;没有显式 Resolver 时,实现可以使用默认字段解析逻辑,例如从父对象读取同名属性。
- 对 Resolver 结果进行值完成、类型强制转换和空值传播,再组装
data、errors等响应条目。

这张图里最重要的分界是:请求错误发生在执行之前,执行错误发生在字段执行期间。前者没有可返回的执行数据;后者可能保留已经成功完成的兄弟字段,并在 errors 中指出失败位置。
用 GraphQL.js 拆开每个阶段
下面用 GraphQL.js 17.0.2 直接调用 parse、validate 和 execute,避免框架把阶段隐藏起来。前置条件是当前 Node.js 项目已经安装 graphql@17.0.2,将代码保存为 request-chain.js 后可直接运行:
const {
buildSchema,
parse,
validate,
execute,
} = require('graphql');
const schema = buildSchema(`
type User {
id: ID!
name: String!
}
type Query {
user(id: ID!): User
}
`);
const source = `
query GetUser($id: ID!) {
user(id: $id) {
id
name
}
}
`;
const rootValue = {
user({ id }) {
// 只有解析、校验和变量处理通过后,根字段 Resolver 才会执行。
console.log(`Resolver Query.user(${id})`);
return { id, name: 'Ada' };
},
};
async function main() {
const document = parse(source);
const errors = validate(schema, document);
if (errors.length > 0) {
console.error(errors.map((error) => error.message));
process.exitCode = 1;
return;
}
// execute 负责选择 operation、执行字段并完成结果组装。
const result = await execute({
schema,
document,
rootValue,
operationName: 'GetUser',
variableValues: { id: '42' },
});
console.log(JSON.stringify(result, null, 2));
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});预期输出:
Resolver Query.user(42)
{
"data": {
"user": {
"id": "42",
"name": "Ada"
}
}
}这个示例只为 Query.user 定义了显式 Resolver。返回对象中的 id 与 name 由默认字段解析器读取,因此并不是 Schema 中的每个字段都必须手写一个函数。生产服务通常会为需要访问数据库、缓存或下游 API 的字段提供显式 Resolver。
用错误阶段判断根因
如果查询文本括号不闭合,错误发生在 Parse,Schema 甚至还没有参与校验。如果查询了 Schema 中不存在的字段,Parse 可以成功,但 Validate 会失败,Resolver 不会被调用。变量类型不合法或缺少必填变量,也会在字段执行前终止请求。
如果 Resolver 在执行中抛错,情况不同:GraphQL 会记录执行错误,并根据字段的可空性决定该位置是否变成 null、错误是否向父级传播,以及其他兄弟字段能否继续形成部分数据。最终响应常见为同时存在 data 和 errors,而不是简单等同于“整个请求失败”。
排查延迟时也应按这条链路分层:解析与校验慢,通常关注超大文档、重复校验或查询缓存;执行慢,则继续拆到具体字段 Resolver、数据库、缓存和下游 RPC。只有把“请求前处理”和“字段执行”分开计时,GraphQL 的性能问题才不会全部被模糊成一个接口耗时。