ts-rest框架中请求验证错误的上下文增强处理

在构建API服务时，请求参数的验证是保证接口健壮性的重要环节。ts-rest作为一款现代化的TypeScript API框架，提供了完善的请求验证机制。本文将深入探讨如何增强请求验证错误的上下文信息，帮助开发者更精准地定位问题。

问题背景

当API请求参数验证失败时，传统的错误响应往往只包含路径信息，例如：

{
  "issues": [{"path": ["filters"], ...}]
}

这种格式存在一个明显缺陷：开发者无法直接判断错误参数来自请求的哪个部分（路径参数、查询参数、请求体还是请求头）。这给问题排查带来了不必要的困扰。

解决方案

ts-rest框架已经内置了完善的错误处理机制。通过自定义requestValidationErrorHandler，我们可以为错误响应添加上下文信息：

createExpressEndpoints(contract, mainRouter, app, {
  requestValidationErrorHandler: (err, req, res, _next) => {
    return res.status(400).json({
      context: (
        err.body ? "body" :
        err.pathParams ? "pathParams" :
        err.query ? "query" :
        err.headers ? "headers" : "unknown"
      ),
      issues: err.body?.issues || err.pathParams?.issues || 
              err.query?.issues || err.headers?.issues,
    })
  },
})

这段代码实现了以下功能：

1. 自动检测错误来源（请求体/路径参数/查询参数/请求头）
2. 在响应中添加明确的context字段
3. 保留原始的错误详情issues

实现原理

ts-rest的验证错误对象包含多个可选属性，每个对应不同的请求部分：

• body: 请求体验证错误
• pathParams: 路径参数验证错误
• query: 查询参数验证错误
• headers: 请求头验证错误

通过检查这些属性的存在性，我们可以准确判断错误来源。这种设计既保持了灵活性，又提供了足够的类型安全。

最佳实践

1. 统一错误格式：建议在整个项目中保持一致的错误响应格式
2. 详细日志记录：在服务端记录完整的错误信息，便于排查问题
3. 客户端处理：前端可以根据context字段展示更有针对性的错误提示
4. 类型安全：利用TypeScript类型守卫确保错误处理的类型安全

总结

ts-rest框架通过灵活的错误处理机制，使开发者能够轻松增强请求验证错误的上下文信息。这种设计不仅提升了开发体验，也为API消费者提供了更友好的错误反馈。通过合理利用这些特性，可以构建出更健壮、更易维护的API服务。