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

在TypeScript生态中，Zod作为一个强大的运行时类型校验库，提供了丰富的模式验证功能。其中discriminatedUnion方法常用于处理带有判别字段的联合类型，但在实际使用中，开发者可能会遇到一个常见问题：当传入无效的判别键值时，错误信息中缺少了关键的"received"字段。

discriminatedUnion的基本用法

discriminatedUnion是Zod提供的一个特殊联合类型构造器，它通过一个明确的判别字段（discriminator）来区分不同的联合成员。典型用法如下：

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

这种模式特别适合处理GraphQL响应等场景，其中__typename字段明确标识了对象的类型。

当前错误处理的局限性

当传入一个无效的判别键值时，例如：

const data = {
  __typename: 'block-3',
};

Zod会返回一个错误对象，其中包含：

• 错误代码invalid_union_discriminator
• 期望的有效选项数组
• 错误路径
• 默认错误消息

但缺少了实际接收到的无效值，这在调试时会造成不便。

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

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. 检查错误代码是否为invalid_union_discriminator
2. 通过ctx.data访问原始输入数据
3. 将实际接收到的值包含在错误消息中
4. 对其他错误类型保持默认处理

实际应用建议

在实际项目中，建议将这种错误处理逻辑封装为可复用的工具函数：

function createDiscriminatedUnionWithVerboseError<T extends string, U extends ZodDiscriminatedUnionOption<T>[]>(
  discriminator: T,
  options: U,
) {
  return z.discriminatedUnion(discriminator, options, {
    errorMap: (error, ctx) => {
      if (error.code === 'invalid_union_discriminator') {
        return {
          message: `无效的判别键值'${ctx.data[discriminator]}'。期望: ${options
            .map(opt => `'${opt.shape[discriminator].value}'`)
            .join(' | ')}`
        };
      }
      return { message: ctx.defaultError };
    },
  });
}

这种封装不仅提高了错误信息的可读性，还能保持代码的DRY原则。

总结

Zod的discriminatedUnion虽然功能强大，但在错误处理细节上仍有优化空间。通过自定义errorMap，开发者可以获得更详细的错误信息，显著提升调试效率。这种模式也体现了Zod的高度可扩展性，开发者可以根据项目需求灵活定制各种校验行为。