Zod项目中如何自定义联合类型校验的错误信息

在Zod这个TypeScript校验库中，discriminatedUnion是一个非常有用的功能，它允许开发者基于一个判别字段（discriminator）来区分不同的对象类型。然而，默认的错误信息可能不够详细，本文将深入探讨如何优化这些错误提示。

默认错误信息的局限性

当使用discriminatedUnion校验失败时，Zod默认会返回类似这样的错误：

Invalid discriminator value. Expected 'apple' | 'orange'

这个错误虽然指出了期望的值，但没有显示实际接收到的无效值。对于开发者调试来说，知道具体接收了什么错误值会非常有帮助。

安全考虑与设计哲学

Zod的维护者明确指出，默认错误信息不包含输入数据是出于安全考虑。在Web应用中，错误信息有时会被暴露给终端用户或记录在日志中，包含输入数据可能导致敏感信息泄露。

自定义错误信息的解决方案

方法一：使用errorMap选项

Zod提供了errorMap选项，允许开发者完全控制错误信息的生成方式：

const schema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('apple') }),
  z.object({ type: z.literal('orange') }),
], {
  errorMap: (issue, ctx) => ({
    message: issue.code === 'invalid_union_discriminator' 
      ? `无效的判别值。期望 ${issue.options.map(opt => `'${String(opt)}'`).join(' | ')}，实际得到 '${ctx.data.type}'`
      : ctx.defaultError
  }),
});

方法二：使用zod_utilz工具库

对于更简洁的写法，可以使用zod_utilz库提供的辅助函数：

import { zu } from 'zod_utilz';

const schema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('apple') }),
  z.object({ type: z.literal('orange') }),
], {
  errorMap: zu.makeErrorMap({
    invalid_union_discriminator: ctx => 
      `无效的判别值。期望 'apple' | 'orange'，实际得到 '${ctx.data.type}'`
  }),
});

开发环境与生产环境的差异化处理

虽然文中没有直接讨论，但在实际项目中，开发者可以考虑根据环境变量来切换错误信息的详细程度：

errorMap: process.env.NODE_ENV === 'production'
  ? undefined
  : (issue, ctx) => ({ /* 详细错误信息 */ })

这种做法既保证了生产环境的安全性，又能在开发阶段提供充分的调试信息。

总结

Zod提供了灵活的机制来自定义校验错误信息，特别是对于discriminatedUnion这样的复杂类型。通过合理使用errorMap选项，开发者可以在安全性和调试便利性之间找到平衡点。理解Zod的设计哲学有助于我们更好地利用这个强大的校验库来构建健壮的TypeScript应用。