JavaScript错误处理实例：try-catch最佳实践与自定义异常

一、JavaScript 错误体系与 try-catch 运行模型

JavaScript 的异常机制建立在原型对象 Error 基础之上。当运行时发生非预期错误（如解引用空指针、类型不匹配），或者开发者主动调用 throw 语句时，异常对象便会沿调用栈逐级向上冒泡，直到被最近的 try-catch 结构拦截。若直至栈顶仍未被拦截，运行时便会将此错误抛出至宿主环境，在浏览器中触发页面报错，在 Node.js 中甚至导致进程崩溃退出。

1.1 标准 Error 对象的构成与 ES2022 cause 链

一个规范的 JavaScript Error 实例通常包含四个关键要素：

• name：错误的分类名称，默认为 "Error"，内置派生类包括 TypeError、RangeError、SyntaxError 等；
• message：针对该异常的人类可读描述，用于开发调试与日志排查；
• stack：当前调用栈的追踪快照（非 ECMAScript 核心标准但被所有现代浏览器及 Node.js 广泛支持）；
• cause（ECMAScript 2022+）：指示导致当前错误发生的底层原始错误，避免了过去重打包异常时丢失根因调用栈的历史顽疾。

1.2 try-catch-finally 块的执行生命周期

try-catch-finally 并不是单纯的代码包裹外壳，它具有严密的控制流语义：

1. try 作用域：放置可能发生失败的操作。一旦发生错误，try 块内后续所有代码立即被跳过；
2. catch 作用域：仅在 try 块内抛出异常时激活，负责接收错误实例。在此处必须完成“诊断”与“分流”；
3. finally 作用域：无论 try 块正常结束还是由 catch 捕获、亦或是重新抛出异常，finally 块中的逻辑无条件必定执行，是清理物理连接、释放锁、复位加载状态的唯一安全位置。

// 错误示范：catch 永远无法捕获该异常
function brokenFetch() {
  try {
    fetchRemoteData(); // 返回 Promise 但未加 await！
  } catch (err) {
    console.error("永远不会执行到这里", err);
  }
}

// 正确示范：使用 async/await 确保异步异常回到上下文栈
async function correctFetch() {
  try {
    const result = await fetchRemoteData();
    return result;
  } catch (err) {
    console.error("成功拦截异步异常:", err.message);
  }
}

二、try-catch 核心准则与典型反模式

在日常业务研发中，try-catch 的滥用通常表现在两个极端：要么放任不管导致应用白屏崩溃，要么盲目地给大段业务代码套上“保护罩”，导致所有细粒度错误被无差别压制。

2.1 准则一：最小受控范围（Scoped Try Block）

try 代码块应该像外科手术刀一样精确，只包裹真正具备失败风险的不稳定操作（例如：网络请求、非可信 JSON 反序列化、文件 I/O、复杂的 DOM 访问）。

如果将十几个函数的整体流程全部套在一个巨大 try 块中，那么当内部发生一个简单的拼写错误（如 TypeError: Cannot read properties of undefined）时，它会被当成网络超时或业务故障一同吞下，使问题诊断成本成倍增加。

2.2 准则二：严禁静默吞噬（No Silent Swallowing）

将 catch 块留空或仅仅打印一行无用的 console.log(e) 就假装一切正常，被称为“静默吞噬”。静默吞噬会让调用方误以为底层执行成功，并在损坏的数据上下文上继续往下计算，最终在离故障源头极远的地方引发连锁崩溃。

2.3 准则三：精准识别与未预料异常重抛（Selective Rethrowing）

任何一层代码都只能处理它有能力并且有明确预案的错误。对于那些未曾预料的系统级故障（如内存溢出、核心环境变量缺失、未知网络断开），必须立即 throw err 向上重新抛出，让上层网关或全局监控接管。

async function loadUserProfile(userId) {
  try {
    return await requestUserData(userId);
  } catch (err) {
    // 仅捕获并处理预期的 404 业务缺失状态
    if (err instanceof UserNotFoundError) {
      return getDefaultGuestProfile();
    }
    // 未知异常（如网络断开、服务端 500、代码 Bug）必须向上重抛
    throw err;
  }
}

