JavaScript异步发送HTTP请求时怎么优雅地处理错误

在 JavaScript 中优雅地处理异步 HTTP 请求错误，核心在于分清网络底层异常与 HTTP 业务状态码异常，并将散落的 try...catch 逻辑收敛为结构一致的错误模型与调用接口。通过统一封装请求层、主动校验 response.ok、引入精确的超时中断以及采用元组解构返回，我们可以让业务代码摆脱层层嵌套的错误拦截，同时保证错误信息可溯源、可分类、可兜底。

一、认识异步请求的两种错误层级

很多开发者在刚使用原生 fetch API 时，最常犯的错误是以为只要加了 try...catch 或 .catch()，就能兜住所有请求失败。事实并非如此：fetch 返回的 Promise 只会在遭遇网络层故障、DNS解析失败、跨域CORS拦截或请求被主动取消时发生 Reject；当服务端返回 404 Not Found、401 Unauthorized 甚至 500 Internal Server Error 时，Promise 依然处于 Fulfilled（已敲定） 状态，直接走入正常流程。

这意味着 HTTP 错误在默认情况下会“伪装”成成功结果，直到后续尝试读取不存在的数据字段时才抛出未捕获的运行时异常。优雅处理错误的第一步，就是把底层传输错误与应用层协议错误进行结构化拆分。

二、构建类型明确的自定义错误类

JavaScript 原生 Error 仅包含 message 字符串，无法携带状态码、响应体、原始请求 URL 等上下文。当错误流转到页面展示或监控系统时，开发者很难判断这究竟是参数校验失败（422）、会话过期（401）还是网关崩溃（504）。

为此，应当针对 HTTP 请求扩展专用的 HttpError 类，并将请求响应的关键元数据妥善固化：

/**
 * 自定义 HTTP 错误类，携带状态码与服务端返回的具体负载
 */
class HttpError extends Error {
  constructor(message, status, data = null, response = null) {
    super(message);
    this.name = 'HttpError';
    this.status = status;       // HTTP 状态码，如 400, 401, 500
    this.data = data;           // 服务端反序列化后的错误载荷（如 { code: 'INVALID_PARAM' }）
    this.response = response;   // 原始 Response 对象引用
    
    // 维护正确的原型链
    Object.setPrototypeOf(this, HttpError.prototype);
  }

  // 便捷判断方法
  get isClientError() {
    return this.status >= 400 && this.status < 500;
  }

  get isServerError() {
    return this.status >= 500;
  }
}

三、实现健壮且通用的网络请求封装器

一次优雅的异步请求必须具备三个基本防线：

1. 超时保护机制：避免由于移动端弱网或服务器挂起导致请求无限期等待，消耗内存与连接数。
2. 安全反序列化：在提取 response.json() 时做好容错，防止因服务端返回 HTML 错误页或空字符串导致 JSON 解析二次抛错。
3. 非侵入式错误转化：将各种突发异常封装为上述标准的 HttpError 实例。

/**
 * 带有超时控制与稳健错误解析的通用 request 函数
 * @param {string} url 请求目标
 * @param {RequestInit & { timeout?: number }} options 配置选项
 * @returns {Promise<any>}
 */
