Graffle Anyware Slots 实战:用 body、searchParams 与 fetch 插槽精确定制 GraphQL 请求管线

原创2026-10-09 20:00:181,680 阅读
文章标签:后端

Graffle Anyware Slots 实战:用 body、searchParams 与 fetch 插槽精确定制 GraphQL 请求管线

Graffle 是一款极简、可扩展、类型安全的 JavaScript GraphQL 客户端。本文聚焦其 anyware 扩展机制中最精细的操控层——Slots(插槽):它允许你在请求管线(Request Pipeline)的特定挂载点上,以最小粒度改写 GraphQL 请求的 body、查询参数甚至直接接管网络请求本身。读完本文,你将掌握 pack 钩子上的 body 与 searchParams 插槽、exchange 钩子上的 fetch 插槽的完整用法,并能结合源码理解这些插槽在请求生命周期中的真实位置与执行时机。

关联示例速览

本文对应的核心示例位于仓库 examples/50_anyware 目录,共三个,分别演示三个不同插槽的用法:

示例文件 演示的钩子 演示的插槽 典型场景
anyware_slot_slot-body__slot-body.ts pack body 改写发送给服务器的请求体(如注入 operationName)
anyware_slot_slot-body__slot-search-params.ts pack searchParams 改写 GET 请求的查询字符串参数
anyware_slot_slot-fetch__slot-fetch.ts exchange fetch 完全接管/模拟网络请求,返回自定义 Response

三个示例的 Markdown 版本文档分别位于 website/content/examples/50_anyware/slot-body.md、website/content/examples/50_anyware/slot-search-params.md 与 website/content/examples/50_anyware/slot-fetch.md,均可对照阅读。

先理解 Anyware 与 Slot:请求管线的"钩子"与"插槽"

在进入代码之前,需要先建立两个核心概念:Hook(钩子) 与 Slot(插槽)。

Graffle 的 anyware 机制将一次 GraphQL 请求拆分为一条可插拔的管线。从仓库中的相邻示例 anyware_jump-start__jump-start.ts 与 anyware_short-circuit__short-circuit.ts 可以看到,管线由以下钩子按顺序组成:

encode → pack → exchange → unpack → decode
  • encode:将 GraphQL 请求编码为可传输的形态(如构造 HTTP 请求)。
  • pack:对即将发出的请求做最终"打包",此时可以改写 body、headers、searchParams 等请求载体。
  • exchange:真正执行网络交换(发送请求、接收响应),也可在此完全替换掉默认的传输行为。
  • unpack:将收到的响应拆包为内部数据。
  • decode:解码为最终结果。

Slot 是钩子内部更细粒度的挂载点。当你使用 pack({ using: { body: ... } }) 时,body 就是 pack 钩子暴露的一个插槽——你只替换"如何生成 body"这一环节,其余管线逻辑照常运行。这种设计让"微调请求"不必重写整个钩子,既精准又低侵入。

插槽一:在 pack 钩子上改写请求体(body slot)

完整示例

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)

(完整可运行版本见 anyware_slot_slot-body__slot-body.ts,其中 transport URL 取自项目内置的 publicGraphQLSchemaEndpoints.Pokemon 公共测试端点。)

运行输出

{
  trainers: [
    { name: 'Ash' },
    { name: 'Misty' },
    { name: 'Brock' },
    { name: 'Gary' }
  ]
}

原理与要点

  • 请求中声明了两个操作:query pokemons 与 query trainers,最终调用 .pokemons() 选择第一个操作。但 body 插槽返回的 JSON 中显式写入了 operationName: "trainers",服务器据此执行的是 trainers 查询——输出结果证实了这一点。
  • body(graphqlRequest) 接收的参数是当前的 GraphQL 请求对象,你可以在其基础上做展开(spread)后添加或覆盖字段,再 JSON.stringify 序列化为字符串返回。示例中用 ...graphqlRequest 保留原有字段(query 等),仅追加 operationName,是最安全、最不易出错的写法。
  • 这个插槽非常适合:固定 operationName、注入追踪字段、改写 extensions、或对接需要特定 body 形态的服务端。

插槽二:在 pack 钩子上改写查询参数(searchParams slot)

当传输层使用 GET 模式(GraphQL 查询参数放在 URL 查询字符串中)时,searchParams 插槽就是改写 URL 参数的入口。

完整示例

