Graffle 自定义 Fetch:用 Anyware 覆盖 exchange 钩子实现请求注入与 Mock

原创2026-10-09 19:01:473,367 阅读
文章标签:后端

Graffle 自定义 Fetch:用 Anyware 覆盖 exchange 钩子实现请求注入与 Mock

导读

本篇技术指南讲解 Graffle 客户端(Simple GraphQL Client for JavaScript)中一个非常实用的扩展能力:通过 Anyware 中间件体系,用 exchange({ using: { fetch } }) 覆盖 HTTP 传输层默认的 fetch 实现,从而实现对 GraphQL 请求的自定义注入、离线 Mock、测试替身或框架增强 fetch 的挂载。读完本文,你将掌握 Graffle 请求管线的 exchange 钩子机制、using 槽位覆写语法,并能独立编写出一个不依赖真实网络即可返回数据的 Graffle 客户端。

本文对应的原始示例文档位于 website/content/_snippets/examples/transport-http/custom-fetch.detail.md,同主题的可运行示例源码见 examples/10_transport-http/transport-http_extension_fetch__custom-fetch.ts。

为什么需要自定义 Fetch

Graffle 的 HTTP 传输层(TransportHttp 扩展)在发送 GraphQL 请求时,默认调用的是平台原生 fetch。但在真实工程中,我们常常希望拦截或替换这一步:

  • 单元测试 / Mock 数据:不想真的发起网络请求,而是返回预设的响应体,验证客户端解析与类型层行为;
  • 离线演示 / 快速原型:后端尚未就绪时,用一段固定的 JSON 假数据驱动前端开发;
  • 框架增强 fetch:例如在 SvelteKit 的 load 函数中使用框架提供的、可解析相对 URL 的增强版 fetch(官方文档 src/extensions/TransportHttp/documentation.md 中给出了专门的 SvelteKit 集成示例);
  • 自定义传输协议:将请求改道到内存传输、本地缓存或 Web Worker 等非标准通道。

Graffle 的 Anyware 机制专门为此设计:你不必修改传输层源码,只需在客户端构建链上挂一个中间件,在 exchange 钩子上覆写 fetch 槽位即可。

完整示例:用 Mock Response 替换真实网络请求

下面是被引用文档(custom-fetch.detail.md)与仓库示例 transport-http_extension_fetch__custom-fetch.ts 中的核心代码。它创建了一个 Graffle 客户端,把 fetch 完全替换成一个返回固定 Mock 数据的函数:

// 网站环境使用 Vitepress + Twoslash,Twoslash 无法自动发现生成的 Graffle 模块,
// 因此需要显式导入全局模块;在你的应用工程中通常无需此行。
import './graffle/modules/global.js'
// ---cut---

import { Graffle } from 'graffle'

const graffle = Graffle
  .create()
  .transport({ url: `http://localhost:3000/graphql` })
  .anyware(({ exchange }) =>
    exchange({
      using: {
        fetch: async () => {
          return new Response(JSON.stringify({ data: { pokemon: [{ name: `Pokemon Mocked!` }] } }))
        },
      },
    })
  )

const data = await graffle.gql('{ pokemons { name } }').$send()

console.log(data)

程序输出如下(即文档中的预期结果):

{
  "pokemon": [
    {
      "name": "Pokemon Mocked!"
    }
  ]
}

仓库中的可运行版本 transport-http_extension_fetch__custom-fetch.ts 与该片段等价,只是把 url 换成了仓库自带的公共测试端点 publicGraphQLSchemaEndpoints.Pokemon(定义于 examples/$/helpers.ts),并用 showJson 输出结果。

逐段拆解:每一步都在做什么

1. 创建客户端与配置传输

const graffle = Graffle
  .create()
  .transport({ url: `http://localhost:3000/graphql` })
  • Graffle.create() 返回一个基于 preset 的客户端实例;
  • .transport({ url }) 配置 HTTP 传输。TransportHttp 扩展的配置项还包括 methodMode(post / getReads,默认 post)、headers 与 raw(直接透传给 fetch 的 RequestInit),全部配置项定义在 src/extensions/TransportHttp/TransportHttp.ts 的 ConfigurationInput 中。

2. 挂载 Anyware,覆写 exchange 的 fetch 槽位

.anyware(({ exchange }) =>
  exchange({
    using: {
      fetch: async () => {
        return new Response(JSON.stringify({ data: { pokemon: [{ name: `Pokemon Mocked!` }] } }))
      },
    },
  })
)

这里使用了 Anyware 的 hook + slot 语法:

  • anyware 回调接收当前钩子(这里解构出 exchange);
  • exchange({ using: { fetch } }) 表示:继续执行 exchange 钩子,但把该钩子内部的 fetch 槽位(slot) 替换为我们提供的实现;
  • using 是“覆写槽位实现”的入口。默认情况下,TransportHttp 在 exchange 钩子上注册的 fetch 槽位实现是 (url, init) => fetch(url, init)——也就是平台原生 fetch(见源码 TransportHttp.ts);
  • 我们的替换函数签名与原生 fetch 兼容:接收 (url, init) 参数,返回 Response。这里直接 new Response(...) 构造一个模拟的 HTTP 响应对象,Response 是浏览器与 Node 18+ 均内置的标准 API。