三、基于 ES6 规范构建自定义异常体系

使用原生的 throw new Error("用户未登录") 或抛出普通字符串 throw "error" 存在严重缺陷：调用方无法通过 instanceof 进行类型分发，无法获得结构化的错误状态码，也无法携带字段校验详情。

在生产项目中，应当建立结构严谨的自定义异常继承链。

3.1 编写高兼容性领域基类 AppError

继承原生 Error 时，需注意三个关键细节：

1. 调用 super(message, options)，并将 options?.cause 原样传递给原生构造函数；
2. 将实例的 name 属性明确覆盖为当前类名；
3. 调用 Error.captureStackTrace（如果当前环境支持），从而把构造函数本身从堆栈跟踪中剥离，保持调用栈的整洁与准确。

/**
 * 全局业务异常基类
 */
class AppError extends Error {
  constructor(message, options = {}) {
    // 调用父类构造器，原生支持 ES2022 options.cause
    super(message, { cause: options.cause });

    this.name = this.constructor.name;
    this.code = options.code || "INTERNAL_ERROR";
    this.statusCode = options.statusCode || 500;
    this.isOperational = options.isOperational ?? true; // 区分可预测业务错误与未捕获Bug
    this.timestamp = Date.now();

    if (typeof Error.captureStackTrace === "function") {
      Error.captureStackTrace(this, this.constructor);
    }
  }

  /**
   * 序列化为适合日志或网络传输的 JSON 结构
   */
  toJSON() {
    return {
      name: this.name,
      code: this.code,
      message: this.message,
      statusCode: this.statusCode,
      timestamp: this.timestamp,
      cause: this.cause ? String(this.cause) : undefined
    };
  }
}

3.2 派生具体业务异常类

在基类基础上，可以根据系统场景派生出输入校验异常 ValidationError、认证鉴权异常 AuthenticationError 以及外部服务异常 ExternalServiceError：

/**
 * 表单或入参校验异常 (HTTP 400)
 */
class ValidationError extends AppError {
  constructor(message = "输入参数校验失败", details = [], options = {}) {
    super(message, {
      code: options.code || "VALIDATION_FAILED",
      statusCode: 400,
      cause: options.cause
    });
    this.details = details; // 存储具体失败的字段与规则，如 [{ field: "email", rule: "invalid" }]
  }

  toJSON() {
    return {
      ...super.toJSON(),
      details: this.details
    };
  }
}

/**
 * 远程服务或下游接口故障异常 (HTTP 502)
 */
class ExternalServiceError extends AppError {
  constructor(serviceName, message, options = {}) {
    super(`[${serviceName}] 依赖服务响应异常: ${message}`, {
      code: options.code || "EXTERNAL_DEPENDENCY_ERROR",
      statusCode: 502,
      cause: options.cause
    });
    this.serviceName = serviceName;
    this.retryable = Boolean(options.retryable);
  }
}

四、完整实战案例：可复用的数据校验与 API 服务

下面通过一个完整的注册业务场景，演示从底层校验、中间业务抛出、到上层网关或控制器统一捕获格式化响应的完整运转链条。代码可直接在支持 ES2022+ 的环境（如 Node.js 16+ 或现代浏览器控制台）中运行验证。

// ==========================================
// 1. 业务领域服务层 (Domain Service)
// ==========================================
function validateRegistrationForm(formData) {
  const violations = [];

  if (!formData.email || !formData.email.includes("@")) {
    violations.push({ field: "email", message: "邮箱地址格式不合法" });
  }
  if (!formData.password || formData.password.length < 8) {
    violations.push({ field: "password", message: "密码长度不得少于8位字符" });
  }

  // 校验不通过，直接抛出强类型 ValidationError
  if (violations.length > 0) {
    throw new ValidationError("注册表单校验不通过", violations);
  }

  return true;
}

async function callPaymentGateway(userId, amount) {
  try {
    // 模拟底层网络调用失败抛出的原生 TypeError 或 NetworkError
    throw new TypeError("Failed to fetch: Connection reset by peer");
  } catch (rawErr) {
    // 使用 Error.cause 保持底层堆栈，同时提升为业务语义明确的异常
    throw new ExternalServiceError("PaymentService", "扣费接口通信超时", {
      cause: rawErr,
      retryable: true
    });
  }
}

