Valibot中custom验证器的正确使用方式解析

Valibot作为一款类型安全的JavaScript/TypeScript数据验证库，其设计理念与常见验证库有所不同。本文将深入分析Valibot中custom验证器的设计原理和使用场景，帮助开发者避免常见误区。

验证器与验证动作的区分

Valibot在设计上严格区分了两种概念：

1. Schema函数：用于定义数据结构的基本验证规则
2. 验证动作：对数据进行实际验证的操作

custom属于Schema函数，而非验证动作。这是许多从其他验证库(如Zod)迁移过来的开发者容易混淆的地方。

custom验证器的本质

custom验证器的主要作用是创建新的验证Schema，而非直接验证数据。当我们需要定义全新的验证规则时，才应该使用custom。

其TypeScript类型签名如下：

function custom<TInput>(action: (value: unknown) => boolean): Schema<TInput>

这个签名表明：

1. 它接收一个验证函数作为参数
2. 返回一个新的Schema类型
3. 验证函数接收unknown类型的值，返回布尔值

管道验证的正确方式

在管道验证(v.pipe)场景中，我们需要的不是创建新Schema，而是对已有数据进行额外验证。这时应该使用check或partialCheck验证动作。

例如，要验证数字大于42的正确做法是：

v.pipe(
  v.number(),
  v.check((value) => value > 42)
);

类型安全设计原理

Valibot强制custom验证函数接收unknown类型参数，这是出于类型安全的考虑：

1. 确保开发者显式处理类型转换
2. 防止在验证前假设数据类型
3. 与TypeScript的严格类型检查保持一致

这种设计虽然增加了少量样板代码，但能有效避免运行时类型错误。

最佳实践建议

1. 仅在需要创建全新验证规则时使用custom
2. 在管道验证中使用check或partialCheck
3. 始终在custom验证函数中先进行类型检查
4. 对于常见验证(如最小值)，优先使用内置验证器

通过理解这些设计原则，开发者可以更高效地使用Valibot构建类型安全的验证逻辑。