Node.js 错误处理最佳实践:只使用内置 Error 对象并统一扩展为 AppError(nodebestpractices 实战指南)
Node.js 错误处理最佳实践:只使用内置 Error 对象并统一扩展为 AppError(nodebestpractices 实战指南)
导读
在 JavaScript 宽松的语言特性与多样的异步流程(EventEmitter、回调、Promise)共同作用下,开发者报告错误的方式千差万别:有人直接 throw 一个字符串,有人为每种场景自定义专属错误类型。本指南以开源项目 nodebestpractices 中《Use only the built-in Error object》一节(波兰语版见 sections/errorhandling/useonlythebuiltinerror.polish.md,英文原版见 sections/errorhandling/useonlythebuiltinerror.md)为核心,讲解为什么应该统一使用 Node.js 内置的 Error 对象、如何仅一次性地将其扩展为应用级 AppError 基类,并给出 JavaScript 与 TypeScript 两种可复制实现。读完你将掌握一套统一、可携带堆栈信息、易于与第三方库互操作的错误建模方案,并理解它与本仓库中"区分操作型/程序员错误""集中处理错误""优雅关停进程"等配套实践如何协同。
一、为什么 JavaScript 环境下错误形态如此混乱
JavaScript 的"宽容天性"(permissive nature)给了开发者极大的自由度,与之相伴的是多样的代码流选择:EventEmitter、回调函数(Callbacks)、Promise、async/await 等。这种自由度直接体现在错误报告方式上——同一份代码库里,可能同时出现以下几种截然不同的错误形态:
- 有人直接抛出字符串;
- 有人定义自己的自定义类型(custom types)来描述错误;
- 有人使用内置
Error对象。
这种混乱会带来两个直接后果:
- 代码库内部不一致:调用方无法预判"下一个抛出来的到底是个什么形态的东西",错误处理逻辑被迫针对每种形态单独分支;
- 与第三方库互操作受损:许多库和 API 会执行
instanceof Error检查,或期望读取错误对象上的标准属性,字符串或自定义类型会直接破坏这类契约。
而统一使用 Node.js 内置的 Error 对象,能够在两个层面带来收益:其一,让你的代码内部以及与第三方库之间保持统一性;其二,保留如 StackTrace(堆栈轨迹) 这样的关键调试信息。Node.js 官方文档对此有明确背书:
"所有由 Node.js 抛出的 JavaScript 与系统错误,要么继承自、要么是标准 JavaScript
Error类的实例,并且保证至少提供该类上可用的属性……错误对象会捕获'堆栈轨迹',详细记录错误被实例化的代码位置,并可能提供错误的文本描述。"
这意味着一件事:以 Error 为唯一事实来源,是所有 Node.js 生态错误的基础契约。
二、正确做法:所有场景统一抛内置 Error 对象
无论是同步函数、异步函数、事件发射器还是 Promise,抛出错误的正确姿势都是同一个:throw new Error('...') 或 emit('error', new Error('...'))。下面这段来自原文档的示例,覆盖了最常见的三种代码流:
// 从典型函数中抛出 Error,无论同步还是异步
if(!productToAdd)
throw new Error('How can I add new product when no value provided?');
// 从 EventEmitter 中"抛出" Error
const myEmitter = new MyEmitter();
myEmitter.emit('error', new Error('whoops!'));
// 从 Promise 中"抛出" Error
const addProduct = async (productToAdd) => {
try {
const existingProduct = await DAL.getProduct(productToAdd.id);
if (existingProduct !== null) {
throw new Error('Product already exists!');
}
} catch (err) {
// ...
}
}
三个场景的共同点是:错误始终是 Error 实例。这样无论错误来自哪条代码路径,处理方拿到的对象都具备 message、name、stack 等标准属性,可以在统一的地方集中消费。
三、反模式:永远不要 throw 一个字符串
最容易犯的错误是把字符串当错误抛出去。原文档明确标注这是 Anti Pattern(反模式):
// 抛字符串会丢失堆栈轨迹信息以及其他重要的数据属性
if(!productToAdd)
throw ('How can I add new product when no value provided?');
字符串没有任何结构:没有堆栈轨迹、没有错误名、没有标准属性,instanceof Error 检查必然失败。正如社区对"字符串不是错误"的批评所言:
"……传递字符串而非错误对象,会降低模块间的互操作性。它会破坏与那些可能执行
instanceof Error检查、或想了解更多错误信息的 API 之间的契约。错误对象在现代 JavaScript 引擎中除了保存传给构造函数的 message 之外,还拥有非常有趣的属性……"
判定标准很简单:凡是无法回答 instanceof Error 的对象,都不应该被当作错误抛出。
四、更进一步:只扩展一次,统一建模为 AppError
仅仅统一使用内置 Error 还不够——原文档给出的进阶建议是:为应用级错误只扩展一次内置 Error 对象,形成统一的 AppError 基类,把需要区分不同错误种类的数据作为构造参数传入。
这条原则的要点有三:
- 只扩展一次:不要为每种错误场景都建一个子类(如
DbError、HttpError),而是只建一个AppError覆盖所有应用级错误; - 用参数区分错误:通过
name、httpCode、isOperational等属性值来区分不同错误,而不是通过不同的类来区分; - 附带上下文属性:抛出异常时,通常建议填充额外的上下文属性,例如错误名称(error name)和关联的 HTTP 错误码。
4.1 JavaScript 实现
// 集中式的、继承自 Node Error 的错误对象
function AppError(name, httpCode, description, isOperational) {
Error.call(this);
Error.captureStackTrace(this);
this.name = name;
//...其他属性在此处赋值
};
AppError.prototype = Object.create(Error.prototype);
AppError.prototype.constructor = AppError;
module.exports.AppError = AppError;
// 客户端抛出异常
if(user == null)
throw new AppError(commonErrors.resourceNotFound, commonHTTPErrors.notFound, 'further explanation', true)
这里有两个值得注意的实现细节:
Error.call(this):在构造函数体内以当前实例为this调用内置Error构造函数,确保实例拥有 Error 的初始内部状态;Error.captureStackTrace(this):在当前实例上捕获堆栈轨迹,使AppError实例能像原生Error一样携带调用栈;- 原型链修复:
AppError.prototype = Object.create(Error.prototype)与constructor还原,是让自定义错误通过instanceof Error检查的关键步骤。
4.2 TypeScript 实现
TypeScript 的 class extends 语法让这件事更简洁、类型更安全:
// 集中式的、继承自 Node Error 的错误对象
export class AppError extends Error {
public readonly name: string;
public readonly httpCode: HttpCode;
public readonly isOperational: boolean;
constructor(name: string, httpCode: HttpCode, description: string, isOperational: boolean) {
super(description);
Object.setPrototypeOf(this, new.target.prototype); // 恢复原型链
this.name = name;
this.httpCode = httpCode;
this.isOperational = isOperational;
Error.captureStackTrace(this);
}
}
// 客户端抛出异常
if(user == null)
throw new AppError(commonErrors.resourceNotFound, commonHTTPErrors.notFound, 'further explanation', true)
两个 TS 特有细节需要理解:
super(description):把人类可读的描述文本交给内置Error,让message属性保持标准语义;Object.setPrototypeOf(this, new.target.prototype):这是 TS 2.2 引入的new.target支持下的惯用写法。由于 ES2015+ 的Error子类在原生环境下原型链可能无法正确还原(instanceof会失真),需要显式地把实例原型指向实际构造函数的prototype。它保证无论你派生出多少层子类,instanceof判定都准确。
参数含义汇总(可直接作为你落地时的属性契约参考):
| 参数 | 类型 | 作用 |
|---|---|---|
name |
string |
错误名称/分类标识,如 resourceNotFound |
httpCode |
HttpCode |
关联的 HTTP 状态码,如 404 notFound |
description |
string |
人类可读的错误描述,最终写入 message |
isOperational |
boolean |
是否为可预期的操作型错误(影响进程是否应崩溃) |
其中 isOperational 正是本仓库另一条实践《区分操作型错误与程序员错误》的核心开关——该文档中的 AppError 同样携带 commonType、description、isOperational 属性,并通过 throw new AppError(errorManagement.commonErrors.InvalidInput, 'Describe here what happened', true) 这样的调用方式抛出,与本节的建模思路一脉相承。
五、AppError 在仓库配套实践中的协同定位
AppError 不是孤立存在的,它是 nodebestpractices 整个错误处理体系的地基。本仓库 README.md 第 2.2 节"Extend the built-in Error object"给出的 TL;DR 是:
有些库会把错误抛成字符串或自定义类型,这复杂化了错误处理逻辑与模块间互操作性。相反,应该创建一个扩展内置 Error 对象的应用错误对象/类,并在 reject、throw 或 emit 错误时统一使用它。应用错误应添加有用的命令式属性,如错误名/错误码和
isCatastrophic。如此,所有错误都具有统一结构并支持更好的错误处理。ESLint 的no-throw-literal规则会严格检查这一点(虽然它有一些局限,使用 TypeScript 并配置@typescript-eslint/no-throw-literal规则可以解决)。
这句话点出了两个可以立即落地的工程动作:
- 用 ESLint 规则卡住反模式:启用
no-throw-literal(TS 项目同时启用@typescript-eslint/no-throw-literal),在 CI/本地 lint 阶段直接拦截throw 'string'这类写法; - 给错误打上"是否灾难性"标记:
isOperational/isCatastrophic属性是后续决策的依据。
围绕 AppError,仓库中的错误处理链路是这样的:
- sections/errorhandling/centralizedhandling.md(集中处理错误):各模块抛出
AppError后,统一交给一个中央错误处理对象,由它负责日志、监控指标、决定是否崩溃。文档给出的典型流程为:某模块抛错 → API 路由捕获 → 传播给错误中间件 → 调用中央错误处理器; - sections/errorhandling/shuttingtheprocess.md(优雅关停进程):展示了如何用
AppError上的标记做"是否崩溃"决策——errorHandler.isTrustedError(error)检查error.isOperational,若非受信错误则process.exit(1),交由 PM2/Forever 等重启工具以干净状态重新拉起。其 TypeScript 版ErrorHandler用error instanceof AppError判断错误是否来自可信源,只有isOperational === true才视为受信; - sections/errorhandling/catchunhandledpromiserejection.md(捕获未处理的 Promise 拒绝):在
process.on('unhandledRejection')与process.on('uncaughtException')中调用errorManagement.handler.handleError(error),再通过isTrustedError决定是否退出——由于所有错误都是AppError实例,这些兜底处理器可以统一断言其属性。
可见,"只使用内置 Error + 单次扩展 AppError"是整个错误处理体系的入口:只有错误形态统一了,集中处理、受信判定、进程决策这些下游机制才有稳定的输入。
六、社区观点佐证
原文档引用了多段社区与官方观点,从不同角度支撑"少建类型、多用属性"的结论:
1. "我不觉得有很多不同类型有什么价值"(Ben Nadel)
"就我个人而言,我看不出拥有很多不同类型错误对象的价值[与只拥有一个相比]——JavaScript 作为一种语言,似乎并不支持基于构造函数的错误捕获。因此,基于对象属性做区分,远比基于构造函数类型做区分容易得多……"
2. "继承 Error 并不会带来太多额外价值"(machadogj)
"……我对 Error 类的一个意见是,它并不那么容易扩展。当然,你可以继承它并创建自己的错误类,如 HttpError、DbError 等。然而那很费时间,而且[与只为 AppError 扩展一次相比]并不会带来太多额外价值,除非你要在类型上做文章。有时候,你只是想加一条消息并保留内部错误;有时候你可能想给错误扩展参数,诸如此类……"
这两段观点与本节的实操结论完全一致:错误之间的差异用属性(name、httpCode、isOperational)表达,而不是用类层级表达。
3. 官方文档:所有错误都继承自 Error
Node.js 官方文档确认了统一错误形态的底层事实:
"……所有由 Node.js 抛出的 JavaScript 与系统错误,要么是标准 JavaScript Error 类的实例,要么继承自它,并且保证至少提供该类上可用的属性……错误对象捕获'堆栈轨迹',详细记录错误被实例化的代码位置,并可能提供错误的文本描述。Node.js 产生的所有错误,包括所有系统错误与 JavaScript 错误,都将是 Error 类的实例或继承自 Error 类……"
七、落地清单
把本节实践落地到你的 Node.js 项目时,可以按以下清单执行:
- 全面禁止
throw字符串/普通对象,启用no-throw-literal(TS 项目加@typescript-eslint/no-throw-literal)从 lint 层面拦截; - 只创建一个
AppError基类(按上文 JS 或 TS 实现),在所有throw、reject、emit('error')场景统一使用; - 用构造参数承载区分信息:
name表示错误分类、httpCode关联 HTTP 状态、isOperational标记是否可预期,不要在每类错误上都新建子类; - 配合集中错误处理:让
AppError流经 centralizedhandling.md 描述的中央处理器,统一完成日志、监控与崩溃决策; - 在进程级兜底:参照 shuttingtheprocess.md 与 catchunhandledpromiserejection.md,用
isOperational/isTrustedError决定process.exit(1)还是继续运行。
一句话总结:在 Node.js 里,错误形态的统一是错误处理体系的第一块基石——只用内置 Error,只为应用级错误扩展一次 AppError,用属性而非类层级去区分错误,你的日志、监控、进程管理和第三方互操作都会因此变得可预期、可维护。