// ==========================================
// 2. 控制器与表现层调用入口 (Controller)
// ==========================================
async function handleRegisterRequest(payload) {
  let auditLogCreated = false;

  try {
    console.log("--- 开始执行注册流程 ---");
    
    // 步骤 1：参数校验
    validateRegistrationForm(payload);

    // 步骤 2：调用外部系统
    await callPaymentGateway("user_8821", 99.0);

    auditLogCreated = true;
    return { success: true, message: "注册成功" };

  } catch (err) {
    // 模式分流：根据错误类型做不同维度的响应控制
    if (err instanceof ValidationError) {
      // 客户端参数错误：返回 400，并提供结构化字段指引
      return {
        success: false,
        status: err.statusCode,
        error: {
          code: err.code,
          message: err.message,
          violations: err.details
        }
      };
    }

    if (err instanceof ExternalServiceError) {
      // 依赖外部接口故障：打印告警日志，并提示可重试状态
      console.warn(`[告警] 第三方服务故障，原始根因: ${err.cause?.message}`);
      return {
        success: false,
        status: err.statusCode,
        error: {
          code: err.code,
          message: "外部支付系统暂不可用，请稍后重试",
          retryable: err.retryable
        }
      };
    }

    // 未知严重异常：记录完整堆栈，对外返回统一脱敏提示，并向上重抛供监控捕获
    console.error("[严重未捕获异常]", err);
    throw err;

  } finally {
    // 无论成功与否，必须执行的上下文清理工作
    console.log(`[清理日志] 流程终止，审计日志标记状态: ${auditLogCreated}`);
  }
}

4.1 执行结果验证

分别传入两组测试数据，观察控制台分流输出：

// 测试用例 1：传入不合规的表单数据
const res1 = await handleRegisterRequest({ email: "invalid-email", password: "123" });
console.log("用例1响应:", JSON.stringify(res1, null, 2));

/* 示例输出：
--- 开始执行注册流程 ---
[清理日志] 流程终止，审计日志标记状态: false
用例1响应: {
  "success": false,
  "status": 400,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "注册表单校验不通过",
    "violations": [
      { "field": "email", "message": "邮箱地址格式不合法" },
      { "field": "password", "message": "密码长度不得少于8位字符" }
    ]
  }
}
*/

// 测试用例 2：表单合格，但底层网络服务发生故障
const res2 = await handleRegisterRequest({ email: "user@domain.com", password: "secret123456" });
console.log("用例2响应:", JSON.stringify(res2, null, 2));

/* 示例输出：
--- 开始执行注册流程 ---
[告警] 第三方服务故障，原始根因: Failed to fetch: Connection reset by peer
[清理日志] 流程终止，审计日志标记状态: false
用例2响应: {
  "success": false,
  "status": 502,
  "error": {
    "code": "EXTERNAL_DEPENDENCY_ERROR",
    "message": "外部支付系统暂不可用，请稍后重试",
    "retryable": true
  }
}
*/

五、全链路错误分层治理与全局兜底

在大型 Web 项目中，异常不能仅仅依靠个别函数内部的局部防御，而需要构建一套自底向上的分层治理体系。

5.1 兜底防御：全局未捕获异常监听

即使遵循了完备的 try-catch 规范，仍然可能存在遗漏的未捕获错误。此时宿主环境提供的全局钩子是守护系统稳定性的最后防线。

5.2 生产环境错误处理快速检查清单

• 检查项 1：是否所有异步调用在 try-catch 中都添加了 await？
• 检查项 2：try 块内是否仅包含高危逻辑，而没有将整个流程大一统包裹？
• 检查项 3：所有的 catch 块中是否存在空实现，或者仅有单纯无用的 console.log？
• 检查项 4：在包装并重新抛出异常时，是否通过 Error.cause 保留了原始错误调用栈？
• 检查项 5：项目中是否已配置全局 unhandledrejection 监听器，确保任何漏网之鱼都会触发警报？