Valibot 库中实现运行时自定义错误消息的最佳实践

在表单验证和数据校验场景中，开发者经常需要根据运行时数据动态生成错误提示信息。Valibot 作为一款类型安全的 TypeScript 验证库，提供了多种灵活的方式来实现这一需求。

基础方案：函数式错误消息

最简单的动态消息生成方式是通过函数参数传递：

const Schema = v.string((issue) => `预期类型: ${issue.expected}`);

这种方式适用于简单的类型校验场景，但当错误消息需要基于复杂验证逻辑时，就会显得力不从心。

进阶方案：check 与 refine 结合

对于需要基于验证上下文生成消息的情况，Valibot 提供了更强大的组合方案：

const Schema = v.pipe(
  v.string(),
  v.check(
    ([c1, c2, c3]) => c1 !== 'f' || c2 == c3,
    ({ input: [c1, c2, c3] }) =>
      `首字母为"${c1}"时，后续两个字符"${c2}"和"${c3}"必须相同`
  )
);

这种模式将验证逻辑和消息生成紧密耦合，避免了重复代码，同时保持了良好的可读性。

高级方案：rawCheck 完全控制

对于最复杂的验证场景，Valibot 提供了底层的 rawCheck API：

const schema = v.pipe(v.string(), v.rawCheck(({ dataset, addIssue }) => {
  if (dataset.typed) {
    const [c1, c2, c3] = dataset.value
    if (c1 === "f" && c2 !== c3) {
      addIssue({ 
        message: `首字母为"${c1}"时，第二和第三个字符"${c2}"与"${c3}"应当相同`
      })
    }
  }
}))

rawCheck 提供了对验证流程的完全控制，包括：

1. 访问原始输入数据
2. 手动添加验证问题
3. 处理类型化/非类型化数据场景

设计原理与最佳实践

Valibot 采用分层设计理念，从简单到复杂提供了不同层级的 API：

1. 声明式验证：适合简单场景，使用预设错误消息
2. 函数式消息：适合需要简单动态消息的场景
3. check + 消息生成器：适合中等复杂度的条件验证
4. rawCheck：适合需要完全控制验证流程的复杂场景

在实际项目中，建议根据场景复杂度选择合适的方案。对于表单验证等常见场景，check 组合方案通常是最佳选择；而对于需要处理多种边界条件的核心业务验证，则可以考虑使用 rawCheck。

Valibot 的这种设计既保证了简单场景的易用性，又为复杂场景提供了足够的灵活性，是 TypeScript 生态中数据验证的优秀解决方案。