API 设计 / 系统课时

处理错误传播与 Null Bubbling

处理错误传播与 Null Bubbling

GraphQL 的字段解析失败并不一定让整次请求失败。本节用一个可运行示例观察 errors、部分 data 与非空字段向上冒泡的关系,并学会用可空边界控制单个 Resolver 故障对响应结构的影响。

学习目标

  • 区分请求级错误与字段执行错误,读懂 data 和 errors 同时出现的响应。
  • 判断 Non-Null 字段发生错误后会冒泡到哪个可空父级。
  • 在对象与列表类型设计中控制错误传播范围,避免不必要的整片数据丢失。

先区分两类失败

语法错误、校验失败等请求级错误发生在执行开始前,因此不会产生正常的字段结果。Resolver 执行期间出现的字段错误则不同:GraphQL 会记录一条 errors,并尝试继续完成不受影响的字段,所以客户端可能同时拿到部分 data 和错误信息。

字段本身是可空类型时,失败位置通常直接变成 null。如果该位置声明为非空类型,例如 String!,GraphQL 不能把 null 放在那里,于是错误会向父字段传播,直到遇到第一个可空位置;若从失败点到根字段一路都是非空,最终 data 会变成 null。

用可空边界理解冒泡

下面的结构中,Billing.plan 与 Profile.billing 都是非空,但 Query.profile 可空。若 plan Resolver 抛错,billing 不能为 null,错误继续向上;到 profile 时才允许用 null 吸收错误,因此同级的 status 仍可返回。

Null Bubbling 从失败字段冒泡到最近可空父级

运行一个最小示例

示例依赖 Node.js 与 graphql 包。保存为 null-bubbling.mjs 后运行该文件;代码主动让 plan Resolver 抛错,并只打印本节关心的 data、错误消息与路径。

js
import { buildSchema, graphql } from "graphql";

const schema = buildSchema(`
  type Query {
    status: String!
    profile: Profile
  }

  type Profile {
    id: ID!
    nickname: String
    billing: Billing!
  }

  type Billing {
    plan: String!
  }
`);

const rootValue = {
  status: "ok",
  profile: () => ({
    id: "u1",
    nickname: "Ada",
    billing: {
      plan: () => {
        throw new Error("billing unavailable");
      },
    },
  }),
};

const source = `
  query {
    status
    profile {
      id
      nickname
      billing { plan }
    }
  }
`;

const result = await graphql({ schema, source, rootValue });

console.log(JSON.stringify({
  data: result.data,
  errors: result.errors?.map(({ message, path }) => ({ message, path })),
}, null, 2));

预期输出:

json
{
  "data": {
    "status": "ok",
    "profile": null
  },
  "errors": [
    {
      "message": "billing unavailable",
      "path": ["profile", "billing", "plan"]
    }
  ]
}

errors[].path 仍定位到真正失败的 plan,而响应中实际被置空的是更高层的 profile。客户端因此应同时检查业务需要的数据与 errors,不能只看到 HTTP 请求成功就假定所有字段都可用。

列表和 Schema 边界

列表还要同时看“列表本身”和“元素”是否非空。[Item] 允许元素为 null;[Item!] 中任一元素无法产生非空值时,整个列表会变成 null;如果外层再写成 [Item!]!,错误还会继续向父级冒泡。

非空约束应表达真实业务不变量,而不是“越严格越好”。把一个不稳定的远程字段放在很长的非空链上,会放大故障半径;相反,对允许降级的子对象保留合理可空边界,可以让客户端拿到仍然可信的部分数据,同时通过 errors.path 精确处理失败位置。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理错误传播与 Null Bubbling

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

登录哪都通