企业官网建设流程全解析

es-toolkit AbortError 详解：基于 AbortSignal 的中断操作错误处理指南

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit

AbortError是 es-toolkit 在error模块中提供的错误类，用于统一表示被中断或取消的操作。本文围绕 es-toolkit 的AbortError类，讲解其构造函数、默认与自定义错误消息、与AbortSignal的协作方式，并结合 delay 等源码实现说明其底层调用链与设计原理，帮助你写出可正确识别"操作被取消"这一异常场景的健壮异步代码。

概述：为什么需要 AbortError

在现代 JavaScript 异步编程中，AbortSignal与AbortController是标准化的取消机制。当一个耗时操作（如网络请求、定时延迟）被用户主动取消或超时中断时，我们需要一种方式把这个"取消"事实以异常的形式传递出来，让上层调用方能够区分：

• 操作真的失败了（网络错误、业务异常）；
• 操作被人为取消了（用户点击了停止按钮、组件卸载、信号超时）。

es-toolkit 提供AbortError正是为了第二种场景：它是一个专门表达"操作被中断或取消"的错误类，语义清晰，便于统一捕获与处理。

const error = new AbortError(message);

构造函数与参数

new AbortError(message?)

AbortError用于表示被中断或取消的操作。它会在类似 debounce 或 delay 这样的操作被AbortSignal取消时被抛出。

• 返回值：AbortError实例，表示一次被中断的操作。它继承自Error（运行时支持DOMException时继承自DOMException），其name属性为'AbortError'。

import { AbortError } from 'es-toolkit/error'; // 使用默认消息创建错误 throw new AbortError(); // 错误消息: 'The operation was aborted' // 使用自定义消息创建错误 throw new AbortError('文件上传已取消'); // 错误消息: '文件上传已取消'

结合 AbortSignal 的典型用法

AbortError最常见的应用场景是与AbortSignal配合。es-toolkit 官方文档给出了一个完整的示例：在fetchData中执行一个可取消的delay，一旦捕获到AbortError就输出"操作已取消"。

import { AbortError, delay } from 'es-toolkit'; async function fetchData(signal: AbortSignal) { try { await delay(1000, { signal }); return '数据加载完成'; } catch (error) { if (error instanceof AbortError) { console.log('操作已取消'); } throw error; } } const controller = new AbortController(); controller.abort(); // 取消操作 await fetchData(controller.signal); // 抛出 AbortError

这段代码有两个关键点：

1. 用instanceof AbortError做类型收窄：在catch中先判断是否为取消导致的异常，再决定是吞掉还是继续向上抛出。非取消类错误仍会通过throw error传播，保证业务异常不会被误判为取消。
2. AbortSignal是标准接口：AbortController来自运行时（浏览器 / Node.js），es-toolkit 的delay接收{ signal }选项，并在信号触发abort事件时拒绝（reject）返回的 Promise。

源码级原理：AbortError 如何被抛出

类的定义

AbortError的完整实现非常精简，见 src/error/AbortError.ts：

import { DOMException } from '../_internal/DOMException.ts'; /** * An error class representing an aborted operation. * @augments DOMException */ export class AbortError extends DOMException { constructor(message = 'The operation was aborted') { super(message); } }

从源码可以看出三个设计事实：

• 默认消息：message = 'The operation was aborted'，与文档中的默认值一致；
• 继承自DOMException：在标准运行时中，AbortError是DOMException的子类（这也是浏览器规范中取消操作的标准异常类型，如fetch被 abort 时抛出的就是DOMException，其name为AbortError）；同时Error也是其原型链上的基类，因此instanceof Error恒为true；
• name属性：作为DOMException的实例，其name属性为'AbortError'。

DOMException 回退机制

src/_internal/DOMException.ts 中处理了运行时不支持DOMException的情况（例如 Hermes / React Native 等 JavaScript 引擎）：

import { globalThis } from './globalThis.ts'; // Falls back to `Error` on runtimes without `DOMException` (e.g. Hermes / React Native). // Type stays `typeof DOMException` so the emitted `.d.ts` keeps `AbortError extends DOMException`. export const DOMException: typeof globalThis.DOMException = typeof globalThis.DOMException !== 'undefined' ? globalThis.DOMException : (Error as unknown as typeof globalThis.DOMException);

即：若运行时存在全局DOMException则直接使用，否则回退到Error。这样保证了AbortError在任意环境下都能正常构造与抛出，同时让生成的类型声明（.d.ts）中仍保持AbortError extends DOMException的签名。

测试如何验证这些行为

src/error/AbortError.spec.ts 用 Vitest 对上述行为做了全面验证：

• new AbortError()是Error的实例；
• 未传参时message为'The operation was aborted'；
• 传入自定义消息时message为自定义值；
• 运行时存在DOMException时，AbortError是其实例；
• 通过vi.stubGlobal('DOMException', undefined)模拟 Hermes 等无DOMException的环境时，模块仍能正常加载，回退后的AbortError依然是Error实例且默认消息不变。

delay 中的调用链

AbortError的实际抛出来自底层调用方。以 src/promise/delay.ts 为例，delay接收{ signal }选项，内部实现如下核心逻辑：

if (signal?.aborted) { return abortError(); } const timeoutId = setTimeout(() => { signal?.removeEventListener('abort', abortHandler); resolve(); }, ms); signal?.addEventListener('abort', abortHandler, { once: true });

其中abortError即reject(new AbortError())。可以看到：

• 若传入的signal在调用时已经处于 aborted 状态（signal.aborted === true），delay立即拒绝并抛出AbortError；
• 否则注册一次性abort监听器，一旦信号在延迟期间被controller.abort()触发，就清除定时器并抛出AbortError；
• 正常等到ms毫秒后会移除监听器并resolve()，避免内存泄漏。

导出路径

AbortError通过 src/error/index.ts 导出，并在 src/index.ts 中以export * from './error/index.ts'对外暴露。因此你可以有两种导入方式：

// 按子路径导入 import { AbortError } from 'es-toolkit/error'; // 从主入口导入 import { AbortError, delay } from 'es-toolkit';

与 TimeoutError 的对比

es-toolkit 的error模块还提供了TimeoutError（见 src/error/TimeoutError.ts），两者结构几乎相同，但语义不同：

两者都继承自DOMException（回退到Error），并分别以name = 'AbortError'与name = 'TimeoutError'区分。实际编码时，你可以在同一个catch块中分别判断这两种"非业务性"异常，做出不同的降级处理。

最佳实践小结

• 统一出口：在封装可取消的异步函数时，内部统一throw new AbortError()，让调用方用instanceof AbortError识别取消场景；
• 区分取消与失败：取消应视为"预期中的中断"，通常无需上报错误监控；真正的业务异常则应继续抛出；
• 复用标准信号：AbortSignal可以同时传递给多个操作（如delay与真实请求），一处controller.abort()即可级联取消；
• 兼容多运行时：得益于DOMException回退机制，AbortError在浏览器、Node.js 以及 Hermes / React Native 等环境都能正常工作。

延伸阅读

• 本文主题的英文权威说明见 docs/reference/error/AbortError.md，本文日文原版见 docs/ja/reference/error/AbortError.md；
• AbortError的完整实现：src/error/AbortError.ts；
• 配套测试用例：src/error/AbortError.spec.ts；
• 实际抛出AbortError的可取消异步函数：src/promise/delay.ts；
• 同类错误类TimeoutError：src/error/TimeoutError.ts；
• error模块导出入口：src/error/index.ts。

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit