Valibot 中如何扩展 Schema 的验证与转换逻辑

Valibot 作为一个类型安全的 schema 验证库，提供了灵活的方式来定义数据结构验证规则。在实际开发中，我们经常需要在已有 schema 基础上添加额外的验证逻辑或转换操作。本文将介绍 Valibot 中实现这一需求的几种方法。

基础 Schema 定义

首先，我们来看一个基础的登录表单 schema 定义示例：

const LoginSchema = v.object({
  email: v.string([v.minLength(1), v.email()]),
  password: v.string([v.minLength(1), v.minLength(8)]),
});

这个 schema 定义了登录表单的两个字段：

• email：必须是非空字符串且符合邮箱格式
• password：必须是非空字符串且长度至少8个字符

使用 intersect 扩展验证

在某些场景下，我们可能需要在这个基础 schema 上添加额外的验证逻辑。例如，在用户注册时，我们不仅要验证邮箱格式，还需要检查邮箱是否已被注册：

const CreateLoginSchema = v.intersect([
  LoginSchema,
  v.object({}),
  [
    checkEmailAvailability,  // 检查邮箱是否可用
    checkPasswordRules      // 检查密码强度规则
  ]
]);

这种方法利用了 intersect 方法将基础 schema 与额外的验证逻辑组合在一起。虽然功能上可以实现需求，但代码结构上存在一些不直观的地方。

使用 pipe 方法改进

Valibot 最新版本引入了 pipe 方法，提供了更优雅的解决方案：

const CreateLoginSchema = v.pipe(
  LoginSchema,
  checkEmailAvailability,
  checkPasswordRules
);

pipe 方法的工作原理类似于管道，将数据从左到右依次通过每个验证或转换函数。这种方式：

1. 代码更清晰直观
2. 保持了验证逻辑的顺序性
3. 更容易添加或移除中间步骤

自定义验证函数示例

让我们看看如何实现 checkEmailAvailability 这样的自定义验证函数：

async function checkEmailAvailability(input: unknown) {
  const { email } = input as { email: string };
  const isAvailable = await isEmailAvailable(email); // 假设这是一个API调用
  
  if (!isAvailable) {
    throw new Error('Email already registered');
  }
  
  return input;
}

这个验证函数可以无缝集成到 pipe 方法中，与其他验证逻辑协同工作。

最佳实践建议

1. 保持基础 schema 简单：只包含最基础的格式验证
2. 业务逻辑单独处理：将业务相关的验证（如邮箱可用性）放在扩展部分
3. 合理使用异步验证：对于需要API调用的验证，确保正确处理异步流程
4. 错误信息友好：提供清晰的错误提示，方便前端展示

通过合理使用 Valibot 的这些特性，我们可以构建出既灵活又易于维护的表单验证逻辑。