Graffle 请求取消实战:使用 AbortController 中断 GraphQL HTTP 请求

原创2026-10-09 23:58:501,957 阅读
文章标签:后端

Graffle 请求取消实战:使用 AbortController 中断 GraphQL HTTP 请求

本篇技术指南讲解如何在 Graffle(Simple GraphQL Client for JavaScript)中通过 Web 标准 AbortController 主动取消尚未完成的 HTTP 请求。文中以官方 abort 示例为核心,结合 TransportHttp 扩展的源码实现与测试用例,剖析 signal 从客户端配置到 fetch 调用的完整传递链路,以及请求被中断后的错误识别与捕获方式。读完本文你将掌握:如何为单个请求注入中止信号、如何在请求发出后随时取消、如何捕获 "This operation was aborted" 类错误,并了解与之相关的 transport.raw 配置语义与注意事项。

一、示例背景与核心代码

该示例完整演示了 Graffle 中最简洁的请求取消方式:创建 AbortController,将其 signal 通过 .transport({ raw: { signal } }) 传入请求,然后在请求尚未完成时调用 abortController.abort() 主动中断,最后捕获并打印被中断的错误信息。

import { Graffle } from 'graffle'

const abortController = new AbortController()

const graffle = Graffle.create().transport({
  url: `http://localhost:3000/graphql`,
})

const resultPromise = graffle
  .transport({ raw: { signal: abortController.signal } })
  .gql(`
    {
      pokemons {
        name
      }
    }
  `)
  .$send()

abortController.abort()

const result = await resultPromise.catch((error: unknown) => (error as Error).message)

console.log(result)

运行后控制台输出:

This operation was aborted

代码中的 ^ 注释分别标注了 abortController、signal 与 abort() 三个关键点:它们共同构成了「先注入信号、再触发中断」的标准取消流程。完整可运行版本见 examples/10_transport-http/transport-http_abort.ts,其真实输出结果记录在 examples/outputs/10_transport-http/transport-http_abort.output.txt 与对应的 快照文件 中,两者均显示 This operation was aborted。

二、逐行拆解:取消请求的三步走

1. 创建并持有 AbortController

const abortController = new AbortController()

AbortController 是浏览器与 Node.js 共有的 Web 标准 API,其 signal 属性是一个 AbortSignal。调用 abort() 后,所有监听该 signal 的进行中操作都会被要求终止。

2. 把 signal 注入请求

const resultPromise = graffle
  .transport({ raw: { signal: abortController.signal } })
  .gql(`{ pokemons { name } }`)
  .$send()

这里有两个值得注意的点:

  • .transport() 的链式调用位置:示例在 graffle 实例之后、.gql() 之前再次调用 .transport(),属于请求级(per-request)配置,只对本次发送生效,不会污染客户端全局配置。这与在 Graffle.create().transport({...}) 中做全局配置是两条不同的配置路径。
  • raw 透传层:raw 是 TransportHttp 提供给 fetch 的原始 RequestInit 配置,signal 正是 RequestInit 的标准字段之一。正因为 raw 是"零护栏"的透传通道,任何 fetch 支持的能力(包括 signal、mode、credentials 等)都能直接传给底层 fetch。

3. 触发中断并捕获错误

abortController.abort()

const result = await resultPromise.catch((error: unknown) => (error as Error).message)

abort() 一旦调用,与该 signal 关联的请求立即被中止,$send() 返回的 Promise 会以错误形式 reject。示例通过 .catch() 拿到错误对象并取其 message 输出,最终得到 This operation was aborted。

三、底层原理:signal 如何从配置流到 fetch

要理解取消为何生效,需要沿着 TransportHttp 扩展的实现追踪 raw 的传递路径,核心实现位于 src/extensions/TransportHttp/TransportHttp.ts。

1. 配置声明:raw 是 RequestInit 的透传口

TransportHttp 的配置输入类型中明确声明了 raw 字段(见 ConfigurationInput 定义):

export type ConfigurationInput = {
  url?: URL | string | undefined
  methodMode?: MethodMode | undefined
  headers?: HeadersInit | undefined
  raw?: RequestInit | undefined
}

它直接复用了标准 RequestInit 类型,因此 signal、headers、method、mode 等 fetch 选项均可直接放入其中。在配置解析阶段(inputResolver),实现按 raw: input.raw ?? current.raw 进行合并,请求级配置会覆盖实例级配置。

2. Pack 阶段:raw 与基础请求头合并

在 pack 步骤的 run 函数中,实现通过 Http.Req.mergeInit 把基础请求头、raw 配置、显式 headers 按顺序合并为最终的 RequestInit:

const baseRequestInit = Http.Req.mergeInit(
  Http.Req.mergeInit(
    {
      headers: requestMethod === `get` ? getRequestHeadersRec : postRequestHeadersRec,
    },
    input.transport.raw,
  ),
  {
    ...(input.transport.headers !== undefined && { headers: input.transport.headers }),
  },
)

也就是说,raw 中携带的 signal 会被原样并入请求配置;由于 raw 的合并优先级最高,它也能覆盖其他位置的同名字段。

3. Exchange 阶段:携带 signal 调用 fetch

exchange 步骤最终执行底层网络请求(见 exchange.run):

const response = await slots.fetch(input.request.url.value, input.request)

这里的 input.request 就是上一步合并了 raw(含 signal)之后的完整 RequestInit。fetch 收到带 signal 的请求后,一旦 abort() 被调用,fetch 的 Promise 便以 AbortError(消息为 This operation was aborted)reject,并沿请求管线向上传播,最终导致 $send() 的 Promise reject。

