Node.js 错误处理最佳实践:只使用内置 Error 对象并统一扩展为 AppError(nodebestpractices 实战指南)

原创2026-09-30 09:39:431,865 阅读
文章标签:文档教程后端

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 对象。

这种混乱会带来两个直接后果:

  1. 代码库内部不一致:调用方无法预判"下一个抛出来的到底是个什么形态的东西",错误处理逻辑被迫针对每种形态单独分支;
  2. 与第三方库互操作受损:许多库和 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 基类,把需要区分不同错误种类的数据作为构造参数传入。

这条原则的要点有三:

  1. 只扩展一次:不要为每种错误场景都建一个子类(如 DbError、HttpError),而是只建一个 AppError 覆盖所有应用级错误;
  2. 用参数区分错误:通过 name、httpCode、isOperational 等属性值来区分不同错误,而不是通过不同的类来区分;
  3. 附带上下文属性:抛出异常时,通常建议填充额外的上下文属性,例如错误名称(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 规则可以解决)。

这句话点出了两个可以立即落地的工程动作:

  1. 用 ESLint 规则卡住反模式:启用 no-throw-literal(TS 项目同时启用 @typescript-eslint/no-throw-literal),在 CI/本地 lint 阶段直接拦截 throw 'string' 这类写法;
  2. 给错误打上"是否灾难性"标记: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 项目时,可以按以下清单执行:

  1. 全面禁止 throw 字符串/普通对象,启用 no-throw-literal(TS 项目加 @typescript-eslint/no-throw-literal)从 lint 层面拦截;
  2. 只创建一个 AppError 基类(按上文 JS 或 TS 实现),在所有 throw、reject、emit('error') 场景统一使用;
  3. 用构造参数承载区分信息:name 表示错误分类、httpCode 关联 HTTP 状态、isOperational 标记是否可预期,不要在每类错误上都新建子类;
  4. 配合集中错误处理:让 AppError 流经 centralizedhandling.md 描述的中央处理器,统一完成日志、监控与崩溃决策;
  5. 在进程级兜底:参照 shuttingtheprocess.md 与 catchunhandledpromiserejection.md,用 isOperational/isTrustedError 决定 process.exit(1) 还是继续运行。

一句话总结:在 Node.js 里,错误形态的统一是错误处理体系的第一块基石——只用内置 Error,只为应用级错误扩展一次 AppError,用属性而非类层级去区分错误,你的日志、监控、进程管理和第三方互操作都会因此变得可预期、可维护。

登录后查看全文
nodebestpractices