Node.js 中的 AbortController：统一取消异步操作的标准方案

在 Node.js 里写异步代码，大多数时候我们都在处理“怎么等待结果”。但真正让系统变得复杂的是另一个问题：怎么取消一个已经发出去的异步操作。

这个问题在浏览器端早就有了答案——fetch 支持 AbortController 取消请求已经不是新鲜事。但很多 Node.js 开发者对它的认知还停留在“fetch 里能用”的层面，没有意识到 AbortController 是一套通用的取消机制。它不限于 HTTP 请求，完全可以把取消能力嵌入你自己写的异步函数、数据库访问、流处理或者任何等待型逻辑里。

这篇文章想聊清楚三件事：AbortController 到底解决了什么问题，它的信号机制在工作层面是怎么运转的，以及在实际工程项目里如何设计一个支持取消的异步接口。

异步操作为什么这么难取消

很多团队都遇到过这样的场景：业务代码里明明已经 return 了，异步操作却还在后台继续跑。

举一个很典型的例子。一个 Node.js 服务接收客户端的请求，内部需要调用一个上游 HTTP 接口取数据。如果客户端在等待时断开了连接，Node.js 这边并不会自动取消对上游的调用。上游接口照常执行，响应照常返回，只是这个响应已经没人需要了。在高并发场景下，这些“没人要的结果”会一直占着连接池、消耗数据库配额、堆积在事件循环里。

真正麻烦的地方在于，这种取消需求不是一个标志位就能解决的。当操作嵌套起来——先查缓存、再查数据库、再调外部 API——每一层都需要你手动检查状态，而且即使你不想等结果了，底层的 I/O 资源也未必能真正释放。这也是为什么社区最终需要一个标准化的取消机制，而不是继续靠各自发明的 hack。

AbortController 不是执行者，而是通知者

很多人第一次接触 AbortController 时，会误以为调用 abort() 就“取消”了某个操作。实际上它并不负责取消这件事本身，它只负责发出一个信号。真正响应这个信号的，是监听它的那一方。

AbortController 和 AbortSignal 是标准 Web API 的组成部分，Node.js 从 15.x 开始完整支持。拆开来看，它们其实是两个角色：

• AbortController：提供 abort() 方法，用来触发取消信号。
• AbortSignal：代表信号本身，通过 aborted 属性和 abort 事件向外传递状态。

当 abort() 被调用时，所有持有这个 signal 的监听者都会收到通知。这个机制看起来简单，但它解决了一个核心问题：取消意图的标准化传递。过去我们传递取消意图，要么靠全局事件，要么层层传回调，要么用一个可变对象四处检查。AbortSignal 把这件事变成了一种约定：任何异步函数都可以把 signal 作为参数接收，并在内部决定如何响应。

以最常用的 fetch 为例：

const controller = new AbortController();
const { signal } = controller;

const request = fetch('https://api.example.com/data', { signal });

// 3 秒后取消请求
setTimeout(() => controller.abort(), 3000);

try {
  const res = await request;
  const data = await res.json();
  console.log(data);
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('请求已在超时前被取消');
  }
}

这里 fetch 是“响应信号的一方”。它监听了 signal 的 abort 事件，在收到信号后真正断开底层的 TCP 连接。AbortController 只负责通知，具体怎么取消、取消到什么程度，由 fetch 内部实现决定。

自己写的异步函数如何支持取消

理解了上面的关系，就会发现让一个自定义异步函数支持取消并不复杂。核心只需要做三件事：接收 signal、监听 abort 事件、在 finally 中清理监听器。

下面是一个包装文件读取的简化示例：

function readFileWithAbort(path, { signal } = {}) {
  return new Promise((resolve, reject) => {
    const => {
      reject(signal.reason ?? new Error('操作已取消'));
    };

    // 如果进来之前就已经被取消，直接失败
    if (signal?.aborted) {
      return reject(signal.reason ?? new Error('操作已取消'));
    }

    signal?.addEventListener('abort', onAbort, { once: true });

    fs.promises.readFile(path, 'utf8')
      .then(resolve)
      .catch(reject)
      .finally(() => {
        signal?.removeEventListener('abort', onAbort);
      });
  });
}

这段代码有几个细节值得注意。

首先是 signal.reason。调用 controller.abort(reason) 时可以传入任意值作为取消原因，默认是一个 AbortError 实例。使用 reason 而不是自己 new 一个 Error，能让调用方拿到更完整的上下文。其次是 addEventListener 的 once 选项和 removeEventListener 成对出现，这保证了函数执行完成后不会保留无用的监听器，避免内存泄漏。

我用 fs.promises.readFile 做例子，是有意为之。它本身不支持 signal，所以这里的“取消”实际上是提前 reject，让调用方不用继续等待。真正的底层文件读取仍在进行，只是结果被丢弃了。这说明一个重要的区分：AbortController 的取消通知是可靠的，但取消动作的彻底程度取决于被调用方。fetch 能断掉网络连接，fs.readFile 做不到直接中断磁盘读取，数据库驱动则要看各自的实现。

超时本质上是一种自动取消

