Web AbortController.abort 怎样保留取消原因

页面切换、搜索词变化或弹窗关闭时，我们经常需要取消尚未完成的 fetch。只调用 controller.abort() 时，浏览器会使用默认的 AbortError；如果希望业务层知道“是切页取消，还是用户点了取消”，应该把结构化值传给 abort(reason)，再从同一个 AbortSignal 读取 reason。

下面的范围只覆盖 AbortController、AbortSignal 和 fetch 的取消原因传递，不讨论框架封装和重试策略。

先把取消原因写进 signal

abort(reason) 的参数可以是任意 JavaScript 值。工程代码更适合传一个带 code 的对象，而不是把一段只能靠字符串匹配的提示语塞进去。没有显式传参时，signal.reason 会得到名为 AbortError 的默认 DOMException。

function createRequest(url) {
  // 每个请求创建自己的 controller，避免把已取消的 signal 带到下一次请求。
  const controller = new AbortController();

  const promise = fetch(url, { signal: controller.signal });

  return {
    promise,
    signal: controller.signal,
    cancel() {
      // 用稳定的业务码表达取消来源，reason 也可以是 Error 或其他值。
      controller.abort({
        code: "route-change",
        message: "用户切换了页面",
      });
    },
  };
}

const request = createRequest("/api/profile");
request.cancel();
console.log(request.signal.reason.code); // route-change

这里的关键不是 console.log，而是 abort() 和 signal 属于同一个 controller。取消动作发生后，signal.aborted 变为 true，signal.reason 保存传入的对象；未取消时，reason 是 undefined。

在 fetch 的 catch 中先判断 aborted

排查时最容易犯的错，是只写 error.name === "AbortError"。这对默认取消有用，但自定义 reason 可能是普通对象、字符串或自定义 Error。更稳定的判断顺序是：先看当前 signal 是否已经取消，再读取 signal.reason；只有未取消时，才把异常当成网络或 HTTP 之外的真实故障。

async function fetchJson(url, signal) {
  try {
    const response = await fetch(url, { signal });

    // fetch 对 404/500 仍可能正常返回 Response，这里单独处理 HTTP 状态。
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    // 取消可能发生在响应到达后、body 尚未读完之前，所以读取 body 也要在 try 内。
    return await response.json();
  } catch (error) {
    if (signal.aborted) {
      // 使用 signal.reason 作为唯一的业务取消来源，兼容默认和自定义 reason。
      return { kind: "aborted", reason: signal.reason };
    }

    // 未取消才继续抛出网络错误、解析错误或 HTTP 错误。
    throw error;
  }
}

const controller = new AbortController();
const pending = fetchJson("/api/profile", controller.signal);

// 传对象后，业务层可以按 code 静默收尾，而不是显示错误提示。
controller.abort({ code: "dialog-close", message: "关闭资料弹窗" });

pending.then((result) => {
  if (result.kind === "aborted" && result.reason.code === "dialog-close") {
    return;
  }
  renderProfile(result);
});

如果项目需要让取消继续走 Promise 的 rejected 分支，也可以在封装函数里 throw signal.reason。无论采用返回值还是抛出值，都要保持一个约定：取消是可预期控制流，网络失败和数据解析失败仍然是错误。

让业务函数保留 reason，而不是只转成字符串

组件、数据层和请求层之间传递 signal 时，不要在底层把原因改写成固定的“请求失败”。这样上层仍能根据 code 决定是否提示用户、是否清空加载状态，或者是否保留旧数据。

async function loadProfile(url, { signal } = {}) {
  // 在真正发请求前就检查，避免已取消的调用继续初始化资源。
  signal?.throwIfAborted();

  try {
    const response = await fetch(url, { signal });
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    if (signal?.aborted) {
      // 把原始 reason 原样交给调用方，保留 code 和附加字段。
      throw signal.reason;
    }
    throw error;
  }
}

async function refreshProfile() {
  const controller = new AbortController();

  try {
    const profile = await loadProfile("/api/profile", {
      signal: controller.signal,
    });
    renderProfile(profile);
  } catch (reason) {
    if (reason?.code === "route-change") {
      // 页面切换属于正常收尾，不弹出网络错误。
      return;
    }
    showRequestError(reason);
  }
}

throwIfAborted() 会在 signal 已取消时抛出它的 reason，适合放在自定义异步 API 的入口。注意它不是“重置 signal”的方法；一旦 signal 进入 aborted 状态，就应该让这次操作结束并创建新的 controller。

四个排查点：复用、读取、超时与组合

• 不要复用已取消的 signal。同一个 signal 只能服务一次生命周期；把它传给下一次 fetch，新请求会立即被拒绝。把 controller 放在请求函数内部，通常最容易保证边界清楚。
• 不要只在 fetch 外层读取结果。响应头到达后，fetch 可能已经 fulfilled，但后续 response.json() 或 response.text() 仍可能因取消而失败。
• 区分默认 reason 和业务 reason。无参数 abort() 得到默认 AbortError；显式 reason 可以是对象。日志中建议同时记录 reason.code 和请求上下文，避免依赖错误信息文本。
• 组合 signal 时保留来源意识。AbortSignal.timeout(5000) 的超时原因是 TimeoutError。AbortSignal.any() 可以把多个 signal 合成一个，但最终 signal 本身不能额外告诉你到底是哪一个来源先触发；需要精细业务分类时，额外维护自己的来源标记。

function requestWithTimeout(url, userSignal) {
  // timeoutSignal 只负责超时，userSignal 代表用户主动取消。
  const timeoutSignal = AbortSignal.timeout(5000);
  const signal = AbortSignal.any([userSignal, timeoutSignal]);

  return fetch(url, { signal }).catch((error) => {
    if (!signal.aborted) {
      throw error;
    }

    // 读取最终 signal 的 reason；若要精确区分来源，应在业务层同步记录来源。
    throw signal.reason;
  });
}

最后用这份清单复查

遇到“取消了但不知道为什么”时，按这个顺序看：是否把 reason 传给了 abort()；catch 是否先检查了 signal.aborted；是否在读取响应体时仍处于 try 范围；是否把已取消的 signal 传给了下一次请求；使用 timeout 或 any 时，业务是否记录了自己的来源码。

最小原则可以浓缩成一句话：abort(reason) 负责写入原因，signal.reason 负责读取原因，业务层负责解释原因；不要用 error.message 代替这条链路。

相关问题

不传 reason 时，应该判断什么？

可以判断 signal.aborted，再检查 signal.reason?.name === "AbortError"。如果业务将来需要区分多种取消来源，建议从一开始就传带 code 的对象。

为什么 fetch 成功了，读取 JSON 仍会被取消？

响应头和响应体是两个阶段。fetch 返回 Response 不代表 body 已经读完；取消发生在 json() 或 text() 期间时，读取 Promise 仍可能拒绝，所以 body 读取也应处于同一套取消处理范围。