JavaScript自定义Error对象：throw new Error的最佳实践

一、原生 Error 的局限与自定义 Error 的价值

JavaScript 原生提供了 Error、TypeError、RangeError、SyntaxError 等内置异常类。在原型机制上，它们继承自 Object.prototype，具备标准属性 name、message 以及非标准但被广泛实现的调用栈字符串 stack。

在小型脚本中，直接抛出原生 Error 已经足够。但在复杂应用或服务端 Node.js 系统中，通用 Error 会暴露出三个显著缺陷：

• 分类辨识困难：所有错误实例的 name 均为 "Error"，调用方若要判断具体错误原因，只能被迫对 err.message 进行字符串匹配或正则表达式嗅探，一旦文案微调，业务逻辑就会失效。
• 上下文元数据丢失：原生错误构造器通常只接收单一文本消息，无法自然携带业务状态码（HTTP Status Code）、内部错误码（Error Code）、校验失败字段或特定请求标识（Trace ID）。
• 因果链断裂：在捕获底层 I/O、数据库或网络异常并转换为上层业务异常时，单纯新建一个 Error 容易把最初诱发问题的底层底层栈信息完全丢弃，增加排障难度。

因此，创建自定义 Error 的本质目的，是在保持与标准 JavaScript 异常机制（支持 try...catch、调用栈生成及序列化）百分之百兼容的前提下，赋予错误面向业务领域的语义、类型安全与结构化上下文。

二、现代 JavaScript 自定义 Error 类的标准实现

在 ES6 标准普及之前，JavaScript 通常通过构造函数配合 Object.create(Error.prototype) 来模拟继承，这种方式需要手动修正原型指针，代码冗长且容易破坏调用栈。在现代标准中，推荐直接使用 class extends Error。

1. 基础应用错误基类（Base Application Error）

在项目架构中，不建议直接散落编写数十个细小且互不相关的错误类。实践中通常先定义一个统一的业务基类，规范公共字段与行为：

/**
 * 业务系统根异常类
 */
class AppError extends Error {
  /**
   * @param {string} message 错误可读描述
   * @param {object} [options] 扩展参数，支持 ES2022 cause 以及业务元数据
   */
  constructor(message, options = {}) {
    // 1. 调用父类构造器；options 支持标准 { cause: originalError }
    super(message, options);

    // 2. 修正 name 为当前构造函数的名称（例如 ValidationError、AuthError）
    this.name = this.constructor.name;

    // 3. 挂载业务字段：HTTP 状态码、业务错误编码、业务详情
    this.statusCode = options.statusCode || 500;
    this.code = options.code || 'INTERNAL_APP_ERROR';
    this.details = options.details || null;

    // 4. 标识该错误是否属于可预期操作性错误（Operational Error）
    this.isOperational = true;

    // 5. 堆栈修剪：若在 V8 环境（Node.js / Chrome）中，从调用栈中移除构造函数自身的帧
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, this.constructor);
    }
  }

  /**
   * 规范序列化方法，解决 JSON.stringify(error) 输出空对象问题
   */
  toJSON() {
    return {
      name: this.name,
      message: this.message,
      code: this.code,
      statusCode: this.statusCode,
      details: this.details,
      stack: process.env.NODE_ENV === 'production' ? undefined : this.stack
    };
  }
}

2. 细分业务错误子类

在 AppError 之上，根据领域边界派生具体的错误类型。各子类具备默认的状态码和简明的入参签名：

// 字段校验异常 (HTTP 400)
class ValidationError extends AppError {
  constructor(message = '请求参数校验失败', details = null, options = {}) {
    super(message, { ...options, statusCode: 400, code: 'VALIDATION_FAILED', details });
  }
}

// 资源未找到异常 (HTTP 404)
class NotFoundError extends AppError {
  constructor(resource = '目标资源', id = '', options = {}) {
    const message = id ? `${resource} (ID: ${id}) 不存在` : `${resource} 不存在`;
    super(message, { ...options, statusCode: 404, code: 'RESOURCE_NOT_FOUND' });
  }
}

// 身份认证异常 (HTTP 401)
class UnauthorizedError extends AppError {
  constructor(message = '尚未登录或凭证无效', options = {}) {
    super(message, { ...options, statusCode: 401, code: 'UNAUTHORIZED' });
  }
}

三、throw new Error 的核心原则与防御性编码

在语法层面上，JavaScript 的 throw 语句允许抛出任意值：字符串、数字、布尔值甚至是未定义的 undefined。但允许并不等于合理，以下是团队协作与生产工程中必须坚守的黄金准则。

1. 绝不直接 throw 字符串或普通对象

有的开发者图省事写出 throw "User not found" 或 throw { code: 404, msg: "Not found" }。这种反模式存在严重副作用：

• 彻底丢失堆栈追踪：字符串或字面量对象不具备堆栈捕获机制，一旦抛出，外层捕获时完全无法获知是在哪一行、哪一路异步调用中产生的错误。
• 破坏调用方契约：外层 catch (err) 通常默认 err 拥有 err.message 和 err.stack。若抛出字符串，err.message 会变成 undefined，导致后续错误处理逻辑发生二次崩溃。

2. 善用 Error.cause 串联错误因果链（ES2022+）

