30 seconds of code 精讲:使用 AbortController 正确取消 JavaScript fetch 请求

原创2026-09-30 17:28:481,716 阅读
文章标签:教程文档

30 seconds of code 精讲:使用 AbortController 正确取消 JavaScript fetch 请求

Fetch API 如今已成为 JavaScript 中发送异步请求的事实标准,而 AbortController 与 signal 选项则为我们提供了优雅地取消请求的能力。本文将基于 30 seconds of code 仓库中的 abort-fetch.md 文档,深入讲解如何在请求超时、组件卸载、用户取消等场景下正确中止 fetch 请求,并结合仓库内的 React useFetch Hook、Promise 超时工具与 HTTP 请求系列文档,提供可直接落地到项目的完整实战方案。

为什么需要取消 fetch 请求

在浏览器中,fetch() 返回的是一个 Promise,代表异步请求的最终完成或失败。正如仓库中 promises.md 所阐述的,Promise 会经历 pending(进行中)、fulfilled(成功)和 rejected(失败)三种状态。问题在于:一旦发起了请求,默认情况下我们无法主动干预它的进行过程。

这在实际开发中会带来三个典型痛点:

  • 请求超时:网络状况不佳时,一个请求可能长时间挂在 pending 状态,用户得不到任何反馈;
  • 响应不再需要:用户已经离开了当前页面、切换了筛选条件,或组件已经卸载,此时旧请求的响应结果已无意义;
  • 资源浪费:未被取消的请求仍会占用连接、带宽与内存,尤其在高频搜索、下拉加载等场景中,会产生大量无效请求堆积。

AbortController 正是标准化的解决方案:它允许我们在任意时刻主动中止一个进行中的 fetch 请求,并在必要时释放相关资源。

AbortController 基础用法

文档给出的核心用法非常简洁,共分三步:创建控制器、将 signal 传给 fetch()、调用 abort() 取消请求。

// 1. 创建 AbortController
const controller = new AbortController();
const { signal } = controller;

// 2. 发起请求并传入 signal
fetch('https://my.site.com/data', { signal })
  .then(res => console.log(res));

// 3. 随时取消请求
controller.abort();

其底层原理如下:

  • AbortController 实例上挂载着一个 signal 属性,该属性是一个 AbortSignal 对象,相当于控制器与请求之间的"信号线";
  • 将 signal 作为 fetch 的 options.signal 传入后,请求会持续监听该信号;
  • 一旦调用 controller.abort(),AbortSignal 的状态被置为 aborted,fetch 请求立即被中止,对应的 Promise 会以 AbortError(DOMException,name 为 AbortError)为原因 reject。

需要特别说明的是:一次 abort 是单向的、不可逆的。同一个 AbortController 一旦调用过 abort(),其 signal.aborted 将永远为 true,不能再复用于后续请求。如果需要多次取消能力,应当为每次请求创建新的 AbortController 实例。

在 React 组件中结合 useEffect 取消请求

文档指出,取消请求在"请求耗时过长或响应不再需要"时尤其有用,并特别提及了常见的 React 场景,仓库对应的实现位于 use-fetch.md。该 Hook 完整展示了如何把"取消请求"与"组件卸载"绑定起来,避免内存泄漏和"在已卸载组件上更新状态"的警告:

const useFetch = (url, options) => {
  const [response, setResponse] = React.useState(null);
  const [error, setError] = React.useState(null);
  const [abort, setAbort] = React.useState(() => {});

  React.useEffect(() => {
    const fetchData = async () => {
      try {
        const abortController = new AbortController();
        const signal = abortController.signal;
        setAbort(abortController.abort);
        const res = await fetch(url, {...options, signal});
        const json = await res.json();
        setResponse(json);
      } catch (error) {
        setError(error);
      }
    };
    fetchData();
    return () => {
      abort();
    }
  }, []);

  return { response, error, abort };
};

这段实现中的关键设计值得我们逐一拆解:

  1. 控制器生命周期与 effect 对齐:AbortController 在 useEffect 内部创建,组件每次挂载都会得到一个新的控制器实例;
  2. 卸载时取消:useEffect 返回的清理函数(cleanup)在组件卸载时执行 abort(),此时进行中的请求被中止,.catch 捕获到 AbortError 后通过 setError 记录,而不会再触发 setResponse 去更新一个已卸载组件的状态;
  3. 请求选项合并:{...options, signal} 将外部传入的 options 与 signal 合并,既保留了调用方对 method、headers、body 等选项的控制,又强制注入了取消信号,signal 排在后者确保其不被外部覆盖;
  4. 暴露 abort 能力:通过 setAbort(abortController.abort) 把 abort 暴露给组件,业务代码可在任意时刻主动取消(例如"停止下载"按钮)。

