Valibot 中 getDefaults 方法的行为分析与最佳实践

Valibot 是一个用于数据验证和模式定义的 TypeScript 库。最近社区中关于其 getDefaults 方法的行为引发了一些讨论，特别是关于该方法如何处理嵌套可选对象的默认值问题。

getDefaults 方法的基本行为

getDefaults 是 Valibot 提供的一个实用方法，用于获取模式(Schema)中定义的默认值。在简单场景下，它能够很好地工作：

const SimpleSchema = v.object({
  name: v.optional(v.string(), '默认名字')
});

console.log(v.getDefaults(SimpleSchema)); 
// 输出: { name: '默认名字' }

嵌套可选对象的问题

问题出现在处理嵌套的可选对象时。考虑以下模式定义：

const NestedOptionalSchema = v.optional(
  v.object({
    k1: v.optional(
      v.object({
        k2: v.optional(v.string(), 'value2')
      }),
      {}
    )
  }),
  {}
);

当使用 parse 方法解析 undefined 时，会得到完整的默认值结构：

console.log(v.parse(NestedOptionalSchema, undefined));
// 输出: { k1: { k2: 'value2' } }

但 getDefaults 方法却只能返回最外层的默认值：

console.log(v.getDefaults(NestedOptionalSchema));
// 输出: {}

技术原因分析

这种差异行为源于设计上的考量：

1. 可选对象的歧义性：对于可选对象，无法确定用户期望返回 undefined 还是继续检查内部模式
2. 性能考虑：深度遍历所有可能的嵌套结构可能会影响性能
3. 明确性：保持方法行为的可预测性和明确性

当前解决方案

目前推荐的解决方案是：

1. 避免在可选对象内部再嵌套可选对象，改为使用非可选对象结构
2. 如果需要完全默认值，可以使用 parse 方法并传入 undefined
3. 对于特殊需求，可以复制并修改 getDefaults 的源码实现

// 推荐的模式定义方式
const RecommendedSchema = v.object({
  k1: v.object({
    k2: v.optional(v.string(), 'value2')
  })
});

console.log(v.getDefaults(RecommendedSchema));
// 输出: { k1: { k2: 'value2' } }

未来可能的改进

Valibot 团队正在考虑改进 getDefaults 方法，使其能够：

1. 提供配置选项来控制是否深度解析可选对象
2. 添加一个新的方法来专门处理深度默认值场景
3. 改进文档以更清楚地说明方法的行为边界

最佳实践建议

基于当前实现，建议开发者：

1. 尽量在模式设计时就明确默认值结构
2. 对于复杂嵌套结构，考虑使用辅助函数来获取完整默认值
3. 关注 Valibot 的更新，未来版本可能会提供更灵活的默认值获取方式

理解这些行为差异有助于开发者更有效地使用 Valibot 进行数据验证和默认值管理。