GraphQL-Nexus 中的可空性设计指南

GraphQL-Nexus 中的可空性设计指南

nexus Code-First, Type-Safe, GraphQL Schema Construction 项目地址: https://gitcode.com/gh_mirrors/ne/nexus

可空性设计原则

在构建 GraphQL API 时，特别是在生产环境或功能正式发布前，合理设计参数和输入对象字段（输入）是否必填、对象类型字段（输出）是否可为空是至关重要的。API 的易用性与可维护性之间存在权衡关系。

输入输出的可空性影响

输入可空性影响：

• 如果输入设为可选，客户端开发者使用更简单，无需预先配置
• 但 API 开发者后期将可选输入改为必填会是破坏性变更

输出可空性影响：

• 如果输出保证非空，客户端处理响应更简单
• 但后期将非空输出改为可为空也是破坏性变更
• 过多的非空输出会增加"空值爆炸半径"风险

空值爆炸半径

"空值爆炸半径"是指当数据源返回 null 或错误时，由于 GraphQL 类型系统声明该字段非空，null 会沿着查询路径向上传播，直到遇到第一个可为空的类型（或最终在根节点报错）。这种机制虽然保证了类型安全，但可能导致大面积数据缺失。

GraphQL-Nexus 的可空性实现

Nexus 默认采用保守策略：

• 所有输入和输出默认都是可为空的
• 这种设计让 API 演化更灵活，但客户端需要处理更多空值情况

默认行为解析

默认行为的优势：

• 输出可空：后期可自由调整而不会破坏客户端
• 输入可为空：客户端使用门槛低
• 最小化空值爆炸半径

默认行为的代价：

• 客户端需要处理更多空值情况
• 后期将输入从可选改为必填会破坏现有客户端

可空性配置层级

Nexus 提供了多层级配置方案：

1. 全局默认配置：

makeSchema({
  nonNullDefaults: {
    input: false,  // 输入默认可为空
    output: false  // 输出默认可为空
  }
})

2. 类型级别覆盖：

queryType({
  nonNullDefaults: {
    input: true,   // 该类型下输入默认为必填
    output: true   // 该类型下输出默认为非空
  }
})

3. 字段级别覆盖：

t.field('example', {
  type: nonNull('String'),       // 强制该字段非空
  args: {
    param: nullable(stringArg()) // 强制该参数可为空
  }
})

默认参数的特殊情况

当参数设置默认值时，需注意：

• 客户端不传参数时会使用默认值
• 但客户端仍可显式传递 null
• 因此解析器仍需处理 null 情况

示例：

t.nonNull.string('echo', {
  args: {
    message: stringArg({ default: '默认消息' })
  },
  resolve(_root, args) {
    // 仍需处理 args.message 为 null 的情况
    return args.message ?? '客户端显式传递了null'
  }
})

对应的 GraphQL 操作：

query {
  result1: echo            # 返回"默认消息"
  result2: echo(message: null) # 返回"客户端显式传递了null"
}

最佳实践建议

1. 初期设计原则：

   • 产品初期优先采用默认的可空设置
   • 随着API稳定，逐步将确定不会为空的输出标记为非空
   • 将业务上必须的输入标记为必填

2. 类型一致性：

   • 同一业务领域的类型保持可空性一致
   • 避免混合使用不同策略造成客户端处理混乱

3. 错误处理：

   • 对于非空字段，确保解析器有完善的错误处理
   • 考虑使用自定义错误类型替代返回null

4. 文档说明：

   • 清晰记录哪些字段可能为null及原因
   • 说明必填参数的业务约束条件

通过合理运用Nexus提供的多层级可空性控制，开发者可以在API灵活性、健壮性和易用性之间找到最佳平衡点。

nexus Code-First, Type-Safe, GraphQL Schema Construction 项目地址: https://gitcode.com/gh_mirrors/ne/nexus