在分层架构中，底层基础设施（如数据库驱动或第三方 HTTP SDK）抛出的原生错误往往过于底层且细节繁杂。正确的做法是：捕获底层错误，包装为业务领域的错误抛出，并通过 cause 将原始错误随行携带。

async function fetchUserProfile(userId) {
  try {
    const response = await databaseClient.query('SELECT * FROM users WHERE id = ?', [userId]);
    if (!response.rows.length) {
      throw new NotFoundError('用户', userId);
    }
    return response.rows[0];
  } catch (err) {
    // 若已经是预期业务错误，无需重复包装，直接向外抛出
    if (err instanceof AppError) {
      throw err;
    }

    // 将底层数据库底层报错（连接超时、SQL异常等）包装为业务级别的系统异常，并附带原始因果
    throw new AppError('获取用户个人资料失败，底层存储引擎响应异常', {
      cause: err,
      code: 'DATABASE_QUERY_ERROR',
      statusCode: 500,
      details: { userId }
    });
  }
}

在支持现代运行时的控制台中，当打印一个带有 cause 的错误时，引擎会自动级联打印出原始错误的完整堆栈，既保护了业务抽象，又保留了底层故障诊断的关键线索。

3. 避免将异常用作控制流

在部分开发实践中，有人习惯使用 try...catch 来替代 if...else，例如解析用户列表时，如果没有匹配项就 throw new Error("NOT_FOUND")，随后在外层捕获并渲染空页面。

这种做法看似省代码，实则存在明显的性能与维护问题：

• 性能开销：每次构造 Error 对象时，JavaScript 引擎都需要暂停执行并向上收集整个调用栈帧（Call Stack Frames），其耗时是普通对象分配与条件分支跳转的数十倍至上百倍。
• 调试干扰：开发环境开启“Pause on caught exceptions”或使用调试器断点时，被滥用的异常会频繁中断调试流程，混淆真正需要关注的程序崩溃。

四、生产级错误捕获、分类识别与分流处理

定义并正确抛出自定义错误之后，消费端（路由处理器、事件监听器、全局中间件）如何识别这些错误，是实现端到端闭环的关键环节。

1. 类型识别：instanceof 与名称守卫

在绝大多数标准单执行上下文中，直接使用 instanceof 是最为推荐的辨识手段：

try {
  await processPayment(orderId, paymentPayload);
} catch (err) {
  if (err instanceof ValidationError) {
    // 客户端入参错误，返回 400 及具体字段提示
    return res.status(err.statusCode).json({
      code: err.code,
      message: err.message,
      fields: err.details
    });
  }

  if (err instanceof UnauthorizedError) {
    // 鉴权失效，重定向或返回 401
    return res.status(err.statusCode).json({ code: err.code, message: err.message });
  }

  // 非预期的系统未知崩溃（Bug、内存溢出或未捕获的第三方抛错）
  logger.fatal('系统发生非预期崩溃:', { error: err, stack: err.stack });
  return res.status(500).json({ code: 'INTERNAL_SERVER_ERROR', message: '服务器内部错误' });
}

2. 集中式全局异常处理中间件（以 Express / Koa 为例）

在现代服务端框架中，应该将各个路由中的具体错误全部传递到全局处理层，保持核心控制器代码的干净纯粹：

// 统一错误处理中间件
function globalErrorHandler(err, req, res, next) {
  // 判断是否属于可预期的业务操作异常
  if (err instanceof AppError || err.isOperational) {
    return res.status(err.statusCode).json({
      success: false,
      error: {
        code: err.code,
        message: err.message,
        details: err.details
      }
    });
  }

  // 针对未知异常进行全量堆栈记录并报警
  logger.error('未处理的未知系统异常:', {
    message: err.message,
    stack: err.stack,
    cause: err.cause,
    url: req.originalUrl,
    method: req.method
  });

  // 生产环境切忌向客户端泄漏代码内部变量或文件路径
  return res.status(500).json({
    success: false,
    error: {
      code: 'INTERNAL_SERVER_ERROR',
      message: '系统繁忙，请稍后重试'
    }
  });
}

五、常见问题与工程避坑清单

1. JSON 序列化得到空对象 {}：

   在 JavaScript 中，原生 Error 对象的 name、message 和 stack 属于不可枚举属性（enumerable: false）。直接调用 JSON.stringify(new Error("msg")) 会返回 "{}"。若需要将错误序列化为 JSON 发送或持久化，务必在自定义 Error 中实现 toJSON() 方法，或者在日志输出时显式挑选需要的字段。

2. 避免无节制地派生过多细碎类：

   很多初学者容易陷入面向对象的设计过度陷阱，例如为“用户密码太短”、“用户邮箱重复”各自编写一个独立的 PasswordTooShortError、EmailDuplicateError。更好的实践是保持高层抽象：按 HTTP 领域或应用边界划分子类（ValidationError），并通过 details 或具体的 code: 'PASSWORD_TOO_SHORT' 来描述细节。

3. 异步代码中不要漏掉 await：

   在包含 try...catch 的 async 函数中，如果直接 return promiseFunction() 而没有加上 await，当 Promise 被 reject 时，该错误会穿透当前的 catch 块，导致局部的自定义捕获与包装逻辑全部失效。