API 设计 / 系统课时

看懂一次 GraphQL 请求链路

看懂一次 GraphQL 请求链路

一次 GraphQL 请求并不是“收到 JSON 后直接调用 Resolver”。服务会经历解析、Schema 校验、operation 与变量处理、字段执行和结果组装。掌握这条链路后,就能把不同故障定位到正确阶段。

学习目标

  • 说清解析、校验、变量处理、执行与响应组装的先后关系
  • 理解 Resolver 在字段执行中的职责,以及默认字段解析行为
  • 根据错误出现的阶段判断 Resolver 是否真正执行过

请求执行依赖哪些输入

GraphQL 执行至少依赖 Schema 和已经解析的 Document;一次请求还可能携带 operationName、变量值以及服务端提供的根值。HTTP 服务通常先从请求体中取出 query、variables 和 operationName,再把这些信息交给 GraphQL 实现。

需要注意,HTTP 传输层和 GraphQL 执行层不是同一件事。HTTP 负责接收请求、鉴权头、内容类型和状态码等;GraphQL 执行器负责理解文档、依据类型系统校验并执行 operation。很多框架把两层封装在一个处理函数里,但排障时应把它们拆开观察。

从查询文本到响应数据

一次常见的服务端链路可以按下面的顺序理解:

  1. 解析查询文本,生成可执行 Document。语法不合法时在这一阶段失败。
  2. 使用 Schema 校验 Document,例如字段是否存在、参数是否满足要求、变量使用位置是否兼容。已知未通过校验的请求不应进入执行。
  3. 选择要执行的 operation,并把变量值按声明的输入类型完成强制转换。文档包含多个 operation 时,通常需要明确 operationName。
  4. 执行根选择集并递归处理子选择集。Query 的同级字段通常可以独立执行;Mutation 的顶层字段按规范串行执行。
  5. 对字段求值。框架通常把这一步暴露为 Resolver;没有显式 Resolver 时,实现可以使用默认字段解析逻辑,例如从父对象读取同名属性。
  6. 对 Resolver 结果进行值完成、类型强制转换和空值传播,再组装 data、errors 等响应条目。

GraphQL 请求从解析到响应组装的完整链路

这张图里最重要的分界是:请求错误发生在执行之前,执行错误发生在字段执行期间。前者没有可返回的执行数据;后者可能保留已经成功完成的兄弟字段,并在 errors 中指出失败位置。

用 GraphQL.js 拆开每个阶段

下面用 GraphQL.js 17.0.2 直接调用 parse、validate 和 execute,避免框架把阶段隐藏起来。前置条件是当前 Node.js 项目已经安装 graphql@17.0.2,将代码保存为 request-chain.js 后可直接运行:

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

预期输出:

text
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 的性能问题才不会全部被模糊成一个接口耗时。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

看懂一次 GraphQL 请求链路

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通