用途:在 NestJS 中实现全局异常过滤器并统一错误响应格式,属于高优先级(P1)规范,核心要求是集中化错误格式化。
主要能力与结构:实现严格类型的错误响应,参考 API 标准中的 ApiErrorResponse,典型结构包含 statusCode、message、error、timestamp、path 字段。错误流分为三层:Service 抛出具体或通用错误(如 EntityNotFoundError);Interceptor 将底层错误映射为 HTTP 异常(如 catchError(err => throw new NotFoundException())),使过滤器专注格式化而非业务逻辑解释;全局过滤器输出最终 JSON 响应。
使用方式:优先抛出内置异常 NotFoundException、ForbiddenException、BadRequestException;仅当领域特定失败需要特定状态码时才扩展 HttpException。平台无关性要求不直接导入 Express/Fastify 的 Request/Response 类型,改用 HttpAdapterHost 访问底层平台响应方法,例如 const { httpAdapter } = this.httpAdapterHost;。日志方面,Logger 构造函数始终传入 MyClass.name 作为上下文;error 级别用于 500 类错误并需堆栈,warn 级别用于 400 类客户端错误。
限制与安全:生产环境(process.env.NODE_ENV === 'production')绝不在 HTTP 响应中暴露堆栈;确保 ApiException 载荷不泄露内部文件路径或原始变量转储。反模式包括:生产环境输出堆栈、在过滤器中使用 Express 类型、在 Service 中直接抛 HttpException。
适用场景:需要统一错误响应格式、跨平台(Express/Fastify)兼容、并控制错误信息泄露风险的 NestJS 后端服务。资料未提供具体安装命令、版本要求或完整代码示例。