深入解析 Graffle anyware 的 pack 钩子与 body 插槽:如何改写 GraphQL 请求体

原创2026-10-09 17:57:291,955 阅读
文章标签:后端

深入解析 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)

逐行拆解这段代码:

  1. 创建客户端并配置传输:.transport({ url }) 指定 GraphQL 端点,默认使用 POST 模式(methodMode 默认值为 post,见 TransportHttp.ts)。
  2. 注册 anyware 中间件:.anyware(async ({ pack }) => ...) 解构出 pack 钩子。
  3. 调用 pack 并传入 using:pack({ using: { body(...) } }) 中 using 是一个"插槽覆盖"配置对象,这里提供了自定义的 body 函数。
  4. 改写请求体:函数接收 graphqlRequest,通过展开运算符保留原始字段,仅把 operationName 强制改为 trainers,再 JSON.stringify 序列化为字符串。
  5. 发出请求:虽然链式调用选择的是 .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 查询参数。
  • 自定义的 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" 示例,本文覆盖了以下核心内容:

  1. 管线模型:encode → pack → exchange → unpack → decode 五个钩子,pack 负责打包传输请求;
  2. body 插槽:pack({ using: { body(graphqlRequest) {...} } }) 可完全接管 POST 请求体生成,示例中通过改写 operationName 让服务器执行目标查询;
  3. 源码依据:默认实现与调用点位于 TransportHttp.ts 的 pack 步骤(slots.body(graphqlRequest)),管线定义位于 RequestPipeline.ts;
  4. 横向对比:body(POST)与 searchParams(GET)分别定制请求体与 URL 参数,exchange.fetch 则可替换整个网络执行;
  5. 真实案例:Upload 扩展内部同样借助 body 插槽实现 multipart 上传,证明该机制是 Graffle 扩展体系的标准入口。

掌握了 body 插槽,你就掌握了 Graffle anyware 中"请求出站前最后一公里"的控制权。想要继续深入,建议依次阅读仓库中的 slot-fetch 示例、slot-search-params 示例 以及 jump-start 示例,并结合 anyware 测试 与 HTTP 传输源码 验证你的理解。

登录后查看全文
graffle