JavaScript AbortSignal.timeout简化请求超时控制

在前后端交互中，网络请求经常因为服务器响应慢或网络波动而长时间处于“挂起”状态。为了防止页面一直等待，必须给请求设置一个“死亡时间”（超时时间）。过去，实现这一功能需要编写繁琐的控制器逻辑和定时器代码。现在，利用现代 JavaScript 提供的 AbortSignal.timeout() 静态方法，只需一行代码即可完美解决此问题。

传统方案 vs 新方案对比

在深入代码之前，先通过表格对比一下传统写法与新写法的区别，直观感受 AbortSignal.timeout() 带来的便利。

实现基础超时控制

直接使用 AbortSignal.timeout() 方法，将其返回值传递给 fetch 的 signal 参数。该方法会自动创建一个在指定毫秒后自动中止的 AbortSignal 对象。

1. 打开你的 JavaScript 项目文件，找到发送网络请求的代码位置。
2. 定位到 fetch 函数调用处。
3. 配置 fetch 的第二个参数（配置对象），添加 signal 属性。
4. 调用 AbortSignal.timeout(5000) 并赋值给 signal，其中 5000 表示 5000 毫秒（即 5 秒）。

// 发送一个带有 5 秒超时的请求
async function fetchData() {
  try {
    const response = await fetch('https://api.example.com/data', {
      // 核心代码：直接使用静态方法创建超时信号
      signal: AbortSignal.timeout(5000)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('数据获取成功:', data);
  } catch (error) {
    // 错误处理逻辑将在下一步详细说明
    console.error('请求失败:', error);
  }
}

fetchData();

捕获与识别超时错误

当请求超时被中止时，fetch 会抛出一个错误。你需要捕获这个错误，并判断它是否是因为超时引起的，以便给用户展示正确的提示信息。

1. 编写 try...catch 结构包裹 fetch 请求（如上一步代码所示）。
2. 检查 catch 块中捕获到的 error 对象的 name 属性。
3. 判断 name 是否等于字符串 'AbortError'。
4. 执行 不同的逻辑：如果是超时，提示用户重试；如果是其他网络错误，提示检查网络。

async function fetchDataWithErrorHandling() {
  try {
    const response = await fetch('https://api.example.com/slow-data', {
      signal: AbortSignal.timeout(2000) // 设置 2 秒超时
    });
    const data = await response.json();
    return data;
  } catch (error) {
    // 步骤 3：判断错误类型
    if (error.name === 'AbortError') {
      // 步骤 4：专门处理超时情况
      console.error('请求超时，服务器未在 2 秒内响应');
      return { error: 'Timeout', message: '请求超时，请刷新重试' };
    } else {
      // 处理其他网络错误
      console.error('网络连接错误:', error.message);
      return { error: 'Network', message: '网络连接失败' };
    }
  }
}

理解超时执行流程

为了更清晰地展示 AbortSignal.timeout() 在请求生命周期中的工作机制，请参考以下流程图。该图描述了从请求发出到最终结束的决策路径。

组合多个中止信号（进阶用法）

在某些复杂场景下，你可能既希望请求在 5 秒后超时，又希望用户能够通过点击“取消按钮”立即手动中止请求。此时可以使用 AbortSignal.any() 将超时信号和手动控制信号组合在一起。

1. 创建一个 AbortController 实例，用于绑定用户的取消操作（如点击按钮）。
2. 生成一个超时信号 AbortSignal.timeout(5000)。
3. 使用 AbortSignal.any([manualSignal, timeoutSignal]) 创建一个组合信号。
4. 传入 组合信号给 fetch。只要其中任意一个信号触发中止，请求就会停止。

// 步骤 1：创建手动控制器
const manualController = new AbortController();
// 假设这是一个取消按钮的点击事件
// cancelButton.addEventListener('click', () => manualController.abort());

async function fetchWithComboSignal() {
  // 步骤 2：生成超时信号 (5秒)
  const timeoutSignal = AbortSignal.timeout(5000);

  // 步骤 3：组合信号 (任意一个触发即中止)
  const combinedSignal = AbortSignal.any([
    manualController.signal,
    timeoutSignal
  ]);

  try {
    const response = await fetch('https://api.example.com/long-task', {
      // 步骤 4：使用组合信号
      signal: combinedSignal
    });
    return await response.json();
  } catch (error) {
    if (error.name === 'AbortError') {
      if (manualController.signal.aborted) {
        console.log('用户手动取消了请求');
      } else {
        console.log('请求自动超时');
      }
    }
  }
}

环境兼容性检查

在使用 AbortSignal.timeout() 之前，请确认你的运行环境支持该 API。如果你的应用需要兼容旧版浏览器，可能需要引入 polyfill 或回退到传统的 setTimeout 方案。

1. 检查 Node.js 版本是否大于等于 v20.0.0（支持度较好）。
2. 检查 浏览器版本（Chrome 103+, Firefox 102+, Safari 16.4+ 均已支持）。
3. 执行 以下特征检测代码，在不支持的环境下提供备用逻辑。

if (typeof AbortSignal.timeout !== 'function') {
  console.warn('当前环境不支持 AbortSignal.timeout，请使用 polyfill 或传统方案');
  // 在此处回退到传统的 setTimeout + AbortController 逻辑
}