async function request(url, { timeout = 8000, ...customOptions } = {}) {
  // 1. 设置超时控制信号（兼容最新标准 AbortSignal.timeout）
  const timeoutSignal = AbortSignal.timeout 
    ? AbortSignal.timeout(timeout) 
    : (() => {
        const controller = new AbortController();
        setTimeout(() => controller.abort(new DOMException('Request timed out', 'TimeoutError')), timeout);
        return controller.signal;
      })();

  // 允许调用者传入自定义 signal 并与超时信号合并
  const signal = customOptions.signal
    ? (AbortSignal.any ? AbortSignal.any([customOptions.signal, timeoutSignal]) : timeoutSignal)
    : timeoutSignal;

  const config = {
    headers: {
      'Content-Type': 'application/json',
      ...customOptions.headers,
    },
    ...customOptions,
    signal,
  };

  let response;
  try {
    response = await fetch(url, config);
  } catch (rawError) {
    // 捕获网络挂掉、跨域阻断或超时异常
    if (rawError.name === 'TimeoutError' || (rawError.name === 'AbortError' && timeoutSignal.aborted)) {
      throw new HttpError(`请求超时，未能于 ${timeout}ms 内响应`, 408, null, null);
    }
    throw new HttpError(rawError.message || '网络连接失败，请检查网络设置', 0, null, null);
  }

  // 2. 尝试反序列化返回内容，应对服务端返回非 JSON 的容错
  let responseData = null;
  const contentType = response.headers.get('content-type');
  if (contentType && contentType.includes('application/json')) {
    try {
      responseData = await response.json();
    } catch {
      responseData = null; // 避免解析失败覆盖主流程
    }
  } else {
    try {
      responseData = await response.text();
    } catch {
      responseData = null;
    }
  }

  // 3. 拦截 4xx / 5xx 状态码
  if (!response.ok) {
    const errorMsg = (responseData && responseData.message)
      || `HTTP 请求错误 [${response.status}]`;
    throw new HttpError(errorMsg, response.status, responseData, response);
  }

  return responseData;
}

四、调用端的优雅消费：采用类 Go 风格的元组解构

很多开发者即使在底层做了封装，在上层业务调用（如 React 组件、Vue 事件响应函数）中依然写满了密密麻麻的 try...catch。当一个业务场景需要串行发起两到三个异步操作时，多层嵌套的 try...catch 会导致代码缩进失控，逻辑碎片化。

为了让调用端真正优雅，可以引入类似 Go 语言错误处理风格的工具函数 to()：

/**
 * 将 Promise 转化为 [error, data] 结构
 * @template T
 * @param {Promise<T>} promise
 * @returns {Promise<[null, T] | [HttpError, null]>}
 */
function to(promise) {
  return promise
    .then(data => [null, data])
    .catch(err => [err, null]);
}

对比这两种书写方式在业务场景下的实际体验：

// ❌ 传统写法：多层 try...catch 嵌套，作用域隔离繁琐
async function updateProfileTraditional() {
  try {
    const user = await request('/api/user');
    try {
      const result = await request('/api/user/settings', {
        method: 'POST',
        body: JSON.stringify({ theme: 'dark' }),
      });
      console.log('更新成功', result);
    } catch (settingErr) {
      console.error('设置配置项失败', settingErr.message);
    }
  } catch (userErr) {
    console.error('获取用户信息失败', userErr.message);
  }
}

// ✅ 优雅写法：扁平解构，单行判断，上下文平铺
async function updateProfileElegant() {
  const [userErr, user] = await to(request('/api/user'));
  if (userErr) {
    showToast(userErr.message);
    return;
  }

  const [settingsErr, result] = await to(request('/api/user/settings', {
    method: 'POST',
    body: JSON.stringify({ userId: user.id, theme: 'dark' }),
  }));

  if (settingsErr) {
    showToast(`配置保存异常: ${settingsErr.message}`);
    return;
  }

  showToast('个人资料与配置更新完成！');
}

五、常见错误分类与治理决策总结

处理网络错误并不是简单地弹出一个“系统错误，请重试”的消息提示框。对于不同类型的 HTTP 响应，前端系统的优雅程度直接取决于针对性处理的颗粒度：

综上所述，JavaScript 异步请求错误的“优雅”并非某种神秘语法技巧，而是一套环环相扣的防御性设计：在底层用 response.ok 和 AbortSignal 守住协议与时序，在中间层用 HttpError 规范数据载荷，在消费层用 [err, data] 抹平嵌套。遵循这套机制，网络交互便能拥有极高的容错率与代码可读性。