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 表达业务承诺

假设商品搜索一定返回一个列表,但部分旧数据可能缺少标签;而推荐商品可能整体不可计算,但一旦返回列表,其中每个商品都必须存在。可以这样声明:

graphql
type Product {
  id: ID!
  name: String!
  tags: [String]!
}

type Query {
  products: [Product!]!
  recommendations: [Product!]
}

这是接口定义示例。products 承诺列表永远存在且不存在空商品;无结果时返回 []。recommendations 允许整个列表为 null,适合“推荐系统暂时无法给出结果”这类可缺失语义。

客户端查询可以保持简单:

graphql
query ProductLists {
  products {
    id
    name
    tags
  }
  recommendations {
    id
    name
  }
}

预期结果

json
{
  "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 合同,应该由真实数据保证和兼容性要求共同决定。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理列表与 Nullability

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

登录哪都通