Node.js 错误处理最佳实践:只使用内置 Error 对象,用 AppError 构建统一错误体系(nodebestpractices 指南解析)
Node.js 错误处理最佳实践:只使用内置 Error 对象,用 AppError 构建统一错误体系(nodebestpractices 指南解析)
本文基于 nodebestpractices 仓库 Error Handling 章节 的「Use only the built-in Error object」条目展开。JavaScript 语言与生俱来的宽容性、以及 EventEmitter / 回调 / Promise 等多种代码流选项,导致开发者抛错方式千差万别——有人抛字符串,有人自定义五花八门的错误类型。本篇指南要解决的核心问题是:如何统一全代码库与第三方库之间的错误结构,同时完整保留 StackTrace 等关键诊断信息。读完本文,你将掌握内置
Error对象的标准用法、反模式识别,以及「只扩展一次 AppError」的集中化错误设计,并了解它与仓库中中央化错误处理、操作性错误标记等实践的衔接方式。
一、为什么必须只使用内置 Error 对象
在 nodebestpractices 的 README 总纲 中,这一条被列为 2.2 Extend the built-in Error object,属于 Error Handling Practices 的核心条目之一。其「TL;DR」明确指出:
有些库会把错误抛成字符串或某种自定义类型,这会让错误处理逻辑和模块间的互操作性变得复杂。正确的做法是:创建一个继承自内置
Error的应用级错误对象(class),并在 reject、throw、emit 时统一使用它。
使用内置 Error 对象的价值体现在两个层面:
- 统一性(Uniformity):代码内部、以及与第三方库交互时,错误对象的结构保持一致,调用方无需猜测「这次抛回来的是字符串、普通对象还是 Error 实例」。
- 信息保全(Information Preservation):
Error对象在实例化时会自动捕获堆栈跟踪(StackTrace),指出错误发生的精确代码位置,并提供错误的文本描述。Node.js 官方文档确认:「Node.js 中产生的所有错误——包括系统错误与 JavaScript 错误——要么是Error类的实例,要么继承自Error类,并且保证至少提供该类上可用的属性」。这是后面所有错误处理策略(集中处理、日志、监控)的前提。
正如本条目反模式警示的那样:抛出字符串会同时丢失堆栈跟踪信息和其他重要的数据属性,这也是「2.2」条目的 Otherwise 部分强调的「使用自定义类型描述错误可能导致关键错误信息(如 StackTrace)丢失」的直接体现。
二、反模式:抛出字符串(Anti Pattern)
原文档给出的反模式极其简短,但一击致命:
// 抛出字符串会丢失堆栈跟踪信息以及其他重要的数据属性
if (!productToAdd)
throw ('How can I add new product when no value provided?');
这里的核心问题不止是「没有堆栈」。devthought.com 的博客引文(原文档收录)把后果说得更透:
……把字符串而不是 Error 传给调用方,会降低模块间的互操作性。它破坏了可能正在做
instanceof Error检查、或想进一步了解错误详情的 API 之间的约定。Error 对象在现代 JavaScript 引擎中除了保存传给构造函数的 message 之外,还拥有非常有趣的属性……
也就是说,一旦调用方依赖 err instanceof Error、err.name、err.message、err.stack 这些约定,字符串抛错会让整条错误处理链路失守。ESLint 的 no-throw-literal 规则正是为此设计的(详见后文第五节)。
三、正确示范:在三种典型代码流中统一使用 Error
原文档强调:无论错误来自哪种代码流,抛出的都应当是内置 Error 对象。下面三个场景覆盖了 Node.js 应用中最常见的错误源头:
// 场景一:从普通函数抛出(同步或异步皆可)
if (!productToAdd)
throw new Error('How can I add new product when no value provided?');
// 场景二:从 EventEmitter 中「抛出」
const myEmitter = new MyEmitter();
myEmitter.emit('error', new Error('whoops!'));
// 场景三:从 Promise 中「抛出」
const addProduct = async (productToAdd) => {
try {
const existingProduct = await DAL.getProduct(productToAdd.id);
if (existingProduct !== null) {
throw new Error('Product already exists!');
}
} catch (err) {
// 这里拿到的是标准 Error,可安全地读取 err.name / err.message / err.stack
}
}
注意场景二的写法:EventEmitter 的 'error' 事件规范要求发射一个 Error 对象,而不是字符串或普通对象——这直接决定了监听 myEmitter.on('error', ...) 的一方能否依赖 Error 的标准属性。
在 Promise 场景中,throw new Error(...) 会被自动转化为 rejected promise,catch (err) 拿到的 err 一定是标准 Error 实例。这与仓库中 catchunhandledpromiserejection.md 一节的警告互为照应:promise 链中漏掉 .catch 的错误会「静默消失」,因此统一使用 Error 对象、并在 process.on('unhandledRejection', ...) 兜底,是完整的配套方案。
四、更优做法:用 AppError 只扩展一次内置 Error
「统一使用内置 Error」解决了结构问题,但还不够。原文档指出,抛出异常时通常还应该附带额外的上下文属性,例如错误名称(name)和关联的 HTTP 错误码(httpCode)。为了达成这种一致性,可以给 Error 对象附加属性,但务必克制:
一般建议为所有应用级错误只扩展一次内置 Error 对象,即定义一个
AppError,把用于区分不同错误种类的数据作为参数传入。没有必要针对每种错误(DbError、HttpError……)分别扩展一次。
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构造函数,初始化 message 等内置属性;Error.captureStackTrace(this):让堆栈跟踪从AppError构造函数之外的调用点开始捕获,避免堆栈被「错误工厂」污染;AppError.prototype = Object.create(Error.prototype)+ 重置constructor:正确建立原型链,使appError instanceof Error为true,保住前文所说的instanceof约定;- 第四个参数
isOperational:为错误打上「操作性」标记,这是本仓库另一条实践(见下文)的衔接点。
TypeScript 实现
// 从 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)
TypeScript 版额外引入了一行容易被忽略但至关重要的代码:Object.setPrototypeOf(this, new.target.prototype)。由于 Error 是 ES5 内置类,TS 编译目标若低于 ES2015,extends Error 生成的 __extends 会破坏原型链,导致 instanceof Error 判定失败;new.target 保证实例始终使用实际被实例化的子类的原型。这也是 TS 2.2 引入 new.target 支持后推荐的恢复原型链的标准写法。
为什么「只扩展一次」而非「每种错误一个类」
machadogj 的博客引文(原文档收录)把这个问题讲得很实际:
……Error 类的一个问题是不太好扩展。你当然可以继承它去创建 HttpError、DbError 之类的错误类,但那很费时间,而且除非你真的在用类型做事情,否则(相比只为 AppError 扩展一次)没什么额外价值。有时你只是想加个 message、保留内部错误,有时想用参数扩展错误……
Ben Nadel 的引文则从语言特性角度补充:
……我个人不觉得(相比只保留一个错误对象类型)有很多错误对象类型有什么价值——JavaScript 这门语言似乎并不适合基于构造函数的错误捕获。因此,用对象属性来区分错误,远比用构造函数类型来区分容易得多……
结论是一致的:用属性(name、httpCode、isOperational、commonType……)区分错误,而不是用类层次区分。这也让调用方只需处理一种类型,配合 switch 或枚举就能完成分派。
五、工程化保障:用 ESLint 规则杜绝字符串抛错
README 总纲在 2.2 条目中专门补充了工程化约束:
存在一条
no-throw-literalESLint 规则可以严格检查这一点(尽管它有一些限制,在使用 TypeScript 并配置@typescript-eslint/no-throw-literal规则时可以解决)。
也就是说,单纯靠团队纪律不够——把「只抛 Error」写进 lint 规则,让 CI 在提交阶段就拦截 throw 'string'、throw 42、throw { foo: 'bar' } 这类字面量抛错。TypeScript 项目则应使用 @typescript-eslint/no-throw-literal 以获得对类型系统的完整支持。这条实践与仓库中 lintrules.md(Security 章节的 lint 规则条目)精神一致:用自动化规则把最佳实践固化为代码规范。
六、与仓库其他错误处理实践的衔接
「只使用内置 Error 对象」不是孤立的技巧,它是本仓库 Error Handling Practices 这一组 12 条实践的地基。理解它与相邻条目的关系,才能搭建完整的错误处理体系:
-
与「区分操作性错误与程序员错误」衔接:operationalvsprogrammererror.md 中给出的集中化错误工厂,与本文的
AppError同构——通过isOperational(或isCatastrophic)标记错误性质:操作性错误(如外部服务连接失败、非法输入)影响已知、可妥善处理;程序员错误(如读取 undefined、连接池内存泄漏)则应触发优雅重启。README 2.3 条目的 Otherwise 部分说得直白:总是重启会因一个可预测的小错让约 5000 名在线用户掉线;而未知的灾难性问题发生时不重启又可能产生不可预测行为——两者都需要 Error 对象承载isOperational这类元数据才能区分。 -
与「中央化处理错误」衔接:centralizedhandling.md 规定错误不应散落在各中间件中处理,而应由单一
errorHandler对象负责「记日志 → 发监控指标 → 决定是否崩溃」。该流程得以成立的前提,正是所有错误都是结构统一的 Error 对象:handleError可以统一读取err.name、err.isOperational等属性做决策。 -
与「捕获未处理的 Promise 拒绝」衔接:catchunhandledpromiserejection.md 建议订阅
process.on('unhandledRejection', callback)作为兜底;若错误本身是字符串,兜底处理器将无法获得堆栈与上下文,只能得到一段无用的文本。
简单总结这套体系:用 AppError 统一错误的「形态」→ 用 isOperational 标记错误的「性质」→ 用中央处理器统一错误的「流向」→ 用 process 级事件兜住「漏网之鱼」。
七、社区共识:四位作者的补充论证
原文档收录了四段博客引文,从不同角度佐证「只使用内置 Error 对象」的正确性,此处提炼其核心论点:
| 来源 | 核心论点 |
|---|---|
| Ben Nadel(关键词「Node.js error object」第 5 位) | 不认为大量错误对象类型有价值;用对象属性区分错误远比用构造函数类型区分容易 |
| devthought.com(第 6 位) | 字符串不是错误:传递字符串会降低模块间互操作性,破坏 instanceof Error 检查的约定;Error 对象在现代 JS 引擎中有许多有价值的属性 |
| machadogj | 继承 Error 扩展成 HttpError/DbError 费时且价值有限;除非真在使用类型系统,否则集中扩展一次 AppError 足矣 |
| Node.js 官方文档 | Node.js 中所有 JavaScript 与系统错误都继承自(或是 Error 类的实例),保证至少提供 Error 类上的属性;Error 对象捕获实例化位置处的堆栈跟踪,并可提供文本描述 |
结语
在 nodebestpractices 的 Error Handling 章节中,「只使用内置 Error 对象」是第 2.2 条,但它实际承担着整个错误处理体系的「数据规范」职责。落地到自己的项目,只需三步:第一,禁止一切 throw '字符串',用 no-throw-literal(TS 项目加 @typescript-eslint/no-throw-literal)固化为 lint 规则;第二,为全应用定义唯一的 AppError(JS 构造函数模式或 TS class 模式皆可),通过构造参数承载 name、httpCode、isOperational 等区分维度;第三,让所有模块的 throw / emit / reject 一律走 AppError,并交给中央化错误处理器统一消费。至此,错误在代码库中的「形态」彻底收敛,堆栈、上下文、操作性标记得以完整保留,为日志、监控、优雅重启铺平道路。
如需对照英文原文或查看本条目在多语言仓库中的其他版本,可继续阅读 useonlythebuiltinerror.md(英文)及 日文版;完整的 12 条错误处理实践总览见 README 2. Error Handling Practices 一节。