在工程里，最常和取消一起出现的是超时。Node.js 17.3 之后提供了 AbortSignal.timeout()，直接用一行代码就能组合出超时取消：

const res = await fetch('https://api.example.com/data', {
  signal: AbortSignal.timeout(5000)
});

这比手动写 setTimeout 加 controller.abort() 要干净得多。AbortSignal.timeout() 返回一个 signal，在指定毫秒数后自动触发 abort，并且 reason 是一个 TimeoutError。如果你需要在超时后拿到请求结果做日志记录，也可以在最外层用 try/catch 捕获，再判断 err.name。

这里有一个工程上的判断：超时到底应该用 AbortSignal.timeout，还是用 Promise.race 去模拟？我倾向于优先用前者，因为 Promise.race 只是让调用方“感觉不到”那个慢操作，操作本身并没有被取消，后台的资源占用依然存在。而 AbortSignal.timeout 有能力把取消意图传递到 fetch、数据库驱动或者你自己封装的函数里。

几种取消方案的实际对比

在 AbortController 成为共识之前，Node.js 项目里最常见的取消方案有这么几种。把它们放在一起看，各自的能力边界会很清晰：

这张表格想表达的核心观点是：取消方案的选择，不应该只考虑“调用方怎么提前返回”，还要考虑“底层资源怎么被真正释放”。AbortController 之所以值得推广，是因为它把取消变成了一种可以沿着调用链传递的信号，而不是一次性的小技巧。

这种差别在真实的批量任务场景里非常明显。假设你有一个定时跑批的服务，需要顺序调用多个下游系统，正常情况下每个接口都能在几百毫秒内返回。但如果某个下游因为故障把响应时间拖到了 30 秒，而你又没有做任何取消控制，整个队列都会被这个异常点卡住，后面的任务全部跟着等待。反过来，如果调用链使用的是基于 signal 的超时取消，队列只需要把失败的任务标记出来单独重试，其他任务完全不受影响。

真实项目里最容易踩的坑

在真实项目里接入 AbortController，最容易出问题的往往不是概念，而是下面这些细节。

以为 signal 会自动取消所有事情

这是最常见的误区。signal 本身没有任何取消能力，它只是一个信号。你在一个异步函数里接收了 signal，就必须自己监听 abort 事件并决定要做什么。如果只想让调用方尽快拿到异常，提前 reject 就够了；如果想真正释放资源，必须操作底层对象。很多人写完代码后发现“为什么取消了操作还在跑”，多半就是只传了 signal，但没有监听它。

abort 监听器没有清理

所有 addEventListener 都有对应的 removeEventListener，这一点在频繁创建和销毁的请求级对象上尤其重要。一个短暂的 HTTP 请求如果因为某个原因没有走到 finally，带着一次性监听器的 signal 会一直被引用，逐步累积成内存泄漏。把清理逻辑放在 finally 里是底线，不是加分项。

取消请求引发的错误被静默吞掉

取消不是失败，但也绝对不是成功。很多团队在 catch 里统一处理错误时，会把 AbortError 和其他错误混在一起，导致监控系统把正常取消也当成故障告警。更合理的做法是单独判断 err.name === ‘AbortError’，把它作为一种预期内的控制流来处理。

设计层面的建议：把 signal 当作一等参数

如果你的代码库正在被“无法取消的异步操作”困扰，可以尝试从接口层开始改造。

第一个建议是，团队内部封装的异步函数，统一把 signal 作为可选参数接收，并遵循“给则响应，不给则忽略”的兼容策略。这样上层调用可以很容易地把取消意图向下传递。Node.js 生态里已经有大量库这么做了，比如 fetch、axios、以及不少数据库驱动。

第二个建议是，在 HTTP 服务层把请求生命周期和 AbortController 绑定起来。比如服务器收到请求时创建一个 controller，在 req 的 close 事件里调用 abort()，然后把 signal 传给下游调用。这样客户端断开连接时，整条调用链都能收到取消信号。

第三个建议是，利用 AbortSignal.any() 组合多个信号来源。Node.js 20 以上的版本支持这个 API，它可以把多个 AbortSignal 合并成一个，比如把“用户断开”和“全局超时”两个信号合并，任何一个触发都会取消整个操作。这比手动叠加多个监听器要清晰得多。

从哪里开始落地

如果团队之前没有用过 AbortController，我建议不要急着改造所有代码。先从最痛的地方开始：找出系统里那些“用户走了还在跑”的请求，或者那些慢到拖垮队列的上游调用，把它们的调用链改成基于 signal 的取消模式。这通常只是很小的改动——在发起请求的地方创建 controller，把 signal 传进去，在必要的回调里调用 abort()。

当几个核心路径的数据流已经验证了这套机制之后，再把它沉淀为团队内部的接口规范。比如代码评审时明确要求：新建的异步函数，如果有等待行为，就应该考虑支持 signal。这是个习惯问题，并不需要追求一步到位。

AbortController 的价值不在于它有多高级，而在于它让“取消”这件事第一次有了标准化的表达方式。在一个调用链越来越深的 Node.js 项目里，这种标准化比任何一次性的取消技巧都更能控制复杂度。