4. 中止错误被当作「预期错误」直接抛出

值得注意的是,中止错误不会走 Graffle 常规的 GraphQL 错误包装逻辑,而是被直接抛出。证据在 src/requestPipeline/RequestPipeline.ts 的管线定义中:

passthroughErrorWith: (signal) => {
  return signal.hookName === `exchange` && Err.isAbortError(signal.error)
},

passthroughErrorWith 专门用于识别"用户主动取消请求"这一预期场景:当错误发生在 exchange 钩子且属于中止错误(Err.isAbortError)时,直接以原生错误形式透传给调用方。这也是为什么示例中 catch 拿到的错误消息恰好就是 fetch 层的 This operation was aborted。

四、测试验证:signal 取消在源码中的行为约定

仓库测试对 signal 取消行为有明确断言,见 src/extensions/TransportHttp/TransportHttp.test.ts 中 can set signal 测试分组(构造器方式注入 signal):

const abortErrorMessagePattern = /This operation was aborted|AbortError: The operation was aborted/
test(`to constructor`, async ({ g1 }) => {
  const abortController = new AbortController()
  const g2 = g1.transport({ url, raw: { signal: abortController.signal } })
  const resultPromise = g2.gql('query { id }').$send()
  abortController.abort()
  const { caughtError } = await resultPromise.catch((caughtError: unknown) => ({ caughtError })) as any as {
    caughtError: Error
  }
  expect(caughtError.message).toMatch(abortErrorMessagePattern)
})

测试注释还说明了一个跨环境细节:JSDOM 与 Node.js 产生的中止错误类型存在差异(JSDOM 是普通 Error,Node 是 AbortError),因此断言使用正则同时匹配两种消息。这意味着你在不同运行时捕获到的具体错误类型可能略有不同,但都可以用"检查 message 或错误名"的方式统一处理。

五、实战扩展:超时取消与批量取消

基于 signal 机制可以轻松实现两种高频实战模式。

模式一:请求超时自动取消

利用 AbortSignal.timeout()(现代浏览器与 Node.js 18+ 支持)可以省去手动管理定时器:

import { Graffle } from 'graffle'

const graffle = Graffle.create().transport({
  url: `http://localhost:3000/graphql`,
})

const resultPromise = graffle
  .transport({ raw: { signal: AbortSignal.timeout(5000) } }) // 5 秒超时
  .gql(`{ pokemons { name } }`)
  .$send()

const result = await resultPromise.catch((error: unknown) => (error as Error).message)
console.log(result)

也可以结合 AbortSignal.any([...])(Node.js 20+/较新浏览器)把多个信号组合:超时信号与外部取消信号任一触发都会中止请求。

模式二:复用客户端、按请求注入

如果你希望客户端全局配置 URL,而只在特定请求上启用取消,可采用示例中的"实例级配置 + 请求级 raw"组合方式:

const graffle = Graffle.create().transport({
  url: `http://localhost:3000/graphql`,
})

// 请求 A:不携带 signal,正常发送
const a = graffle.gql(`{ pokemons { name } }`).$send()

// 请求 B:携带 signal,随时可取消
const controller = new AbortController()
const b = graffle
  .transport({ raw: { signal: controller.signal } })
  .gql(`{ pokemons { name } }`)
  .$send()

// 需要时只取消请求 B
controller.abort()

由于请求级配置只影响当前链式调用的这一次发送,这种模式非常适合"大部分请求正常、个别请求可取消"的页面场景(如搜索防抖、离开页面时清理在途请求)。

六、注意事项与配置语义小结

使用 signal 取消请求时,建议同时了解 transport.raw 的整体语义(详见 src/extensions/TransportHttp/documentation.md 与 website/content/examples/10_transport-http/abort.md):

  • raw 优先级最高:在扩展栈、with 配置、构造器配置三层配置中,raw 内的字段会覆盖 transport 下其他同名字段;同样,请求级 .transport() 的 raw 会覆盖实例级配置。
  • raw 零护栏:raw 直接透传 fetch 的 RequestInit,若误设 raw.method 之类字段会覆盖 methodMode 并产生非法的 GraphQL-over-HTTP 请求。使用 signal 不受此影响,因为它不影响请求语义,只负责取消。
  • GET 模式同样支持:methodMode: 'getReads' 下查询走 GET 并携带 URL search params,raw.signal 依然随请求传入 fetch,取消机制保持一致(对应测试见 relative URL with GET method mode 等分组)。
  • 环境差异:Node.js 原生 fetch 不支持相对 URL,浏览器与框架增强 fetch(如 SvelteKit load 函数)才可配合相对路径使用;取消行为本身在浏览器与 Node 均可工作,只是错误对象形态略有差异(见第四节测试注释)。
  • TransportHttp 的可用前提:该扩展已包含在 minimal 与 basic 预设中,因此 Graffle.create() 开箱即可使用 .transport({ raw: { signal } });若使用 bare 预设,则需要先通过 GraffleBare.create().use(TransportHttp) 显式引入该扩展。

七、小结

Graffle 的请求取消能力完全建立在 Web 标准之上:AbortController 提供信号,transport.raw 负责透传,TransportHttp 的 pack/exchange 步骤把 signal 并入最终 fetch 调用,RequestPipeline 再把中止错误作为预期错误直接抛出。整条链路清晰、零魔法,示例代码、输出快照与单元测试相互印证,让你可以放心地在生产代码中用它实现超时、防抖与页面卸载清理等场景。相关参考文件:示例 transport-http_abort.ts、实现 TransportHttp.ts、管线 RequestPipeline.ts、测试 TransportHttp.test.ts。

登录后查看全文
graffle