API 设计 / 系统课时
处理列表与 Nullability
处理列表与 Nullability
GraphQL 的列表类型同时包含“列表本身”和“列表元素”两层可空性。正确组合 [] 与 !,才能既表达真实业务约束,又避免某个意外空值把过多响应数据一起变成 null。
学习目标
- 区分
[T]、[T!]、[T]!与[T!]!的约束差异 - 判断空列表、
null列表与null元素是否被类型允许 - 理解非空字段出错时的错误传播,并选择合适的 Nullability
读懂列表类型的两层约束
[] 表示 List,! 表示 Non-Null。读类型时从内向外看:先判断元素类型是否带 !,再判断整个列表是否带 !。
| 类型 | 列表可为 null |
元素可为 null |
合法示例 |
|---|---|---|---|
[String] |
是 | 是 | null、[]、["A", null] |
[String!] |
是 | 否 | null、[]、["A"] |
[String]! |
否 | 是 | []、["A", null] |
[String!]! |
否 | 否 | []、["A"] |
这里最容易误判的是空列表。! 只禁止 null,不会要求列表至少有一个元素,因此 [String!]! 仍然允许 []。如果业务要求“至少一个元素”,需要在应用层或自定义校验规则中额外验证。
用 Schema 表达业务承诺
假设商品搜索一定返回一个列表,但部分旧数据可能缺少标签;而推荐商品可能整体不可计算,但一旦返回列表,其中每个商品都必须存在。可以这样声明:
type Product {
id: ID!
name: String!
tags: [String]!
}
type Query {
products: [Product!]!
recommendations: [Product!]
}这是接口定义示例。products 承诺列表永远存在且不存在空商品;无结果时返回 []。recommendations 允许整个列表为 null,适合“推荐系统暂时无法给出结果”这类可缺失语义。
客户端查询可以保持简单:
query ProductLists {
products {
id
name
tags
}
recommendations {
id
name
}
}预期结果
{
"data": {
"products": [
{
"id": "p1",
"name": "Keyboard",
"tags": ["input", null]
}
],
"recommendations": null
}
}tags 的元素允许为 null,所以示例响应符合 [String]!;recommendations 本身允许为 null,也符合 [Product!]。真实字段值由服务端 resolver 和数据源决定。
理解非空错误如何向上冒泡
Non-Null 不只是文档说明,它还会改变执行结果。如果某字段声明为非空,但 resolver 最终得到 null,GraphQL 会记录字段错误,并把 null 向父级传播,直到遇到一个可空边界。
例如 products: [Product!]! 中某个元素最终无法形成 Product,因为元素类型是 Product!,这个元素不能单独变成 null;错误会使整个列表失败。列表本身又是非空,因此还会继续向它的父级传播。
选择合适的 Nullability
设计时先回答业务语义,而不是先决定符号。若“没有数据”和“系统无法给出数据”需要区分,可以用 [] 表示前者、null 表示后者;若列表元素理论上绝不应该缺失,则应优先使用非空元素类型,避免客户端逐项判空。
对已有 Schema 更要谨慎。把输出字段从可空改成非空,意味着服务端必须从此兑现更强承诺;把输入参数从可空改成非空,则会直接要求旧客户端补传值。Nullability 最终表达的是 API 合同,应该由真实数据保证和兼容性要求共同决定。