组件消费侧同样在该文档中给出示例:无 response 且无 error 时渲染加载态,有 response 时渲染数据,有 error 时渲染错误提示,从而让 UI 完整反映请求的三种状态。

请求超时与 Promise 竞速方案

除了组件卸载,最常见的取消场景是"超时"。仓库中的 await-timeout.md 提供了另一种不依赖 AbortController、但常与之配合的思路:用 Promise.race() 让"请求 Promise"与"定时器 Promise"竞争,先完成者胜出。

const awaitTimeout = (delay, reason) =>
  new Promise((resolve, reject) =>
    setTimeout(
      () => (reason === undefined ? resolve() : reject(reason)),
      delay
    )
  );

const wrapPromise = (promise, delay, reason) =>
  Promise.race([promise, awaitTimeout(delay, reason)]);

wrapPromise(fetch('https://cool.api.io/data.json'), 3000, {
  reason: 'Fetch timeout',
})
  .then(data => {
    console.log(data.message);
  })
  .catch(data => console.log(`Failed with reason: ${data.reason}`));

需要注意 Promise.race() 方案与 AbortController 的本质区别:前者只是让代码"先返回超时结果",底层 fetch 请求并未真正被取消,它仍会继续占用网络资源直到自然完成。因此更严谨的做法是将两者结合——超时后同时调用 controller.abort() 真正中断底层请求,并捕获 AbortError:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 3000);

fetch('https://my.site.com/data', { signal: controller.signal })
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => {
    if (err.name === 'AbortError') {
      console.log('请求已超时并被取消');
    } else {
      console.error('请求失败:', err);
    }
  })
  .finally(() => clearTimeout(timeoutId));

finally 中的 clearTimeout() 是必要的收尾工作:请求在超时前完成时,应清理定时器,避免它在请求结束后仍然触发无意义的 abort()。

错误处理:识别 AbortError 与状态感知

取消请求会使 Promise 以 DOMException(name 为 AbortError)reject。因此,错误的分类处理是生产代码中不可省略的一环:

  • 主动取消(AbortError):属于可预期、非异常情况,不应当作真实网络错误向用户展示报错,通常只需静默处理或更新 UI 为"已取消"状态;
  • 真实失败:网络断开、服务器 5xx、CORS 失败等,才需要记录日志并展示错误提示。
fetch(url, { signal })
  .then(response => {
    if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
    return response.json();
  })
  .catch(err => {
    if (err.name === 'AbortError') {
      // 用户主动取消或组件卸载,无需展示错误
      console.log('请求已取消');
    } else {
      // 真实错误,需要上报或提示
      console.error('请求失败:', err);
    }
  });

同时注意,abort() 之后 promise 进入的是 rejected 状态,若链式调用中没有 .catch() 捕获该拒绝,会产生未处理的 promise 拒绝(unhandled rejection)警告。因此只要使用了 signal,就必须配套错误处理。

典型应用场景与最佳实践小结

综合文档及仓库相关内容,以下是几个高频实战场景的落地建议:

1. 组件卸载时取消(React) 在 useEffect 的清理函数中调用 abort(),配合 signal 传入请求,避免卸载后更新状态引发的内存泄漏与 React 警告。完整可运行示例见 use-fetch.md。

2. 请求超时自动取消 用 setTimeout(() => controller.abort(), ms) 实现超时,并结合 err.name === 'AbortError' 区分"超时取消"与"真实错误"。

3. 用户主动取消 为搜索框、文件下载、图像加载等场景绑定"取消"按钮,直接调用 controller.abort();对高频触发场景,可在发起新请求前先 abort 旧请求的控制器。

4. 请求竞态防护 在"筛选条件变化""分页切换"等场景中,上一次请求的响应可能晚于新请求到达并覆盖新数据。将每个请求绑定独立的 AbortController,在新请求发出时中止旧请求,即可从源头消除竞态。

5. 结合 HTTP 方法使用 取消逻辑与请求方法无关,signal 可无缝应用于仓库 http-get-post-put-delete.md 中展示的 GET、POST、PUT、DELETE 任意一种 fetch 用法。

最后回到核心原则:一个 AbortController 对应一次请求生命周期。创建控制器 → 注入 signal → 在恰当的时机 abort → 捕获并分类处理 AbortError,这条完整链路就是浏览器标准下"优雅取消 fetch 请求"的正确姿势。

登录后查看全文
30-seconds-of-code