3. 发送查询并获取数据

const data = await graffle.gql('{ pokemons { name } }').$send()
  • .gql('{ pokemons { name } }') 以 GraphQL 字符串形式声明查询;
  • .$send() 触发完整的请求管线。由于 fetch 已被替换,管线不会真正访问 http://localhost:3000/graphql,而是直接把 new Response(...) 当作服务器应答继续向下处理(解析 JSON、按 Schema 解码),最终返回:
{
  "pokemon": [
    { "name": "Pokemon Mocked!" }
  ]
}

注意:Mock 响应的 JSON 结构必须符合 GraphQL 执行结果(execution result)的约定——顶层为 { data: ... },data 内字段名要与查询的根字段对应,否则管线在 unpack/decode 阶段会解析失败。

底层原理:请求管线与 exchange 钩子

要真正理解自定义 fetch 为什么能生效,需要了解 Graffle 的请求管线(Request Pipeline)。管线定义在 src/requestPipeline/RequestPipeline.ts,共五个步骤:

步骤 职责
encode 依据 Schema-Driven Data Map 编码请求变量与查询
pack 组装传输层所需的 url、headers、body
exchange 真正发起请求(默认调用 fetch),拿到 response
unpack 从 response 解析 JSON,得到执行结果
decode 依据 Schema 解码结果数据与标量类型

TransportHttp 扩展正是围绕这条管线挂载的:它在 pack 阶段注入 URL/Headers/Body 编码槽位,在 exchange 阶段提供 fetch 槽位,在 unpack 阶段解析响应(见 TransportHttp.ts)。

exchange 钩子的核心实现非常直观:

.exchange({
  slots: {
    fetch: (url: string | URL, init?: RequestInit): Prom.Maybe<Response> => fetch(url, init),
  },
  async run(input, slots) {
    const response = await slots.fetch(input.request.url.value, input.request)
    return { ...input, response }
  },
})

也就是说:fetch 是 exchange 钩子的一个可替换槽位,钩子运行时通过 slots.fetch(...) 调用它。当我们用 anyware 写 exchange({ using: { fetch: myFetch } }) 时,就等价于把默认的 (url, init) => fetch(url, init) 换成了 myFetch,随后的 run 逻辑(拿 response、交给 unpack 解析)完全不变。这就是"最小侵入、类型安全"的扩展设计:你只需替换一个函数,就接管了整个网络层。

进阶玩法:与其它 Anyware 示例组合

自定义 fetch 只是 exchange 钩子能力的冰山一角,仓库中还有大量同族示例可供组合:

  • 短路(short-circuit):在 exchange 钩子修改请求头后直接结束(跳过 unpack、decode),或者条件性地放行不同传输;
  • slot-body / slot-search-params:覆写 pack 阶段的 body、searchParams 槽位,自定义请求载荷编码;
  • slot-fetch:与本文同源的 fetch 槽位覆写专题。

例如在 SvelteKit 中,官方文档建议这样把框架的增强 fetch 挂进客户端(见 src/extensions/TransportHttp/documentation.md):

const client = GraffleBare
  .create()
  .use(TransportHttp)
  .transport({ url: '/api/graphql' })
  .anyware(({ exchange }) => {
    exchange.fetch = fetch   // 使用 SvelteKit 的增强 fetch
    return exchange()
  })

注意这里与 using 语法是等价的两种写法:既可以 exchange({ using: { fetch } }) 传覆写配置,也可以直接对钩子对象上的 exchange.fetch 属性赋值。

注意事项与最佳实践

  1. 响应的结构必须合法:Mock 返回的 JSON 顶层应为 { data }(或包含 errors),字段名需匹配查询。文档示例中查询 { pokemons { name } },但 Mock 返回 data.pokemon(单数)——管线按字符串查询解析并解码,这里展示的是输出层面的"被 Mock 后的结果",实际项目中请保持查询与 Mock 字段一致,或直接用文档中的输出作为演示数据。
  2. 相对 URL 的限制:TransportHttp 支持相对路径 URL(如 /api/graphql、./graphql、../graphql),但 Node.js 原生 fetch 不支持相对 URL,只有浏览器环境或提供增强 fetch 的框架(如 SvelteKit)才可用。这也是在那些场景中覆写 fetch 槽位的典型动机。
  3. raw 配置的优先级:transport.raw 会直接透传并覆盖其它 transport 配置(例如把 raw.method 设为 PATCH 会覆盖 methodMode 导致非法 GraphQL over HTTP 请求),使用需谨慎。
  4. 测试友好:exchange 钩子的 input.request 携带完整的 url、headers、body 等请求信息,你可以在自定义 fetch 内断言这些值,或按请求内容返回不同响应,实现条件化 Mock。

相关资源

登录后查看全文
graffle