Zod项目中discriminatedUnion的无效判别键错误处理优化

在Zod类型校验库中，discriminatedUnion是一个强大的工具，它允许开发者基于一个判别字段（discriminator）来验证不同类型的对象。然而，当遇到无效的判别键时，错误信息中缺少了关键的"received"字段，这给调试带来了不便。

discriminatedUnion的基本用法

discriminatedUnion通常用于处理类似GraphQL接口类型的场景，其中包含一个公共字段（如__typename）来区分不同的类型变体：

const schema = z.discriminatedUnion('__typename', [
  z.object({
    __typename: z.literal('block-1'),
    // 其他block-1特有字段
  }),
  z.object({
    __typename: z.literal('block-2'),
    // 其他block-2特有字段
  }),
]);

当前错误信息的局限性

当传入一个无效的判别键值时，Zod会返回一个错误对象，其中包含：

• 错误代码：invalid_union_discriminator
• 有效选项列表：options
• 错误路径：path
• 默认错误消息

但缺少了实际接收到的无效值，这在调试时会造成不便，特别是当错误来自API响应或数据库查询时。

解决方案：自定义错误映射

Zod提供了强大的错误映射功能，可以通过errorMap选项自定义错误处理：

const schema = z.discriminatedUnion('__typename', [
  // ...类型定义
], {
  errorMap: (error, ctx) => {
    if (error.code === 'invalid_union_discriminator') {
      return {
        message: `无效的判别键: ${ctx.data.__typename}`
      };
    }
    return { message: ctx.defaultError };
  }
});

这种方法不仅解决了原始问题，还提供了以下优势：

1. 更详细的错误信息：包含了实际接收到的无效值
2. 本地化支持：可以轻松实现多语言错误消息
3. 灵活的错误格式：可以根据需要定制错误结构

最佳实践建议

1. 始终包含接收值：在自定义错误处理中，确保包含实际接收到的无效值
2. 保持一致性：在整个项目中采用统一的错误信息格式
3. 考虑日志需求：设计错误信息时考虑后续的日志分析需求
4. 性能考量：复杂的错误处理逻辑可能会影响性能，需在开发和生产环境采用不同策略

通过合理利用Zod的错误映射功能，开发者可以创建更加友好和可调试的类型校验系统，特别是在处理复杂的联合类型时。