import { Graffle } from 'graffle'

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`,
          }
        },
      },
    })
  })

const result = await graffle.gql(`
    query getTrainers {
      trainers { name }
    }
    query getPokemons {
      pokemons { name }
    }
  `)
  .getTrainers()

console.log(result)

(完整可运行版本见 anyware_slot_slot-body__slot-search-params.ts。)

运行输出

{
  pokemons: [
    { name: 'Pikachu' },
    { name: 'Charizard' },
    { name: 'Squirtle' },
    { name: 'Bulbasaur' },
    { name: 'Caterpie' },
    { name: 'Weedle' }
  ]
}

原理与要点

  • 传输配置中出现了 methodMode: 'getReads':读取类操作走 GET,将 GraphQL 文档编码进 URL 查询字符串。正是这个前提使 searchParams 插槽有意义;若请求走 POST body,则应使用上面的 body 插槽。
  • searchParams(graphqlRequest) 返回一个普通对象(query + operationName),由管线将其序列化拼接为 URL 查询字符串。返回对象的键即 URL 参数名。
  • 与 body 示例异曲同工:调用 .getTrainers() 选择 getTrainers 操作,但插槽将 operationName 覆写为 getPokemons,服务端最终执行并返回的是 pokemons 数据,输出结果即为佐证。
  • 实用场景:固定或重写 operationName、追加 variables、附加认证/版本号参数等。

插槽三:在 exchange 钩子上接管网络请求(fetch slot)

fetch 插槽位于 exchange 钩子内,是网络层最"底层"的接管点——替换掉它,等于完全绕开真实的 HTTP 发送。

完整示例

import { Graffle } from 'graffle'

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` }] } }))
        },
      },
    })
  })

const result = await graffle.gql(`
  query {
    trainers {
      name
    }
  }
`).$send()

console.log(result)

(完整可运行版本见 anyware_slot_slot-fetch__slot-fetch.ts。)

运行输出

{ trainers: [ { name: 'Jason' } ] }

原理与要点

  • fetch 插槽返回一个标准 Web API 的 Response 对象。这里直接以 JSON.stringify 构造了一个内联的 GraphQL 响应({ data: { trainers: [...] } }),从而完全绕开了真实网络——没有任何请求真正发出。
  • 注意本示例调用的是 .$send()(显式发送并返回原始结果),与前面两个示例的领域方法风格(.pokemons()、.getTrainers())不同,两种调用方式都受 anyware 管线保护。
  • 这一插槽的典型用途:单元测试中 mock 网络响应、实现内存/离线传输、插入缓存层、或在返回前对原始响应做统一包装。
  • 与同目录 examples/40_other/transport-memory.ts 的思路一致:Graffle 的传输层本就支持"非 HTTP"形态,fetch 插槽让你在 HTTP 传输之上获得同样的自由度。

源码视角:插槽在请求管线中的位置

从仓库源码结构可以进一步印证上述机制:anyware 的管线实现集中在 src/requestPipeline 目录,其中 RequestPipeline.ts 组织各钩子(encode、pack、exchange、unpack、decode)的编排,而 encode.ts 与 decode.ts 分别承载请求编码与结果解码。

同时,src/context/fragments/transports/dataType/builder.ts 中可以看到传输层以 $Slots extends Ware.StepDefinition.Slots 的泛型约束定义各步骤可用的插槽集合——即"某个钩子上允许挂载哪些插槽"由类型系统静态保证。这意味着:插槽名写错或挂载到不存在的钩子上,会在编译期报错,而非运行时才暴露。

可以推断:当你在 anyware 中使用 pack({ using: { body: ... } }) 时,实际是向 pack 步骤注册了一个仅替换"body 生成"这一子步骤的处理器;exchange({ using: { fetch: ... } }) 同理。这种"钩子内嵌插槽"的分层设计,让请求改写既无需逐行重写整个钩子(对比 anyware_jump-start__jump-start.ts 中手动逐层 encode() → pack() → exchange() 的跳级写法),也无需像 anyware_short-circuit__short-circuit.ts 那样提前短路整条管线——改动面最小,可控性最高。

插槽与跳级、短路的边界

为帮助你选型,这里对比三种 anyware 写法:

  • Slot(本文主题):只替换钩子内的一个子环节(body / searchParams / fetch 等),其余管线完整运行。适合"微调请求"。
  • Jump start(跳级):在 anyware 中直接从 exchange 这类靠后的钩子开始,跳过 encode、pack,适合需要完全自控请求形态、又希望保留 unpack/decode 后处理的情况。见 anyware_jump-start__jump-start.ts。
  • Short circuit(短路):执行到某个钩子(如 exchange)后直接返回结果,跳过 unpack、decode,适合完全接管输出。见 anyware_short-circuit__short-circuit.ts。

实际开发中,优先从 Slot 开始:它能以最小代价满足绝大多数"改请求"需求;只有当需要整体替换请求构造或响应处理逻辑时,才考虑跳级或短路。

小结

  • pack 钩子的 body 插槽改写 POST 请求体,searchParams 插槽改写 GET 查询字符串;二者接收 graphqlRequest,返回序列化后的字符串或参数对象。
  • exchange 钩子的 fetch 插槽返回自定义 Response,可完全接管网络行为,是测试与模拟传输的利器。
  • 插槽能力由类型系统约束(见 src/context/fragments/transports/dataType/builder.ts 中的 Slots 泛型),错误挂载会在编译期被拦截。
  • 三份可运行示例均位于 examples/50_anyware,可直接运行观察输出。
登录后查看全文
graffle