深入解析 hapijs/boom：HTTP 错误处理利器

深入解析 hapijs/boom：HTTP 错误处理利器

boom HTTP-friendly error objects 项目地址: https://gitcode.com/gh_mirrors/boo/boom

什么是 hapijs/boom？

hapijs/boom 是一个专门用于生成 HTTP 错误响应的工具库，它提供了一套简洁而强大的 API，帮助开发者快速构建符合 HTTP 规范的错误响应。无论是 4xx 客户端错误还是 5xx 服务器错误，boom 都能轻松应对。

核心特性

1. 标准化的错误对象

boom 创建的每个错误对象都包含以下核心属性：

• isBoom：标识是否为 boom 错误对象
• isServer：标识是否为服务器错误（状态码 ≥500）
• message：错误消息
• output：格式化后的响应内容，包含：
  • statusCode：HTTP 状态码
  • headers：响应头
  • payload：响应体

2. 错误格式化方法

reformat(debug) 方法可以重新构建错误输出：

• 当 debug 为 true 时，保留内部服务器错误的详细信息
• 默认 false，会隐藏敏感信息

基础使用方法

创建 boom 错误

const error = new Boom.Boom('错误消息', {
  statusCode: 400,
  data: { key: 'value' }
});

装饰现有错误

const err = new Error('原始错误');
const boomError = Boom.boomify(err, {
  statusCode: 404,
  message: '前缀消息'
});

检查 boom 错误

Boom.isBoom(error); // true
Boom.isBoom(error, 400); // 检查特定状态码

HTTP 4xx 客户端错误大全

400 Bad Request

Boom.badRequest('无效请求');

401 Unauthorized

// 简单用法
Boom.unauthorized('密码错误');

// 带认证方案
Boom.unauthorized('密码错误', 'Basic', { realm: 'Secure Area' });

403 Forbidden

Boom.forbidden('无权限访问');

404 Not Found

Boom.notFound('资源不存在');

405 Method Not Allowed

Boom.methodNotAllowed('方法不允许', null, ['GET', 'POST']);

429 Too Many Requests

Boom.tooManyRequests('请求过于频繁');

HTTP 5xx 服务器错误大全

500 Internal Server Error

Boom.badImplementation('内部实现错误');

501 Not Implemented

Boom.notImplemented('功能未实现');

503 Service Unavailable

Boom.serverUnavailable('服务不可用');

最佳实践

1. 错误消息：为 4xx 错误提供清晰的错误消息，帮助客户端理解问题
2. 安全考虑：5xx 错误在生产环境中应隐藏具体错误细节
3. 附加数据：使用 data 参数提供额外的错误上下文
4. 自定义响应：通过修改 output 属性定制错误响应

总结

hapijs/boom 通过提供标准化的 HTTP 错误处理机制，大大简化了 Web 开发中的错误处理流程。无论是简单的状态码设置，还是复杂的认证头配置，boom 都能以优雅的方式实现。掌握 boom 的使用，能让你的 API 错误处理更加专业和规范。

boom HTTP-friendly error objects 项目地址: https://gitcode.com/gh_mirrors/boo/boom