深入解析 Graffle anyware 的 pack 钩子与 body 插槽:如何改写 GraphQL 请求体
深入解析 Graffle anyware 的 pack 钩子与 body 插槽:如何改写 GraphQL 请求体
Graffle 是 JavaScript 生态中一个极简、可扩展、类型安全的 GraphQL 客户端,其 anyware 机制让开发者可以像中间件一样介入请求管线的每个环节。本篇以官方示例 "Slot Body"(示例页面)为骨架,系统讲解在 pack 钩子上通过 body 插槽定制 POST 请求体的完整用法,并深入到请求管线与 HTTP 传输扩展的源码实现,帮助你掌握利用 anyware 改写请求体、控制 operationName 的实战能力。
背景:anyware 与请求管线的五个钩子
在使用 body 插槽之前,需要先理解 anyware 所围绕的请求管线。Graffle 的每次请求都会依次经过五个阶段,这在 src/requestPipeline/RequestPipeline.ts 中由 stepName 常量定义:
| 钩子 | 职责 |
|---|---|
encode |
依据 Schema 驱动数据映射(SDDM)与标量配置,将请求变量编码、规范化查询 |
pack |
将请求打包成传输层需要的形态(HTTP 请求方法、URL、请求体等) |
exchange |
执行真正的传输交互(如调用 fetch) |
unpack |
拆解传输层响应(如解析 JSON) |
decode |
解码结果数据并返回最终执行结果 |
anyware 允许你在任意钩子上注入中间件:既可以像 anyware_jump-start__jump-start.ts 那样跳过前序钩子直接从 exchange 起步,也可以像 anyware_short-circuit__short-circuit.ts 那样提前短路。而本篇文章的主角——body 插槽,正是 pack 钩子暴露的定制点之一。
什么是 pack 钩子上的 body 插槽
在 Graffle 中,pack 步骤负责把内部请求对象转换为传输层请求。对于 HTTP 传输(POST 模式)而言,最终发出去的请求体默认是一段 JSON 字符串。body 插槽就是 pack 阶段用来生成这段请求体的扩展点:
- 它的输入是一个
graphqlRequest对象,包含operationName、variables和query字段; - 它的返回值会被直接用作
fetch的body(BodyInit)。
在 TransportHttp.ts 中可以看到,HTTP 传输为 pack 注册了两个插槽:searchParams 与 body,其中 body 的默认实现是 postRequestEncodeBody(POST 模式下的请求体编码函数)。实际组装请求时,run 函数会调用 slots.body(graphqlRequest) 来产出 POST 请求体(见 TransportHttp.ts 附近源码)。换句话说:你通过 using 提供的 body 函数会覆盖默认编码逻辑,成为最终请求体的唯一来源。
官方示例:改写 operationName 让服务器执行另一条查询
下面就是 "Slot Body" 示例的完整可运行代码(仓库源码见 anyware_slot_slot-body__slot-body.ts):
import { Graffle } from 'graffle'
const graffle = Graffle
.create()
.transport({ url: `http://localhost:3000/graphql` })
.anyware(async ({ pack }) => {
return await pack({
using: {
body(graphqlRequest) {
return JSON.stringify({
...graphqlRequest,
operationName: `trainers`,
})
},
},
})
})
const result = await graffle.gql(`
query pokemons {
pokemons { name }
}
query trainers {
trainers { name }
}
`)
.pokemons()
console.log(result)
逐行拆解这段代码:
- 创建客户端并配置传输:
.transport({ url })指定 GraphQL 端点,默认使用 POST 模式(methodMode默认值为post,见 TransportHttp.ts)。 - 注册 anyware 中间件:
.anyware(async ({ pack }) => ...)解构出pack钩子。 - 调用
pack并传入using:pack({ using: { body(...) } })中using是一个"插槽覆盖"配置对象,这里提供了自定义的body函数。 - 改写请求体:函数接收
graphqlRequest,通过展开运算符保留原始字段,仅把operationName强制改为trainers,再JSON.stringify序列化为字符串。 - 发出请求:虽然链式调用选择的是
.pokemons(),但由于请求体中的operationName已被改写为trainers,服务器实际执行的是trainers查询。
最终控制台输出(仓库中的记录见 anyware_slot_slot-body__slot-body.output.txt):
{
trainers: [
{ name: 'Ash' },
{ name: 'Misty' },
{ name: 'Brock' },
{ name: 'Gary' }
]
}
这正是 body 插槽的核心价值:在请求真正发出前,你有机会对请求体做任意改写——换操作、注入自定义字段、加密、压缩、调整标量序列化方式等。
工作原理:body 插槽在源码中的调用链
为了准确理解插槽被调用的时机,我们可以追踪源码中的关键链路:
- 在 RequestPipeline.ts 中,管线明确定义了
encode → pack → exchange → unpack → decode五个步骤,其中pack步骤的输出(PackInput)携带内部请求对象与上下文状态。 - 在 TransportHttp.ts 中,HTTP 传输的
pack步骤先把内部请求整理成graphqlRequest(含operationName、variables、query),然后根据methodMode与操作类型决定 HTTP 方法:- POST 时:
body: slots.body(graphqlRequest),即请求体来自body插槽; - GET(
getReads)时:改用slots.searchParams(graphqlRequest)把负载拼进 URL 查询参数。
- POST 时:
- 自定义的
body插槽通过pack({ using: { body } })注入后,会在该步骤运行时被调用,返回的字符串直接成为fetch的body。
从源码结构可以推断:using 中的插槽覆盖是按钩子粒度生效的,body 只影响请求体生成环节,不会干扰 encode(变量编码)与 exchange(网络交互)等其余阶段,因此你可以只定制请求体而保留其他默认行为。
对比实战:body 插槽与 searchParams 插槽
body 并非 pack 钩子唯一的插槽。当传输配置为 methodMode: 'getReads' 时,Graffle 会把请求负载放进 URL 查询参数,对应的插槽是 searchParams。仓库中的姊妹示例 anyware_slot_slot-body__slot-search-params.ts 展示了这种用法:
const graffle = Graffle
.create()
.transport({ url: `http://localhost:3000/graphql`, methodMode: `getReads` })
.anyware(async ({ pack }) => {
return await pack({
using: {
searchParams: (graphqlRequest) => {
return {
query: graphqlRequest.query,
operationName: `getPokemons`,
}
},
},
})
})
两个插槽的差异可以总结为:
| 插槽 | 适用场景 | 返回值 | 影响对象 |
|---|---|---|---|
body |
POST 请求 | BodyInit(通常是 JSON 字符串) |
请求体 |
searchParams |
getReads 模式下的 GET 请求 |
查询参数对象(含 query、operationName 等) |
URL 查询字符串 |
值得注意的是,getReads 模式下只有读取操作(read 类)走 GET,写入操作仍回退为 POST(见 TransportHttp.ts 的请求方法决策逻辑)。因此如果你的客户端同时存在读写操作,body 插槽仍然会用于其中的 POST 请求。
更多插槽:exchange 钩子上的 fetch 插槽
pack 之外,其他钩子也有各自的插槽,理解它们有助于建立完整的 anyware 心智模型。例如 anyware_slot_slot-fetch__slot-fetch.ts 演示了在 exchange 钩子上覆盖 fetch 插槽——完全接管网络请求,直接返回一个伪造的 Response:
const graffle = Graffle
.create()
.transport({ url: `http://localhost:3000/graphql` })
.anyware(async ({ exchange }) => {
return await exchange({
using: {
fetch: () => {
return new Response(JSON.stringify({ data: { trainers: [{ name: `Jason` }] } }))
},
},
})
})
在 TransportHttp.ts 中可以看到,exchange 步骤默认调用 slots.fetch(url, init) 发起网络请求;覆盖它之后,整个"网络往返"都被替换为本地模拟。这通常用于测试、缓存或离线场景,与 body 插槽形成互补:body 改请求体,fetch 改请求执行本身。
实战进阶:Upload 扩展如何复用 body 插槽
body 插槽不仅出现在官方示例中,Graffle 自带的 Upload 扩展(src/extensions/Upload/Upload.ts)也用它实现了 multipart/form-data 文件上传。当检测到请求变量中包含 Blob 实例时(isUploadRequest),Upload 扩展通过 pack({ using: { body(input) { ... } } }) 覆盖 body 插槽,返回 createBody({ query, variables }) 生成的 multipart 表单体,同时清空 content-type 头,让 fetch 根据 FormData 自动设置带 boundary 的 Content-Type。
这说明一个重要的工程结论:anyware 的插槽是 Graffle 自身扩展系统的公共机制——内置扩展和用户代码使用完全相同的 API,你在掌握 body 插槽后,既可以直接写中间件,也可以借此理解甚至编写自定义扩展。
类型安全与测试保障
从源码测试可以看出这套机制在类型层面的严谨性。在 src/client/methods/anyware.test.ts 中:
anyware中间件会被收集到requestPipelineInterceptors,且不影响客户端上下文类型;- 在
pack钩子内可以通过pack.input.transportType精确判断当前使用的传输(存在多个传输时,类型会被推断为联合类型),便于在中间件中针对 HTTP 传输做条件处理。
这意味着你在编写 body 插槽时,graphqlRequest 参数具备完整的类型提示;而测试文件本身也验证了 anyware 中间件注册与调用的正确性,你可以参照它为自己的中间件编写类型断言与行为测试。
小结
围绕 Graffle 官方 "Slot Body" 示例,本文覆盖了以下核心内容:
- 管线模型:
encode → pack → exchange → unpack → decode五个钩子,pack负责打包传输请求; body插槽:pack({ using: { body(graphqlRequest) {...} } })可完全接管 POST 请求体生成,示例中通过改写operationName让服务器执行目标查询;- 源码依据:默认实现与调用点位于 TransportHttp.ts 的
pack步骤(slots.body(graphqlRequest)),管线定义位于 RequestPipeline.ts; - 横向对比:
body(POST)与searchParams(GET)分别定制请求体与 URL 参数,exchange.fetch则可替换整个网络执行; - 真实案例:Upload 扩展内部同样借助
body插槽实现 multipart 上传,证明该机制是 Graffle 扩展体系的标准入口。
掌握了 body 插槽,你就掌握了 Graffle anyware 中"请求出站前最后一公里"的控制权。想要继续深入,建议依次阅读仓库中的 slot-fetch 示例、slot-search-params 示例 以及 jump-start 示例,并结合 anyware 测试 与 HTTP 传输源码 验证你的理解。