Fetch AbortController传递取消原因并区分异常来源的实现方法

我在做搜索框联想请求时遇到过一个很典型的竞态：用户刚输入第二个字符，上一轮 fetch() 还没结束，页面却把旧结果渲染了出来。解决这类问题时，AbortController 不只负责“取消”，还可以把取消原因一路传到 catch，让代码分开处理用户主动取消、超时和真正的网络故障。

官方文档：https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort

核心做法是：给每次请求创建新的 controller，把 signal 传给 fetch，调用 abort(reason) 时传入稳定的错误值；捕获时先判断 AbortError、TimeoutError 或业务原因，再处理其他异常。

先把取消原因设计成可判断的值

abort() 的参数不是日志备注，而是异步操作的拒绝原因。最省事的写法是传字符串，例如 controller.abort('route-change')，但这样进入 catch 的可能是字符串，直接读取 err.name 就会失去区分能力。实际项目里我更愿意使用名称稳定的 DOMException，或者使用带 kind 字段的对象。

让 abort(reason) 沿着 fetch 传到 catch

请求开始前创建 controller，把它的 signal 放进 Fetch 选项；取消按钮只负责调用 abort()。同一个 signal 一旦变成 aborted，就不要拿去复用下一次请求。

async function loadSuggest(keyword, onCancel) {
  // 每次请求使用新的 controller，避免复用已经 aborted 的 signal。
  const controller = new AbortController();
  const { signal } = controller;

  // 将取消动作交给调用方，例如输入框的清理函数或取消按钮。
  onCancel(() => {
    controller.abort(new DOMException('搜索词已变化', 'AbortError'));
  });

  try {
    // signal 会把取消状态传递给 Fetch 和响应体读取过程。
    const response = await fetch(`/api/suggest?q=${encodeURIComponent(keyword)}`, { signal });
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return await response.json();
  } catch (err) {
    // DOMException 有 name；自定义字符串或对象则按约定字段处理。
    if (err?.name === 'AbortError' || err === signal.reason) {
      return { cancelled: true };
    }
    throw err;
  }
}

这里的关键不是把所有异常都吞掉，而是只吸收明确的取消分支。HTTP 404、500 不会让 fetch 自动 reject，所以仍然要先检查 response.ok，否则“请求成功返回错误页面”和“请求被取消”会混在一起。

用错误类型区分用户取消、超时和网络失败

只需要超时控制时，可以直接使用 AbortSignal.timeout(5000)。MDN 当前文档说明，超时会以名称为 TimeoutError 的 DOMException 拒绝；用户调用 controller 取消时通常是 AbortError。因此分支顺序应先处理这两类，再把未知异常交给统一错误上报。

async function requestWithTimeout(url) {
  try {
    // 超时信号只服务这一轮请求，不要跨请求保存。
    const response = await fetch(url, {
      signal: AbortSignal.timeout(5000),
    });
    return await response.json();
  } catch (err) {
    // 超时可重试，用户取消通常不需要显示错误。
    if (err?.name === 'TimeoutError') return { retryable: true };
    if (err?.name === 'AbortError') return { cancelled: true };
    // 其他情况可能是 DNS、断网或 CORS 等网络层问题。
    throw err;
  }
}

不要用 err.message 判断分支：浏览器、语言环境和自定义 reason 都可能改变文案。对跨层封装来说，固定 name 或业务字段更适合记录和测试。

组合信号时保留可追踪边界

搜索框既可能被用户输入取消，也可能因超时结束，可以用 AbortSignal.any() 合并外部信号和超时信号：

async function fetchProfile(url, userSignal) {
  const timeoutSignal = AbortSignal.timeout(4000);
  // 任一信号 aborted，组合 signal 就会 aborted。
  const signal = AbortSignal.any([userSignal, timeoutSignal]);

  try {
    const response = await fetch(url, { signal });
    return await response.json();
  } finally {
    // 若这里额外注册了 abort 监听器，应在 finally 中移除。
    // Fetch 自身的内部监听不需要由业务代码清理。
  }
}

组合后的 signal 只告诉你“其中一个原因先发生了”，不能可靠回答究竟是用户取消还是超时。若产品必须展示不同文案，可在业务层保留两个 controller 的状态，或让统一的 reason 对象先在业务边界被记录。这样既享受组合信号的简洁，又不会丢失诊断线索。

兼容处理也很简单：在需要支持较老浏览器时先检查 AbortController、AbortSignal.timeout 和 AbortSignal.any 是否存在；缺少后两者时退回手动 setTimeout + controller.abort(new DOMException('请求超时', 'TimeoutError'))，并用 clearTimeout 清理定时器。不要把同一个 controller 放进全局单例，否则一次取消会影响后续所有请求。

相关问题

不传 reason 时 catch 收到什么？

规范默认使用名称为 AbortError 的 DOMException。代码可以通过 err.name === 'AbortError' 判断，但仍应保留其他异常分支。

abort(reason) 会取消已经返回的 Response 吗？

如果响应对象已经返回但响应体尚未读完，取消后继续调用 response.text() 或类似方法仍可能因 AbortError 拒绝，所以要把 signal 的生命周期覆盖到正文读取结束。

AbortSignal 能不能重复用于多次 fetch？

可以传给多个尚未开始的关联操作，但一旦 signal aborted，之后使用它的 Fetch 会立即被拒绝。更稳妥的做法是每个用户任务创建一个新的 controller。