JavaScript AbortController.abort(reason) 实战：取消请求后区分用户操作与超时

搜索框、列表筛选和详情页经常同时发起请求。用户刚选了新条件，旧请求才返回；如果所有取消都被当成“网络失败”，页面就会闪出一条没有意义的错误提示。AbortController.abort(reason) 的价值在于：取消动作仍然只有一条控制链，但可以把原因带到 catch，分别处理主动切换、超时和离开页面。

问题先落到一个搜索请求

假设列表页输入框每次变化都会刷新结果。第一次请求还没有结束，用户又输入了第二个关键词，此时最合理的动作不是等待两个响应竞争，而是取消旧请求。更麻烦的是，用户切换筛选和请求超过 3 秒，本来就是两种不同的产品事件。

下面的封装保留了原始 reason，并让调用方只接收真正需要提示用户的错误：

async function loadResults(url, options = {}) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => {
    controller.abort({ type: "timeout", limit: 3000 });
  }, 3000);

  try {
    const response = await fetch(url, {
      ...options,
      signal: controller.signal
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return await response.json();
  } finally {
    clearTimeout(timeoutId);
  }
}

这里的关键不是定时器，而是 controller.abort({ type: "timeout", limit: 3000 })。reason 可以是字符串、对象或其他 JavaScript 值；用对象能保留阈值，日志里比单独写一条“请求取消”更容易排查。

让 catch 区分用户取消与超时

真正发起请求的地方还要拿到 controller，才能在用户切换条件时取消它。一个简单做法是把上一次请求的控制器放在模块变量里，并在创建新请求前先终止旧请求：

let activeController = null;

async function refreshList(keyword) {
  activeController?.abort({ type: "superseded", keyword });
  activeController = new AbortController();

  const timeoutId = setTimeout(() => {
    activeController?.abort({ type: "timeout", limit: 3000 });
  }, 3000);

  try {
    const response = await fetch(`/api/search?q=${encodeURIComponent(keyword)}`, {
      signal: activeController.signal
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    const reason = activeController.signal.reason;
    if (reason?.type === "superseded") return null;
    if (reason?.type === "timeout") {
      console.warn("搜索超时", reason.limit);
      return { items: [], timedOut: true };
    }
    if (error?.name === "AbortError") return null;
    throw error;
  } finally {
    clearTimeout(timeoutId);
  }
}

这段代码有一个容易忽略的竞态：旧请求的 finally 可能在新请求创建后才执行，因此生产代码不要用共享的 activeController 作为唯一判断依据。更稳妥的写法是把本次控制器保存到局部常量，再比较它是否仍是当前控制器：

let currentController = null;

async function query(keyword) {
  currentController?.abort({ type: "superseded" });
  const controller = new AbortController();
  currentController = controller;

  try {
    const response = await fetch(`/api/search?q=${encodeURIComponent(keyword)}`, {
      signal: controller.signal
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    const reason = controller.signal.reason;
    if (reason?.type === "superseded" || error?.name === "AbortError") return null;
    throw error;
  } finally {
    if (currentController === controller) currentController = null;
  }
}

超时可以用 AbortSignal.timeout()，但先确认边界

如果只需要固定时长的超时，现代浏览器还提供了 AbortSignal.timeout(3000)。它能减少手写定时器，但超时 reason 由平台产生，业务日志若需要统一字段，仍可以保留手写控制器：

const signal = AbortSignal.timeout(3000);

try {
  const response = await fetch("/api/report", { signal });
  return await response.json();
} catch (error) {
  if (error.name === "TimeoutError") {
    console.warn("报表请求超过 3 秒");
  } else if (error.name === "AbortError") {
    console.info("请求被主动取消");
  } else {
    throw error;
  }
}

两种写法不要混成一条不可解释的错误判断。需要业务字段、取消来源或自定义阈值时，用 AbortController；只想给请求加固定时限时，使用 AbortSignal.timeout() 更短。

几个常见坑要在验收时看出来

不要把所有异常都当成取消

网络断开、服务端 500 和主动中止都可能出现在 catch。只检查 error.name 会把业务 reason 丢掉；建议先读当前 controller 对应的 signal.reason，再用 AbortError 作为旧写法回退。

不要复用已经结束的控制器

一个 signal 一旦 aborted，就会一直保持 aborted。把它放在模块全局并反复传给新请求，会让后续请求刚开始就失败。每个独立请求创建一个新的 controller。

取消不等于服务端回滚

取消 fetch 只表示客户端不再等待或消费这条请求；如果服务端已经收到写操作，仍要靠幂等键、事务或服务端取消协议保证数据一致，不能把客户端中止当成业务回滚。

完整验收清单

• 用户快速输入时，旧请求不再覆盖新结果，控制台没有错误提示。
• 人为把接口延迟设为 3 秒以上时，超时分支能记录阈值并返回可识别状态。
• 断网或返回 500 时仍能抛出真正错误，而不是静默吞掉。
• 连续刷新多次后，当前 controller 只指向最后一次请求。
• 目标浏览器中检查 AbortSignal.reason 和 AbortSignal.timeout() 的兼容情况，并准备 AbortError 回退。

相关问题

abort(reason) 不传参数时是什么 reason？

通常会得到一个名为 AbortError 的 DOMException。业务需要区分来源时，应显式传入字符串或对象。

abort(reason) 会返回错误对象吗？

不会，abort() 本身没有返回值。reason 会写入 signal，异步操作在消费结果时以拒绝或中止状态体现。

可以用字符串作为 reason 吗？

可以，但对象更适合携带类型和参数。无论使用哪种形式，都应限制字段内容，避免把隐私或整段响应写入日志。

把取消原因设计成小而稳定的业务协议，前端就能同时处理快速切换、固定超时和页面离开，而不会把正常的用户操作误报成故障。真正需要关注的不是“请求有没有被取消”，而是取消之后页面应该呈现什么状态。