Zod项目中条件性必填字段验证的实践与思考

在表单验证场景中，我们经常会遇到某些字段的必填性取决于其他字段值的情况。本文将深入探讨如何在使用Zod这一TypeScript优先的模式验证库时，优雅地处理这类条件性必填验证问题。

问题背景

在用户注册表单中，"姓名"字段(name)是否必填取决于"注册类型"(registerType)字段的值。例如：

• 当registerType为"个人/代理"时，name必须填写
• 当registerType为"法人代表"时，name也必须填写

但直接使用superRefine方法会遇到一个关键问题：验证顺序导致依赖字段的验证错误无法及时显示。

初始方案分析

最初的实现尝试了以下方案：

const stepOneSchema = z
  .object({
    registerType: requiredSchema('注册类型'),
    phone: requiredSchema('手机号').pipe(phoneReExpSchema()),
    password: requiredSchema('密码'),
    confirmPassword: requiredSchema('确认密码'),
    name: z.string().optional(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: '密码不匹配',
    path: ['confirmPassword'],
  })
  .superRefine((data, ctx) => {
    if (!data.name) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: `${userNameLabelText(data.registerType)}不能为空`,
        path: ['name'],
      })
    }
  })

这个方案存在验证顺序问题：只有当其他字段都验证通过后，name字段的验证才会执行，导致用户体验不佳。

临时解决方案

第一种临时解决方案采用了discriminatedUnion方法，针对不同registerType创建不同的验证规则：

const testSchema1 = z
  .discriminatedUnion('registerType', [
    z.object({
      registerType: z.literal(RegisterTypeEnum.IndividualOrAgent),
      name: z.string({
        required_error: `${userNameLabelText(RegisterTypeEnum.IndividualOrAgent)}不能为空`,
      }),
    }),
    z.object({
      registerType: z.literal(RegisterTypeEnum.LegalRepresentative),
      name: z.string({
        required_error: `${userNameLabelText(RegisterTypeEnum.LegalRepresentative)}不能为空`,
      }),
    }),
  ])
  .and(
    z.object({
      phone: requiredSchema('手机号').pipe(phoneReExpSchema()),
      password: requiredSchema('密码'),
      dbCheckPassword: requiredSchema('数据库校验密码'),
    }),
  )

这种方法虽然解决了验证顺序问题，但代码结构变得复杂，特别是当需要添加更多公共字段时。

优化后的最终方案

经过实践验证，调整验证链的顺序可以更优雅地解决问题：

z
  .object({
    registerType: requiredSchema('注册类型'),
    name: z.string().optional(),
  })
  .superRefine((data, ctx) => {
    if (!data.name) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: `${userNameLabelText(data.registerType as RegisterType)}不能为空`,
        path: ['name'],
      })
    }
  })
  .and(
    z.object({
      phone: requiredSchema('手机号').pipe(phoneReExpSchema()),
      password: requiredSchema('密码'),
      dbCheckPassword: requiredSchema('数据库校验密码'),
    }),
  )

这个方案的关键点在于：

1. 首先验证registerType和name字段的依赖关系
2. 然后通过and操作符合并其他字段的验证规则
3. 确保了条件性验证优先执行

总结与最佳实践

在Zod中处理条件性验证时，建议遵循以下原则：

1. 验证顺序优先：将依赖其他字段的验证逻辑放在验证链的前面
2. 模块化设计：使用and、or等组合操作符拆分复杂验证逻辑
3. 尽早验证：确保条件性验证在依赖字段验证后立即执行
4. 错误信息友好：动态生成错误提示，增强用户体验

通过合理组织验证逻辑的顺序和结构，可以构建出既健壮又用户友好的表单验证系统。Zod提供的丰富组合操作符和细化控制能力，为这类复杂验证场景提供了强大的支持。