Node.js 错误处理最佳实践:只使用内置 Error 对象,用 AppError 构建统一错误体系(nodebestpractices 指南解析)

原创2026-09-30 17:51:551,617 阅读
文章标签:文档教程后端

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 对象的价值体现在两个层面:

  1. 统一性(Uniformity):代码内部、以及与第三方库交互时,错误对象的结构保持一致,调用方无需猜测「这次抛回来的是字符串、普通对象还是 Error 实例」。
  2. 信息保全(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-literal ESLint 规则可以严格检查这一点(尽管它有一些限制,在使用 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 条实践的地基。理解它与相邻条目的关系,才能搭建完整的错误处理体系:

  1. 与「区分操作性错误与程序员错误」衔接:operationalvsprogrammererror.md 中给出的集中化错误工厂,与本文的 AppError 同构——通过 isOperational(或 isCatastrophic)标记错误性质:操作性错误(如外部服务连接失败、非法输入)影响已知、可妥善处理;程序员错误(如读取 undefined、连接池内存泄漏)则应触发优雅重启。README 2.3 条目的 Otherwise 部分说得直白:总是重启会因一个可预测的小错让约 5000 名在线用户掉线;而未知的灾难性问题发生时不重启又可能产生不可预测行为——两者都需要 Error 对象承载 isOperational 这类元数据才能区分。

  2. 与「中央化处理错误」衔接:centralizedhandling.md 规定错误不应散落在各中间件中处理,而应由单一 errorHandler 对象负责「记日志 → 发监控指标 → 决定是否崩溃」。该流程得以成立的前提,正是所有错误都是结构统一的 Error 对象:handleError 可以统一读取 err.name、err.isOperational 等属性做决策。

  3. 与「捕获未处理的 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 一节。

登录后查看全文
nodebestpractices