文档教程后端【免费下载链接】nodebestpractices✅ The Node.js best practices list (July 2026)项目地址https://gitcode.com/GitHub_Trending/no/nodebestpractices点击查看免费下载导读在 Node.js 后端应用中错误处理分散在业务模块、路由与中间件各处往往是线上问题隐身的首要原因。本文基于开源仓库 nodebestpractices 错误处理最佳实践第 2.4 条集中处理错误不要在 Express 中间件中处理错误系统讲解集中式错误处理Centralized Error Handling的设计思想、典型错误流转链路、专用错误处理对象的落地实现以及在中间件内直接处理错误这一反模式的危害并结合仓库内 centralizedhandling.chinese.md 等姊妹章节给出可复制、可运行的 JavaScript / TypeScript 代码。读完你将掌握如何让所有入口API 路由、Cron 任务、消息队列消费者、未捕获异常共享同一个错误处理对象如何区分操作型错误与程序型错误并决定是否优雅重启从而让错误可见、可追踪、可决策。为什么必须有一个专用的错误处理对象分散处理的代价错误在雷达下被隐藏仓库文档在 一段解释 中明确指出如果没有一个专用的错误处理对象由于处理不当重要错误在雷达下被隐藏的可能性会更大centralizedhandling.chinese.md。这里的逻辑非常直白Web 请求内抛出的错误、启动阶段抛出的错误、定时任务Cron/Scheduled Jobs抛出的错误如果没有统一出口就会被不同代码片段以不同方式处理甚至被直接吞掉一部分错误被特殊对待一部分错误无人理会最终导致某些类型错误被错误管理mismanaged。英文原版 centralizedhandling.md 补充了关键事实这个单一的错误处理对象负责让错误可见——例如写入格式良好的 logger、通过监控产品如 Prometheus、CloudWatch、DataDog、Sentry触发指标并决定进程是否应该崩溃。也就是说集中式错误处理对象承担了三件核心职责职责说明典型实现可见化Visibility将错误写入格式化日志便于检索定位logger.logError(err)度量/告警Metrics Alerting向监控系统上报指标、向管理员发送邮件fireMonitoringMetric(err)、sendMailToAdminIfCritical决策Decision判断错误是否为可信操作型错误决定是否发送响应或崩溃重启crashIfUntrustedErrorOrSendResponse(err)、determineIfOperationalError大多数 Web 框架提供的只是捕获机制不是处理机制Express、Koa 等框架都提供错误捕获中间件机制但文档特别警告典型的错误是把错误处理代码直接写在这个中间件里。这样做的后果是——你无法把同一套处理逻辑复用到其他场景的错误上比如定时任务Cron jobs抛出的错误消息队列订阅者subscribers处理消息时抛出的错误未被捕获的异常uncaught exceptions单元测试中主动抛出的错误。因此正确分工是错误中间件只负责捕获并转发真正的处理交给集中式错误处理程序。这正是本最佳实践的核心主张也呼应了 README.md 中 2.4 条的 TL;DR日志、崩溃决策、监控指标等错误处理逻辑应封装在一个专用且集中的对象中让所有入口API、Cron 任务、定时任务在错误到来时都调用它。典型错误流从抛出到集中处理的完整链路四个环节各司其职仓库文档给出了一个典型的错误流转链路centralizedhandling.chinese.md一些模块抛出错误 → API 路由器捕获错误 → 传播错误给负责捕获错误的中间件如 Express、Koa→ 集中式错误处理程序被调用 → 中间件被告知该错误是否为不可信错误非操作型错误以便优雅地重新启动应用程序。英文原版 centralizedhandling.md 用一张架构图直观呈现了各参与方与流转方向这也是本篇文章的直接配图依据整个链条可拆解为四步DAL/业务层只负责抛出带有充分说明的错误不做处理API 路由层同时捕获同步与异步错误统一转发给错误中间件next(error)错误中间件只做捕获与转发调用集中式错误处理对象集中式错误处理程序完成日志、指标、决策并依据是否操作型错误决定是继续转发next(err)还是由进程管理工具优雅重启。可运行的代码JavaScript 典型错误流以下代码完整继承自 centralizedhandling.chinese.md同时吸收了英文原版对process级事件的补充centralizedhandling.md// DAL 层在这里我们不处理错误只抛出带说明的错误 DB.addDocument(newCustomer, (error, result) { if (error) throw new Error(Great error explanation comes here, other useful parameters) }); // API 路由代码同时捕获异步和同步错误并转发到中间件 try { customerService.addNew(req.body).then(function (result) { res.status(200).json(result); }).catch((error) { next(error) }); } catch (error) { next(error); } // 错误处理中间件委托集中式错误处理程序处理错误 app.use(function (err, req, res, next) { errorHandler.handleError(err).then((isOperationalError) { if (!isOperationalError) next(err); }); });进程级兜底uncaughtException 与 unhandledRejection英文原版进一步展示了一个容易被中文版忽略的细节集中式错误处理对象不仅服务于 Web 请求还应作为Node 进程级事件的统一出口process.on(uncaughtException, error { errorHandler.handleError(error); }); process.on(unhandledRejection, (reason) { errorHandler.handleError(reason); });这与仓库姊妹章节 catchunhandledpromiserejection.chinese.md 的结论完全一致现代 Node.js/Express 应用大部分代码运行在 Promise 中.then、回调、catch块除非开发者记得加.catch否则这些地方抛出的错误不会被uncaughtException事件处理程序捕获而是直接消失。该章节给出的标准兜底方案是process.on(unhandledRejection, (reason, p) { // 捕获到未处理的 promise rejection把它转成未捕获异常统一处理 throw reason; }); process.on(uncaughtException, (error) { errorManagement.handler.handleError(error); if (!errorManagement.handler.isTrustedError(error)) process.exit(1); });可以看到无论是请求级错误、Promise 拒绝还是未捕获异常最终都汇聚到同一个handleError——这正是集中二字的含义。在专门的对象里处理错误核心实现中文版的职责链版本centralizedhandling.chinese.md 给出的专用对象实现如下module.exports.handler new errorHandler(); function errorHandler() { this.handleError function (err) { return logger.logError(err).then(sendMailToAdminIfCritical).then(saveInOpsQueueIfCritical).then(determineIfOperationalError); } }这段职责链promise chain把错误处理拆成了四个可独立演进的动作logger.logError(err)写入格式化日志保证错误可见sendMailToAdminIfCritical若错误级别达到关键阈值邮件通知管理员saveInOpsQueueIfCritical若为关键错误写入运维队列供后续排障determineIfOperationalError最终判定是否为操作型错误受信任错误返回值供上层如错误中间件决定是否继续转发 / 是否触发重启。英文原版的演进版本JavaScript / TypeScript英文原版 centralizedhandling.md 将上述职责链封装成了更明确的三个动作并增加了responseStream参数使错误处理对象可以自行决定崩溃或向客户端返回错误响应module.exports.handler new errorHandler(); function errorHandler() { this.handleError async (error, responseStream) { await logger.logError(error); await fireMonitoringMetric(error); await crashIfUntrustedErrorOrSendResponse(error, responseStream); }; }TypeScript 版本使用类class表达同一结构便于类型约束与依赖注入class ErrorHandler { public async handleError(error: Error, responseStream: Response): Promisevoid { await logger.logError(error); await fireMonitoringMetric(error); await crashIfUntrustedErrorOrSendResponse(error, responseStream); }; } export const handler new ErrorHandler();两个版本对比可以归纳出集中式处理对象的稳定契约handleError(error, responseStream)必须依次完成记日志 → 打指标 → 做崩溃决策/响应。这一契约在仓库 shuttingtheprocess.chinese.md 中还有更细化的版本——错误处理对象额外暴露isTrustedError(error)方法等价于判断error.isOperational供进程级处理使用function errorHandler() { this.handleError function (error) { return logger.logError(err).then(sendMailToAdminIfCritical).then(saveInOpsQueueIfCritical).then(determineIfOperationalError); } this.isTrustedError function (error) { return error.isOperational; } }反模式在中间件内直接处理错误谁来处理 Cron 任务和测试中的错误仓库文档用一段反模式代码点出最常见的错误centralizedhandling.chinese.md// 中间件直接处理错误那谁将处理 Cron 任务和测试错误呢 app.use(function (err, req, res, next) { logger.logError(err); if (err.severity errors.high) mailer.sendMail(configuration.adminMail, Critical error occured, err); if (!err.isOperational) next(err); });这段代码看似完成了日志 邮件告警 是否继续传播的完整逻辑但它有一个致命问题这段逻辑被死死绑定在 Express 中间件里。当错误不是来自 HTTP 请求比如 Cron 任务失败、单元测试抛错、进程未捕获异常时这段处理代码根本不会被触发于是这部分错误的日志、告警全部缺失。正确与错误的边界在哪里对比正反两版代码可以发现边界非常清晰错误中间件正确做法只调用errorHandler.handleError(err)把决策权交给集中式对象自己不做日志、不发邮件错误中间件反模式直接在中间件里写logger.logError、mailer.sendMail将处理逻辑与请求上下文耦合导致非 Web 场景的错误无人处理。仓库文档的结论原话是在 Express 中间件中处理错误是一种常见但又错误的做法这样做不会覆盖在非 Web 接口中抛出的错误。centralizedhandling.chinese.md与操作型错误 vs 程序型错误的联动判断是否崩溃的依据集中式错误处理对象中反复出现的isOperationalError/error.isOperational/isTrustedError其判定标准来自仓库另一条核心最佳实践区分操作型错误和程序型错误operationalvsprogrammererror.chinese.md操作型错误Operational / 受信任你了解发生了什么及其影响例如因连接问题导致对某 HTTP 服务的查询失败。这类错误记录日志即可无需重启进程程序型错误Programmer / 灾难性你不知道原因、有时连来源都不清楚例如读取未定义的值、DB 连接池内存泄漏。应用可能处于不一致状态除了优雅重启之外几乎没有更安全的做法。错误对象上标记操作型错误的标准做法来自该章节// 将错误标记为可操作 var myError new Error(How can I add new product when no value provided?); myError.isOperational true; // 或者使用集中式错误工厂参见仅使用内置错误对象章节 function appError(commonType, description, isOperational) { Error.call(this); Error.captureStackTrace(this); this.commonType commonType; this.description description; this.isOperational isOperational; }; throw new appError(errorManagement.commonErrors.InvalidInput, Describe here what happened, true);把它放回集中式处理链路中就形成完整的闭环决策// 错误处理中间件委托集中式处理程序返回是否为操作型错误 app.use(function (err, req, res, next) { errorHandler.handleError(err).then((isOperationalError) { if (!isOperationalError) // 程序型错误不可信 next(err); // 交由进程管理工具优雅重启 }); });对应地shuttingtheprocess.chinese.md 给出的进程级决策是收到uncaughtException时调用handleError若isTrustedError为假则process.exit(1)再由 Forever、PM2 等重启工具拉起新进程。两处决策逻辑完全同构印证了集中式处理对象在请求级与进程级是同一套决策引擎。用测试锁定错误流让集中处理可验证集中式错误处理必须可测试否则错误被正确处理无法被信任。仓库 testingerrorflows.chinese.md 提供了两条可落地的测试思路单元级用 Mocha Chai 断言特定错误被抛出如ConnectionErrordescribe(Facebook chat, () { it(Notifies on new chat message, () { var chatService new chatService(); chatService.participants getDisconnectedParticipants(); expect(chatService.sendMessage.bind({ message: Hi })).to.throw(ConnectionError); }); });API 级验证错误时 API 返回正确的 HTTP 错误码it(Creates new Facebook group, function (done) { var invalidGroupInfo {}; httpRequest({ method: POST, uri: facebook.com/api/groups, resolveWithFullResponse: true, body: invalidGroupInfo, json: true }).then((response) { // 如果走到这里说明没有抛出异常 }).catch(function (response) { expect(400).to.equal(response.statusCode); done(); }); });在集中式错误处理的语境下还可以为errorHandler本身编写测试伪造操作型错误与程序型错误分别断言handleError的返回值isOperationalError为真/假从而验证日志、指标、崩溃决策三个动作是否按预期执行。延伸阅读与仓库索引集中式错误处理只是仓库错误处理最佳实践体系中的一环与之强关联的姊妹章节还包括集中处理错误中文版本文主体来源集中处理错误英文原版含 TypeScript 与流程图区分操作型错误和程序型错误isOperational标记的来源依据特殊情况产生时优雅地退出服务isTrustedError与process.exit(1)的进程级决策捕获未处理的 Promise rejectionsunhandledRejection/uncaughtException兜底订阅使用您喜欢的测试框架测试错误流错误流测试示例README 错误处理最佳实践目录2.3、2.4、2.6、2.10 等条目在总目录中的上下文。从 README.md 的表述可以确认本最佳实践的核心主张是日志、崩溃决策、监控指标等错误处理逻辑应封装在专用且集中的对象中所有入口API、Cron 任务、定时任务在错误到来时都调用它否则错误处理逻辑散落各处必然导致代码重复并大概率出现错误被不当处理的隐患。小结一套可直接落地的集中式错误处理清单一个对象建立唯一的errorHandler或ErrorHandler类对外只暴露handleError(error, responseStream)内部依次完成日志、指标、崩溃决策一个中间件Express/Koa 错误中间件只做捕获 转发绝不内嵌处理逻辑一个标记在抛错处统一用isOperational true/false区分操作型与程序型错误两个进程级订阅process.on(uncaughtException)与process.on(unhandledRejection)都汇入handleError程序型错误则process.exit(1)交由 PM2/Forever 等重启一套测试对handleError的返回值与 API 错误码分别做单元与集成断言确保错误流长期不回归。坚持这套结构你的应用无论错误来自 HTTP 请求、定时任务还是进程内部都会走同一条可见、可告警、可决策的流水线——这正是 nodebestpractices 错误处理章节希望每个 Node.js 团队建立的第一道防线。赞分享文档教程后端【免费下载链接】nodebestpractices✅ The Node.js best practices list (July 2026)项目地址https://gitcode.com/GitHub_Trending/no/nodebestpractices点击查看免费下载相关推荐Node.js 集中式错误处理基于 nodebestpractices 设计中央错误处理器而非在中间件中处理错误Node.js 集中式错误处理基于 nodebestpractices 设计中央错误处理器而非在中间件中处理错误 本文是开源项目 nodebestpracti文档教程后端Node.js 最佳实践集中式错误处理——将错误处理从中间件中抽离nodebestpracticesNode.js 最佳实践集中式错误处理——将错误处理从中间件中抽离nodebestpractices 本指南基于 nodebestpractices ht文档教程后端Node.js 集中式错误处理实践将错误处理逻辑从中间件中剥离nodebestpractices 最佳实践解析Node.js 集中式错误处理实践将错误处理逻辑从中间件中剥离nodebestpractices 最佳实践解析 导读 本文基于 nodebestpract文档教程后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考