Valibot 中实现可复用的异步表单验证

在 Valibot 表单验证库中，开发者经常会遇到需要复用异步验证逻辑的场景。本文将通过一个实际案例，介绍如何在 Valibot 中优雅地实现可复用的异步验证功能。

问题背景

假设我们有以下两个表单接口：

interface IPostalCodeForm {
    Country: string;
    PostalCode: string;
}

interface IAddressCreateForm extends IPostalCodeForm {
    Name: string;
}

这两个表单都需要对邮政编码进行异步验证，检查该邮政编码在指定国家是否有效。我们希望在多个地方复用这个验证逻辑。

初始解决方案

开发者最初尝试直接在 schema 中内联定义验证逻辑：

const Form = v.pipeAsync(AddressCreateSchema, v.customAsync(async (input: unknown) => {
    // 类型守卫和验证逻辑...
}));

这种方法虽然可行，但存在几个问题：

1. 需要手动编写类型守卫来确保类型安全
2. 验证逻辑无法复用
3. 代码结构不够清晰

改进方案

Valibot 提供了更优雅的方式来实现可复用的验证逻辑。核心思路是使用泛型函数来封装验证逻辑：

function createPostalCodeValidator<T extends IPostalCodeForm>() {
    return v.checkAsync<T>(async (input) => {
        const result = await PostalCodeExistsAsync(input.PostalCode, input.Country);
        if (result !== true) {
            return false; // 验证失败
        }
        return true; // 验证通过
    });
}

使用方式：

const AddressCreateSchema = v.pipeAsync(
    v.object({
        Name: NameSchema,
        Country: CountrySchema,
        PostalCode: PostalCodeSchema
    }),
    createPostalCodeValidator()
);

最佳实践建议

1. 避免使用 customAsync：除非特殊情况，否则优先使用 check 或 checkAsync，它们提供了更好的类型安全性和更简洁的 API。

2. 错误处理：验证失败时返回 false 而不是抛出异常，Valibot 会自动处理错误信息的生成。

3. 类型安全：利用 TypeScript 的泛型来确保验证函数与 schema 的类型匹配。

4. 组合验证：对于复杂的验证逻辑，可以组合多个简单的验证函数。

完整示例

// 定义基础验证函数
function createPostalCodeValidator<T extends IPostalCodeForm>() {
    return v.checkAsync<T>(async (input) => {
        const result = await PostalCodeExistsAsync(input.PostalCode, input.Country);
        return result === true;
    });
}

// 创建具体 schema
const AddressCreateSchema = v.pipeAsync(
    v.object({
        Name: v.string(),
        Country: v.string(),
        PostalCode: v.string()
    }),
    createPostalCodeValidator()
);

// 使用 schema 验证数据
const result = await v.safeParseAsync(AddressCreateSchema, {
    Name: "Test",
    Country: "US",
    PostalCode: "12345"
});

通过这种方式，我们实现了验证逻辑的复用，同时保持了良好的类型安全性和代码可维护性。