TanStack Form 中 Zod 表单验证的类型错误解析

问题背景

在使用 TanStack Form 结合 Zod 进行表单验证时，开发者可能会遇到类型错误问题。典型场景是当开发者尝试在表单级别使用 Zod 验证器时，TypeScript 会抛出类型不匹配的错误。

错误示例分析

让我们先看一个常见的错误实现方式：

const formSchema = z.object({
  firstName: z.string().min(3, "First name must be at least 3 characters"),
  lastName: z.string().min(3, "Last name must be at least 3 characters"),
});

const form = useForm<FormSchema, ZodValidator>({
  validators: {
    onChange({ value }) {  // 这里会报类型错误
      const result = formSchema.safeParse(value)
      return result.success
        ? undefined
        : result.error.errors.map((err) => err.message).join(", ");
    },
  },
  validatorAdapter: zodValidator(),
});

问题根源

这个错误的本质在于类型声明与实现方式的不一致：

1. 通过 <FormSchema, ZodValidator> 泛型参数，我们明确告诉表单要使用 Zod 验证器
2. 但同时又在 validators 中手动实现了一个验证函数
3. 表单期望的是一个 Zod 模式（Zod schema），而我们却提供了一个自定义验证函数

正确解决方案

TanStack Form 与 Zod 的集成实际上更加简洁优雅。正确的做法是：

const form = useForm({
  defaultValues: {
    firstName: "",
    lastName: "",
  },
  onSubmit: async ({ value }) => {
    console.log(value);
  },
  validators: {
    onChange: formSchema,  // 直接使用 Zod schema
  },
  validatorAdapter: zodValidator(),
});

关键改进点

1. 简化类型声明：移除不必要的泛型参数，让 TypeScript 自动推断类型
2. 直接使用 Zod schema：将整个表单验证逻辑交给 Zod 处理
3. 保持一致性：确保验证器类型与适配器类型匹配

深入理解

这种设计体现了 TanStack Form 的一个重要理念：当使用验证器适配器时，应该充分利用适配器提供的验证能力，而不是混合使用不同的验证方式。

Zod 适配器已经为我们处理了：

• 类型安全验证
• 错误消息提取
• 验证结果转换

手动实现的验证函数不仅冗余，还可能破坏类型系统的完整性。

最佳实践建议

1. 优先使用 Zod schema 进行表单级验证
2. 只有在需要特殊验证逻辑时才考虑自定义验证函数
3. 当使用 Zod 适配器时，尽量保持验证方式的一致性
4. 利用 TypeScript 的类型推断能力，减少不必要的类型声明

通过这种方式，我们既能享受 Zod 强大的验证能力，又能保持代码的简洁性和类型安全性。