Graffle 自定义 Fetch:用 Anyware 覆盖 exchange 钩子实现请求注入与 Mock
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 属性赋值。
注意事项与最佳实践
- 响应的结构必须合法:Mock 返回的 JSON 顶层应为
{ data }(或包含errors),字段名需匹配查询。文档示例中查询{ pokemons { name } },但 Mock 返回data.pokemon(单数)——管线按字符串查询解析并解码,这里展示的是输出层面的"被 Mock 后的结果",实际项目中请保持查询与 Mock 字段一致,或直接用文档中的输出作为演示数据。 - 相对 URL 的限制:
TransportHttp支持相对路径 URL(如/api/graphql、./graphql、../graphql),但 Node.js 原生 fetch 不支持相对 URL,只有浏览器环境或提供增强 fetch 的框架(如 SvelteKit)才可用。这也是在那些场景中覆写fetch槽位的典型动机。 raw配置的优先级:transport.raw会直接透传并覆盖其它 transport 配置(例如把raw.method设为PATCH会覆盖methodMode导致非法 GraphQL over HTTP 请求),使用需谨慎。- 测试友好:
exchange钩子的input.request携带完整的url、headers、body等请求信息,你可以在自定义 fetch 内断言这些值,或按请求内容返回不同响应,实现条件化 Mock。
相关资源
- 示例源码:examples/10_transport-http/transport-http_extension_fetch__custom-fetch.ts
- 传输扩展实现:src/extensions/TransportHttp/TransportHttp.ts
- 传输扩展完整文档:src/extensions/TransportHttp/documentation.md
- 请求管线定义:src/requestPipeline/RequestPipeline.ts
- Anyware 测试:src/client/methods/anyware.test.ts
- 更多 Anyware 示例:examples/50_anyware