Valibot 中如何优雅地扩展包含可选属性的 Schema

理解 Schema 扩展的基本概念

在 Valibot 这个强大的 TypeScript 模式验证库中，Schema 扩展是一个常见需求。开发者经常需要在现有 Schema 的基础上添加额外的验证规则，同时保留原有的类型定义和可选性特性。

基础 Schema 示例

让我们从一个基础 Schema 开始，它包含一个可为 null 或 undefined 的数字属性：

const BaseSchema = v.object({
  foo: v.nullish(v.number())
});

这个 Schema 表示 foo 可以是一个数字，也可以是 null 或 undefined。

扩展 Schema 的挑战

当我们想要扩展这个 Schema，为 foo 添加额外的验证条件（例如必须是整数）时，会遇到几个技术难点：

1. 类型系统会正确地提示 foo 可能是 undefined
2. 直接添加验证会破坏原有的可选性
3. 需要保持 nullish 值的处理逻辑

解决方案一：使用 unwrap 方法

第一种解决方案利用了 Valibot 的 unwrap 方法，它可以提取出基础验证器：

const OtherSchema1 = v.object({
  foo: v.nullish(v.pipe(v.unwrap(BaseSchema.entries.foo), v.integer()))
});

这种方法明确地重新包装了 nullish 处理，确保可选性被保留，同时添加了整数验证。

解决方案二：自定义检查函数

第二种方案使用自定义检查函数，更灵活地处理验证逻辑：

const OtherSchema2 = v.object({
  foo: v.pipe(
    BaseSchema.entries.foo,
    v.check((input) => input === null || Number.isInteger(input))
  )
});

这种方法的优势在于可以精确控制验证逻辑，同时保持原有的 Schema 结构。

解决方案三：在对象级别验证

第三种方案直接在对象级别进行验证：

const OtherSchema3 = v.pipe(
  BaseSchema,
  v.check((input) => input.foo === null || Number.isInteger(input.foo))
);

这种方法适用于需要在多个字段间进行协调验证的场景。

最佳实践建议

1. 保持一致性：选择一种扩展方式并在项目中保持一致
2. 类型安全：始终确保 TypeScript 能正确推断扩展后的类型
3. 可读性：复杂的验证逻辑可以考虑提取为单独的函数
4. 性能考虑：对于高频验证的场景，简单检查函数通常性能更好

深入理解原理

Valibot 的 Schema 扩展之所以需要特殊处理，是因为 TypeScript 的类型系统和 Valibot 的运行时验证需要协同工作。nullish 包装器实际上创建了一个联合类型，任何扩展都需要尊重这个类型契约。

当使用 pipe 方法时，验证器会按顺序执行，因此必须确保每个步骤都能处理前一步骤可能产生的所有类型。这就是为什么直接添加 integer 验证会失败 - 它不能处理 undefined 值。

实际应用场景

这种技术在实际开发中非常有用，例如：

• 逐步增强表单验证规则
• 在不同环境中应用不同的验证强度
• 构建可配置的验证系统
• 实现验证规则的模块化组合

总结

Valibot 提供了多种灵活的方式来扩展包含可选属性的 Schema。理解这些技术背后的原理，能够帮助开发者构建更健壮、更易维护的验证系统。无论是使用 unwrap 方法、自定义检查函数，还是对象级验证，关键是要确保不破坏原有的类型契约和可选性特性。