30 seconds of code 精讲:使用 AbortController 正确取消 JavaScript fetch 请求
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 };
};
这段实现中的关键设计值得我们逐一拆解:
- 控制器生命周期与 effect 对齐:
AbortController在useEffect内部创建,组件每次挂载都会得到一个新的控制器实例; - 卸载时取消:
useEffect返回的清理函数(cleanup)在组件卸载时执行abort(),此时进行中的请求被中止,.catch捕获到AbortError后通过setError记录,而不会再触发setResponse去更新一个已卸载组件的状态; - 请求选项合并:
{...options, signal}将外部传入的options与signal合并,既保留了调用方对method、headers、body等选项的控制,又强制注入了取消信号,signal排在后者确保其不被外部覆盖; - 暴露 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 请求"的正确姿势。