JavaScript 教程:使用 AbortController 取消 fetch 请求与异步任务
JavaScript 教程:使用 AbortController 取消 fetch 请求与异步任务
fetch 返回的是 Promise,而 JavaScript 的 Promise 本身没有"取消"概念,因此当一个正在进行的网络请求不再需要时(例如用户已离开页面、切换了筛选条件、或超时),如何主动终止它就成了实际问题。本指南围绕 Modern JavaScript Tutorial(本仓库 1-js / 5-network 系列)中 Fetch: Abort 一章展开,系统讲解内建对象 AbortController 的用法:如何用它取消单个 fetch、一次取消多个并行请求,以及如何让自定义异步任务共享同一套取消机制。读完本文你将掌握一套不依赖任何第三方库、浏览器原生支持的请求取消方案,并能在实际项目中正确处理 AbortError。
AbortController 对象:为"可取消操作"而生的内建对象
JavaScript 语言层面没有"中止一个 Promise"的标准 API,但存在一个专为此类场景设计的内建对象:AbortController。它不仅适用于 fetch,也可以服务于其他任意异步任务。
创建控制器非常简单:
let controller = new AbortController();
控制器是一个极其简单的对象,只有两部分:
- 一个方法
abort(); - 一个属性
signal,允许在其上挂载事件监听器。
当调用 abort() 时,会发生两件事:
controller.signal触发"abort"事件;controller.signal.aborted属性变为true。
整个过程通常涉及两方参与者:
- 执行方可取消操作的一方:在
controller.signal上设置事件监听器; - 发起取消的一方:在需要时调用
controller.abort()。
下面是不涉及 fetch 的完整示例(来自 article.md),演示了这一事件传播机制:
let controller = new AbortController();
let signal = controller.signal;
// 执行可取消操作的一方拿到 signal 对象
// 并注册监听器,在 controller.abort() 被调用时触发
signal.addEventListener('abort', () => alert("abort!"));
// 另一方(可在任意时刻)发起取消:
controller.abort(); // abort!
// 事件已触发,signal.aborted 变为 true
alert(signal.aborted); // true
由此可见,AbortController 本质上只是"调用 abort() → 在 signal 上派发 abort 事件"这一交互的标准化载体。类似的"事件监听"逻辑你完全可以自己实现,但真正有价值的是:fetch 原生就认识 AbortController,二者深度集成,这正是它不可替代的地方。
与 fetch 集成:把 signal 作为请求选项传入
要让一个 fetch 可以被取消,只需要把 AbortController 的 signal 属性作为 fetch 的第二个参数(选项对象)传入:
let controller = new AbortController();
fetch(url, {
signal: controller.signal
});
fetch 会在内部监听 signal 上的 abort 事件。此后随时调用:
controller.abort();
请求即被终止。在 Fetch API 一章 的选项清单中,signal 选项的官方说明正是 // AbortController to abort request,与本文所述一致,可见它是 fetch 选项体系中的一等公民。
被中止时:Promise 以 AbortError 拒绝
当 fetch 被中止时,其返回的 Promise 会以名为 AbortError 的错误拒绝,因此必须在 try..catch(或 .catch)中处理它,避免产生未捕获的 Promise 异常。
以下是文档中的完整示例——发起请求 1 秒后自动中止,并区分 AbortError 与其他错误(见 article.md):
// 1 秒后中止
let controller = new AbortController();
setTimeout(() => controller.abort(), 1000);
try {
let response = await fetch('/article/fetch-abort/demo/hang', {
signal: controller.signal
});
} catch(err) {
if (err.name == 'AbortError') { // 处理 abort() 触发的中止
alert("Aborted!");
} else {
throw err; // 其他错误照常抛出
}
}
这里请求的地址 /article/fetch-abort/demo/hang 在本仓库中有对应的演示服务器实现:demo.view/server.js。它基于 Koa 构建,其关键端点是一个"永不返回"的挂起请求:
router.get('/hang', async (ctx) => {
await new Promise(() => {}); // 永不 resolve,模拟长时间挂起的请求
});
await new Promise(() => {}) 使该请求永远不会完成,是验证 AbortController 取消能力最直接的测试场景:若不中止,这个 fetch 会一直挂起;调用 controller.abort() 后,Promise 立即以 AbortError 拒绝,进入 catch 分支。
工程实践要点:
- 判断中止请使用
err.name == 'AbortError',不要依赖错误消息文本; - 捕获到
AbortError后通常无需提示用户"网络错误",因为这是应用主动取消,属于预期流程; - 其他非中止错误(如网络断开、HTTP 层失败)应原样抛出或单独处理,切勿与取消混为一谈。
AbortController 可扩展:一次取消所有并行请求
AbortController 是可扩展(scalable)的——同一个控制器可以同时取消多个 fetch。假设我们并行抓取一批 URL,并希望用一个控制器统一管理它们的生命周期:
let urls = [...]; // 需要并行 fetch 的 URL 列表
let controller = new AbortController();
// fetch 的 Promise 数组
let fetchJobs = urls.map(url => fetch(url, {
signal: controller.signal
}));
let results = await Promise.all(fetchJobs);
// 只要在任意位置调用 controller.abort(),
// 所有 fetch 会同时被中止
每个 fetch 都监听同一个 signal,因此一次 abort() 调用即可让整个批处理任务全部终止。这在"用户取消了整页加载""分页/搜索请求竞态""批量预取被废弃"等场景中尤其有用。
自定义异步任务与 fetch 共享取消信号
如果你有自己的异步任务(不是 fetch),同样可以把它们纳入这套取消机制:只需要在自己的任务里监听 signal 的 abort 事件即可。
下面是文档中的组合示例——自定义任务 ourJob 与多个 fetch 并行等待,共享同一个控制器(见 article.md):
let urls = [...];
let controller = new AbortController();
let ourJob = new Promise((resolve, reject) => { // 我们的自定义任务
...
controller.signal.addEventListener('abort', reject); // 被中止时拒绝
});
let fetchJobs = urls.map(url => fetch(url, { // fetch 任务
signal: controller.signal
}));
// 并行等待所有 fetch 和我们的任务
let results = await Promise.all([...fetchJobs, ourJob]);
// 只要调用 controller.abort(),
// 所有 fetch 与 ourJob 会一并被中止
这里 controller.signal.addEventListener('abort', reject) 让自定义任务在中止信号到来时以 reject 结束——reject 被调用时传入的默认参数会使得 ourJob 以一个错误被拒绝,从而与 fetchJobs 的中止行为保持一致。这种"统一信号、统一取消"的模式意味着:无论任务来源是 fetch 还是手写逻辑,一套 AbortController 即可统管全部。
需要留意的是,若要在中止后区分"被取消"与"正常失败",自定义任务中更稳妥的写法是显式构造 AbortError(如 reject(new DOMException('Aborted', 'AbortError'))),并让 Promise 链按相同约定处理——这与 fetch 的内建行为对齐。
相关章节联动
AbortController 在教程中并非孤立存在,它与以下内容相互呼应:
- Promise API(Promise.all):该章明确指出
Promise.all本身不会取消任何 Promise,因为 Promise 没有取消概念,并预告"取消"由AbortController补足; - Fetch API 选项清单:
signal: undefined, // AbortController to abort request是该选项的权威出处; - XMLHttpRequest:XHR 体系也有对应的
abort事件语义,可对照理解不同请求 API 的取消模型。
总结
AbortController是一个极简对象:调用abort()方法时,会在其signal属性上触发abort事件,并将signal.aborted置为true;fetch与之深度集成:把signal作为选项传入后,fetch会监听它,从而可以被中止;中止时 Promise 以AbortError拒绝,需用try..catch配合err.name == 'AbortError'处理;- 该模式可扩展:一个控制器能同时取消多个并行 fetch;自定义异步任务同样可以监听
signal的abort事件,与 fetch 共享同一套取消机制; - "调用
abort()→ 监听abort事件"的交互简单且通用,即使不使用fetch,也可以把AbortController作为通用的任务取消基础设施。