H3框架中createError方法的正确使用与错误处理实践

核心问题解析

在H3框架的开发实践中，createError方法的使用方式经常让开发者感到困惑。主要存在两个典型问题场景：

1. 参数类型不明确：开发者不确定应该传递字符串还是对象作为参数
2. 服务端错误传递：不清楚如何将服务端抛出的错误数据正确传递到客户端

createError方法深度解析

方法签名与参数

createError是H3框架提供的错误创建工具，其核心功能是生成标准化的HTTP错误对象。它支持两种调用方式：

1. 字符串形式：直接传递错误消息

createError("资源未找到")

2. 对象形式：传递包含详细错误信息的配置对象

createError({
  statusCode: 404,
  statusMessage: "Not Found",
  data: {
    customField: "额外错误信息"
  }
})

最佳实践建议

1. 简单错误场景：当只需要基础错误信息时，使用字符串形式更简洁
2. 复杂错误场景：需要附加状态码、自定义数据时，必须使用对象形式
3. 服务端到客户端：要传递结构化错误数据，必须使用对象形式的data属性

服务端错误处理完整流程

服务端抛出错误

在路由处理器中，可以这样构造包含额外数据的错误：

export default defineEventHandler(() => {
  throw createError({
    statusCode: 400,
    message: "无效请求",
    data: {
      validationErrors: {
        username: "必须大于6个字符",
        password: "必须包含特殊字符"
      }
    }
  })
})

客户端错误捕获

客户端可以通过try-catch捕获并处理这些结构化错误：

try {
  const data = await $fetch('/api/endpoint')
} catch (error) {
  if (error.data?.validationErrors) {
    // 处理验证错误
    console.error(error.data.validationErrors)
  }
  // 访问基础错误信息
  console.error(error.statusMessage)
}

常见误区与解决方案

1. 错误数据丢失：直接抛出字符串错误会导致data等附加信息无法传递

   • 解决方案：始终对需要传递额外数据的错误使用对象形式

2. 状态码混淆：忘记设置statusCode会导致默认500错误

   • 解决方案：明确指定符合语义的HTTP状态码

3. 类型推断问题：TypeScript环境下可能出现类型提示不全

   • 解决方案：扩展Error类型定义或使用H3提供的类型工具

高级应用场景

自定义错误类型

可以通过扩展创建符合业务需求的特定错误类：

class BusinessError extends Error {
  constructor(message, businessCode) {
    super(message)
    this.businessCode = businessCode
  }
}

// 使用示例
throw createError({
  statusCode: 400,
  message: "业务错误",
  data: new BusinessError("余额不足", "ERR_INSUFFICIENT_BALANCE")
})

错误格式化中间件

创建统一的错误处理中间件确保错误响应一致性：

export default defineEventHandler(async (event) => {
  try {
    return await handleEvent(event)
  } catch (error) {
    if (process.env.NODE_ENV === 'production') {
      // 生产环境标准化错误
      return createError({
        statusCode: error.statusCode || 500,
        message: "请求处理失败",
        data: { code: error.code }
      })
    }
    // 开发环境返回完整错误
    return createError(error)
  }
})

总结

H3框架的错误处理机制提供了灵活的错误创建和传递能力。理解createError方法的两种使用场景，掌握服务端到客户端的错误数据传递方式，能够显著提升应用的错误处理能力和开发体验。建议在项目中建立统一的错误处理规范，特别是在TypeScript环境下，可以通过类型定义来增强错误处理的类型安全性。