Valibot 中的多值验证：values 和 notValues 的实现与应用

Valibot 是一个强大的 TypeScript 数据验证库，最近在 1.0.0-rc.1 版本中新增了 values 和 notValues 验证器，为开发者提供了更灵活的数据验证能力。本文将深入探讨这一新特性的实现原理和使用场景。

多值验证的需求背景

在实际开发中，我们经常需要验证一个值是否属于一组允许的值（白名单），或者不属于一组禁止的值（黑名单）。虽然 Valibot 之前提供了 .value 和 .notValue 验证器，但它们只能处理单个值的情况，对于多值验证需要开发者自行实现，通常通过以下方式：

1. 使用多个 .value 或 .notValue 验证器组合
2. 编写自定义的 .check 验证逻辑
3. 使用正则表达式 .regex 验证

这些方法虽然可行，但不够直观且代码冗余。新增的 values 和 notValues 验证器正是为了解决这一问题。

新验证器的特性解析

values 验证器

values 验证器用于确保输入值存在于指定的值列表中，相当于白名单验证。其基本用法如下：

v.pipe(
  v.string(),
  v.values(['admin', 'editor', 'viewer'], '角色必须是预定义值之一')
);

notValues 验证器

notValues 验证器则相反，确保输入值不在指定的值列表中，相当于黑名单验证。例如：

v.pipe(
  v.number(),
  v.notValues([0, 8080, 3000], '端口号不能是保留端口')
);

技术实现细节

从实现角度看，这两个验证器底层都是基于数组的 includes 方法进行判断：

• values 验证器：allowedValues.includes(input)
• notValues 验证器：!disallowedValues.includes(input)

这种实现方式简洁高效，同时保持了与 JavaScript 原生方法的一致性。

特殊值的处理

值得注意的是，这两个验证器对特殊值的处理遵循 JavaScript 的严格相等比较（===）规则：

1. NaN 的处理：由于 NaN === NaN 在 JavaScript 中总是返回 false，因此 values 和 notValues 无法直接用于 NaN 的验证。对于这种情况，仍然需要使用专门的 .check 验证器：

v.check(i => !Number.isNaN(i), '必须是一个有效数字')

2. 对象和数组的比较：由于对象和数组是通过引用比较的，这两个验证器不适合用于复杂对象的验证。

实际应用场景

表单输入验证

在处理表单输入时，我们经常需要验证用户输入是否符合预定义的选项：

const roleSchema = v.pipe(
  v.string(),
  v.values(['admin', 'editor', 'viewer'], '无效的角色类型')
);

API 参数验证

在 API 开发中，可以用 notValues 验证器来防止使用保留值：

const portSchema = v.pipe(
  v.number(),
  v.notValues([0, 80, 443], '不能使用系统保留端口')
);

类型安全的替代方案

Valibot 还提供了类型更安全的替代方案，如 picklist 或 literal 与 union 的组合：

const roleSchema = v.union([
  v.literal('admin'),
  v.literal('editor'),
  v.literal('viewer')
]);

这种方法能提供更精确的 TypeScript 类型推断，适合在类型安全要求高的场景使用。

最佳实践建议

1. 对于简单的值列表验证，优先使用 values 和 notValues，它们语法简洁，易于理解
2. 当需要精确的类型推断时，考虑使用 picklist 或 literal 组合
3. 对于 NaN 等特殊值的验证，使用专门的 .check 验证器
4. 在处理用户输入时，考虑将字符串输入转换为目标类型后再验证

总结

Valibot 新增的 values 和 notValues 验证器为开发者提供了更便捷的多值验证方式，简化了常见验证场景的代码编写。理解这些验证器的特性和适用场景，能够帮助开发者构建更健壮、更易维护的数据验证逻辑。在实际项目中，应根据具体需求选择合适的验证策略，平衡代码简洁性和类型安全性。