NestJS统一异常处理深度解析:全局过滤器与生产级错误响应设计指南
NestJS统一异常处理深度解析全局过滤器与生产级错误响应设计指南【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-apiNestJS 统一异常处理是构建稳定 REST API 的关键环节。开源项目nestjs-starter-rest-apiNestJS Starter Kit 单体后端模板提供了一套完整的生产级方案一个全局异常过滤器 自定义异常基类 统一错误响应结构帮助新手快速掌握错误处理的正确姿势。本文带你逐层拆解这套设计。 为什么需要统一异常处理没有统一异常处理时每个接口可能返回格式各异的报错有的暴露堆栈、有的直接崩溃、有的缺少状态码。这带来两个问题前端难以解析客户端必须为每种错误格式写不同的判断逻辑线上排障困难没有统一标识一次请求出错后无法在日志中快速定位本项目的做法是用一个全局异常过滤器Global Exception Filter兜住所有错误输出固定格式的错误 JSON。️ 架构一览异常处理涉及哪些文件组件文件职责全局异常过滤器all-exceptions.filter.ts捕获所有异常统一输出错误响应自定义异常基类base-api.exception.ts支持 details 与多语言消息的异常错误响应 DTObase-api-response.dto.ts定义 Swagger 文档中的错误对象结构请求 ID 中间件request-id.middleware.ts为每个请求生成x-request-id请求上下文工具util/index.ts提取请求 IP、用户等上下文信息日志服务logger.service.ts把错误以结构化 JSON 写入日志模块注册shared.module.ts将过滤器注册为全局 APP_FILTER注册点在 shared.module.ts 中通过useClass: AllExceptionsFilter声明NestJS 会将其作为全局 APP_FILTER 生效无需在每个 Controller 上单独添加。 统一错误响应8 个字段缺一不可所有错误响应都遵循 BaseApiErrorObject 定义的结构最终输出如下{ error: { statusCode: 404, message: Article not found, localizedMessage: 記事が見つかりません, errorName: BaseApiException, details: { code: NOT_FOUND }, path: /api/v1/articles/1, requestId: 3f2c8a1e-9d4b-4c6a-8e2f-1a2b3c4d5e6f, timestamp: 2026-08-26T00:53:07.000Z } }这个设计参考了 Google API Design 的错误规范代码中注释有说明几个字段的设计意图值得学习errorName机器可读的错误标识前端可以据此做分支处理requestId与响应头中的x-request-id对应用户反馈报错时可直接检索日志pathtimestamp定位哪个接口、什么时间出错省去翻日志时间范围localizedMessage预留的多语言错误消息目前按请求头语言取值见 all-exceptions.filter.ts 三类异常的分级处理策略过滤器的核心逻辑在 all-exceptions.filter.ts按异常类型分三级处理1️⃣ 业务异常BaseApiException继承自 NestJS 的HttpException额外携带details和localizedMessage适合预期的业务错误如参数校验失败、资源不存在throw new BaseApiException(用户不存在, HttpStatus.NOT_FOUND, { code: USER_NOT_FOUND });2️⃣ 框架异常HttpExceptionNestJS 内置异常如NotFoundException、ValidationPipe抛出的BadRequestException也能被正确提取状态码和响应体。3️⃣ 未知异常Error兜底逻辑任何不属于前两类的异常一律返回 500并默认errorName为InternalException、消息为Internal server error见 all-exceptions.filter.ts。堆栈信息只写入日志绝不返回给客户端。 这是新手最容易忽略的点过滤器必须保证永远能返回一个合法响应而不是让请求直接挂起。 requestId贯穿请求生命周期的追踪线索request-id.middleware.ts 在每个请求进入时检查x-request-id头客户端已传入合法的 UUID → 沿用未传入或非法 → 生成新的 UUID该 ID 会写回响应头同时被异常过滤器读取并放进错误体请求头名定义在 common.ts。配合 createRequestContext 提取的 IP、URL、用户信息错误日志形如[warn] 用户不存在 { error: {...}, stack: ..., ctx: { requestID, url, ip, user } }一次线上报错拿着requestId就能在日志中精确还原整个请求。️ 生产环境细节错误信息脱敏过滤器中有一个关键的安全设计all-exceptions.filter.ts开发环境500 错误返回原始错误消息方便本地调试生产环境500 错误的message一律替换为Internal server error防止内部报错如数据库连接串、文件路径泄露给攻击者原始信息则完整保留在服务端日志中通过 AppLogger 的warn方法输出。 快速上手三步接入同款方案创建全局过滤器实现ExceptionFilter接口用Catch()捕获所有异常参照 all-exceptions.filter.ts定义自定义异常继承HttpException并扩展details字段参照 base-api.exception.ts注册并测试在共享模块中注册APP_FILTER并用单元测试覆盖三类异常场景参考 all-exceptions.filter.spec.ts项目入口 main.ts 中还配合了ValidationPipe自动转换 白名单校验让参数类错误在进 Controller 前就以标准 400 形式抛出再被全局过滤器统一格式化。 总结nestjs-starter-rest-api 的异常处理设计可以归纳为四句口诀一个过滤器兜底——所有异常统一出口一个响应结构——字段固定机器友好一个 requestId 串联——请求、响应、日志三方对齐一套环境开关——开发看细节生产保安全这套模式不依赖任何第三方错误处理库纯 NestJS 原生能力实现非常适合作为生产级 REST API 项目的异常处理模板。【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

Token预算感知:让LLM推理可控且成本可预期

Token预算感知:让LLM推理可控且成本可预期

不知道你有没有遇到过这种场景:上线一个带“推理”能力的 LLM 应用,用户问了一个稍微复杂点的问题,模型开始“思考”,然后账号余额在几分钟内掉了一大截。更头疼的是,它思考了一大段之后,给出来的答案还是被…

2026/11/22 10:41:42 阅读更多 →
大模型部署宝典:参数量选择与本地工具详解,适合小白与程序员

大模型部署宝典:参数量选择与本地工具详解,适合小白与程序员

应该部署多少参数量的模型 32B 以下的模型不具备生产应用价值,不值得用于训练。 模型的回答要么像个傻子(1.5B),要么像个有点智慧的傻子(7B),要么就是看上去是对的,但反复核查后实际…

2026/11/18 22:45:28 阅读更多 →
多模态大模型原来这么简单?多模态大模型(MM-LLMs)核心架构详解:从理论到实践,看完我简直醍醐灌顶!

多模态大模型原来这么简单?多模态大模型(MM-LLMs)核心架构详解:从理论到实践,看完我简直醍醐灌顶!

前言 多模态大模型作为当下科研的热点之一,其应用和发展正受到广泛关注。多模态大模型是指能够处理和理解来自多种模式或类型数据的模型,这些模式包括文本、图像、声音等。 通过整合这些不同类型的数据,模型能够提供更为丰富和精确的信息处理…

2026/11/12 17:02:43 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/21 23:27:35 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/21 23:27:35 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/21 23:27:35 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/21 23:27:35 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/21 23:27:36 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/21 23:27:37 阅读更多 →

日新闻

周新闻

月新闻