H3框架中自定义错误响应体的高级实践

在现代Web开发中，错误处理是API设计的重要组成部分。unjs/h3作为一款轻量级的HTTP框架，近期在其v2版本中对错误处理机制进行了重要升级，允许开发者更灵活地构建错误响应体结构。

传统错误响应结构的局限性

在传统HTTP错误处理中，开发者通常需要将自定义错误信息嵌套在data字段中。例如一个资源不存在的错误可能呈现为：

{
  "statusCode": 404,
  "message": "Not Found",
  "data": {
    "code": "resource_not_found"
  }
}

这种结构虽然可用，但在某些场景下存在两个明显不足：

1. 错误码需要多级访问（response.data.code）
2. 不符合部分API设计规范要求顶级字段包含业务错误码的需求

H3 v2的解决方案

最新发布的H3 v2版本引入了更灵活的HTTPError构造函数，开发者现在可以通过body参数直接定义响应体的顶级字段：

throw new HTTPError({
  statusCode: 404,
  message: "Not Found",
  body: {
    code: "resource_not_found",
    customField: "additional_info"
  }
})

这将生成结构更扁平化的错误响应：

{
  "statusCode": 404,
  "message": "Not Found",
  "code": "resource_not_found",
  "customField": "additional_info"
}

实际应用场景

1. 标准化错误码体系：可以在顶级直接暴露业务错误码，方便客户端统一处理
2. 调试信息附加：添加traceId等调试信息到顶级字段
3. 多语言支持：附加locale-specific的错误消息
4. 合规性要求：满足某些API规范对响应结构的特殊要求

最佳实践建议

1. 保持一致性：在整个项目中统一错误响应结构
2. 文档化错误码：为自定义的code字段建立完善的文档
3. 适度使用：避免过度扩展顶级字段，保持响应体简洁
4. 类型安全：配合TypeScript定义严格的错误体类型

升级注意事项

从旧版本迁移时需要注意：

1. 原先通过data字段传递的内容现在可以直接放在body中
2. 确保客户端代码能够处理新的响应结构
3. 考虑进行渐进式迁移，初期可以同时支持新旧两种结构

这项改进使得H3在错误处理方面更加灵活，能够适应各种复杂的业务场景需求，同时保持了框架的轻量级特性。开发者现在可以更自由地设计符合自身业务需求的错误响应体系。