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 仍可返回。

运行一个最小示例
示例依赖 Node.js 与 graphql 包。保存为 null-bubbling.mjs 后运行该文件;代码主动让 plan Resolver 抛错,并只打印本节关心的 data、错误消息与路径。
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));预期输出:
{
"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 精确处理失败位置。