Zod项目中动态表单字段验证的实践与思考

在表单验证场景中，我们经常会遇到字段验证逻辑相互依赖的情况。本文将以Zod项目中的一个实际案例为例，探讨如何优雅地处理这种动态表单验证需求。

问题背景

在一个用户注册表单中，name字段的验证逻辑依赖于registerType字段的值。具体表现为：

• 当registerType为"IndividualOrAgent"时，name字段的错误提示应为"个人/代理人姓名不能为空"
• 当registerType为"LegalRepresentative"时，name字段的错误提示应为"法人姓名不能为空"

初始方案分析

开发者最初尝试使用superRefine方法来实现这一需求：

.superRefine((data, ctx) => {
  if (!data.name) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: `${userNameLabelText(data.registerType)}${$t('common.notEmpty')}`,
      path: ['name'],
    })
  }
})

这种方法存在一个关键问题：Zod的验证是按字段顺序执行的，superRefine无法在registerType验证完成前执行，导致无法获取正确的错误提示。

解决方案演进

方案一：使用discriminatedUnion

const testSchema1 = z
  .discriminatedUnion('registerType', [
    z.object({
      registerType: z.literal(RegisterTypeEnum.IndividualOrAgent),
      name: z.string({
        required_error: `${userNameLabelText(RegisterTypeEnum.IndividualOrAgent)} ${$t('common.notEmpty')}`,
      }),
    }),
    z.object({
      registerType: z.literal(RegisterTypeEnum.LegalRepresentative),
      name: z.string({
        required_error: `${userNameLabelText(RegisterTypeEnum.LegalRepresentative)} ${$t('common.notEmpty')}`,
      }),
    }),
  ])

这种方法利用了Zod的discriminatedUnion特性，根据registerType的不同值创建不同的验证规则。优点是可以直接为每种情况定义精确的错误消息，缺点是当依赖字段较多时，组合会变得复杂。

方案二：调整验证顺序

z
  .object({
    registerType: requiredSchema($t('account.register.type.text')),
    name: z.string().optional(),
  })
  .superRefine((data, ctx) => {
    if (!data.name) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: `${userNameLabelText(data.registerType as RegisterType)} ${$t('common.notEmpty')}`,
        path: ['name'],
      })
    }
  })
  .and(
    z.object({
      phone: requiredSchema($t('account.phone.text')).pipe(phoneReExpSchema()),
      password: requiredSchema($t('account.password.new')),
      dbCheckPassword: requiredSchema($t('account.password.dbCheck.normal.text')),
    }),
  )

这种方法通过调整验证顺序，先验证依赖字段(registerType)，再验证被依赖字段(name)，最后验证其他独立字段。这种方式更加灵活，适合复杂表单场景。

最佳实践建议

1. 明确依赖关系：在设计表单验证前，先理清字段间的依赖关系图。

2. 分层验证：

   • 第一层：验证基础字段和决定其他字段行为的控制字段
   • 第二层：验证依赖其他字段的动态字段
   • 第三层：验证独立字段

3. 错误消息处理：

   • 对于动态错误消息，可以使用函数生成
   • 考虑国际化需求，预留消息模板

4. 性能考虑：

   • 避免在验证逻辑中进行复杂计算
   • 对于大型表单，考虑分步验证

总结

在Zod中处理动态表单验证时，关键在于理解验证顺序和字段依赖关系。通过合理组织验证逻辑的结构，我们可以构建出既灵活又强大的表单验证系统。本文介绍的两种方案各有优劣，开发者应根据具体场景选择最适合的方式。