Graffle 动态请求头实战:用 anyware 拦截 exchange 钩子按请求注入 HTTP Headers

原创2026-10-09 12:21:211,948 阅读
文章标签:后端

Graffle 动态请求头实战:用 anyware 拦截 exchange 钩子按请求注入 HTTP Headers

本篇技术指南聚焦 Graffle(Simple GraphQL Client for JavaScript)中如何借助扩展系统(anyware)在每次请求发出前动态地操作 HTTP 请求头。通过一个可运行的真实示例——为每个 GraphQL 请求注入 X-Sent-At-Time 时间戳头,你将掌握请求管线(Request Pipeline)中 exchange 钩子的用法、anyware 的输入覆盖机制,以及如何在不改动静态配置的前提下实现"请求头按请求动态变化"。

一、为什么需要"动态请求头"

Graffle 的 HTTP 传输扩展(TransportHttp)在配置阶段就支持静态声明请求头:

Graffle.create().transport({
  url: `https://api.example.com/graphql`,
  headers: {
    authorization: `Bearer MY_TOKEN`,
  },
})

这种静态方式适合固定不变的请求头(如认证令牌、固定 Accept)。但很多真实场景需要按请求动态计算请求头,例如:

  • 记录请求发出时间(时间戳每毫秒都不同);
  • 根据当前登录态动态切换 authorization;
  • 注入请求 ID / 追踪 ID(每次请求唯一);
  • 根据查询内容或方法模式(POST/GET)决定是否追加特定头。

面对这类需求,Graffle 提供的答案是 anyware:一种运行在请求管线上的中间件机制,可以拦截、读取并改写管线中每个阶段(hook)的输入与输出。

二、完整示例:动态注入请求头

关联文档 dynamic-headers.detail.md 对应的可运行示例位于 transport-http_extension_headers__dynamicHeaders.ts,站点上的完整展示页为 dynamic-headers.md。核心代码如下:

import { Graffle } from 'graffle'

const graffle = Graffle
  .create()
  .transport({
    url: `http://localhost:3000/graphql`,
  })
  .anyware(({ exchange }) => {
    if (exchange.input.transportType !== `http`) return exchange()
    return exchange({
      input: {
        ...exchange.input,
        request: {
          ...exchange.input.request,
          headers: [
            ...new Headers(exchange.input.request.headers),
            [`X-Sent-At-Time`, Date.now().toString()],
          ],
        },
      },
    })
  })
  .anyware(({ exchange }) => {
    console.log(exchange.input.request)
    return exchange()
  })

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

逐段拆解

  1. 创建客户端并配置传输:.transport({ url }) 声明 GraphQL 端点,此处未声明任何静态请求头。
  2. 第一个 anyware:改写请求头:
    • 通过解构拿到 exchange 钩子(该钩子负责把打包好的请求真正发送出去);
    • exchange.input.transportType 是判别联合(discriminated union)属性,用于按传输类型收窄数据。这里先判断 !== 'http',非 HTTP 传输(如 memory)直接原样放行;
    • new Headers(exchange.input.request.headers) 把当前请求头包装成 Headers 实例,再展开成键值对数组,追加 ['X-Sent-At-Time', Date.now().toString()]。这样既保留原有请求头,又实现了"按请求动态计算"。
  3. 第二个 anyware:观测请求:在修改完成后打印 exchange.input.request,用于确认改动生效。
  4. 发送请求:graffle.gql('{ pokemons { name } }').$send() 发起 GraphQL 查询。

站点文档中的示例代码首行 import './graffle/modules/global.js' 是 Vitepress+Twoslash 环境下的特殊导入,用于让类型检查器发现生成的 Graffle 模块;在普通项目中只需 import { Graffle } from 'graffle' 即可。

三、运行输出解读:请求对象长什么样

示例运行后第二个 anyware 打印出的请求对象(完整输出见 dynamicHeaders.output.txt):

{
  methodMode: 'post',
  headers: [
    [
      'accept',
      'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8'
    ],
    [ 'content-type', 'application/json' ],
    [ 'X-Sent-At-Time', '1762136942519' ]
  ],
  method: 'post',
  url: {
    _tag: 'url',
    value: URL {
      href: 'http://localhost:3000/graphql',
      origin: 'http://localhost:3000',
      protocol: 'http:',
      host: 'localhost:3000',
      hostname: 'localhost',
      port: '3000',
      pathname: '/graphql',
      search: '',
      searchParams: URLSearchParams {},
      hash: ''
    }
  },
  body: '{"query":"{ pokemons { name } }"}'
}

这个输出揭示了 HTTP 传输在 exchange 阶段的请求数据形态:

字段 说明
methodMode 'post' 或 'getReads',来自传输配置的 methodMode(默认 post,见下文源码)
headers 键值对数组。前两项 accept、content-type 是 Graffle 自动生成的默认请求头,第三项 X-Sent-At-Time 正是 our anyware 动态注入的
method 实际 HTTP 方法,post 对应 GraphQL-over-HTTP 的 POST 语义
url 带 _tag: 'url' 的判别联合包装的 URL 对象;相对路径场景下 _tag 则为 'path'
body 序列化后的 JSON 请求体,'{"query":"{ pokemons { name } }"}'

可以清楚看到:动态注入的 X-Sent-At-Time 头被追加到了默认请求头之后,且原有请求头无一丢失——这正是"展开旧头、追加新头"写法的效果。

四、原理纵深:请求管线与 exchange 钩子

4.1 请求管线的五个钩子

Graffle 的每次请求都要经过一条由五个钩子组成的管线。在 RequestPipeline.ts 中定义了它们的名称与顺序:

export const stepName = {
  encode: `encode`,
  pack: `pack`,
  exchange: `exchange`,
  unpack: `unpack`,
  decode: `decode`,
} as const

管线中每个钩子接收输入并返回输出,输出成为下一钩子的输入,最后一个钩子的输出即管线最终结果。anyware 就像运行在管线上的中间件序列——与只包住"单个操作"的传统中间件不同,它包住的是整条"操作序列"。

flowchart LR
  A[encode] --> B[pack] --> C[exchange] --> D[unpack] --> E[decode]

(源码层面该图对应 RequestPipeline.ts 中 steps 的类型定义;站点还提供了一张更完整的请求管线图:graffle-request.svg。)

4.2 exchange 钩子在 HTTP 传输中做什么

对 HTTP 传输而言,各钩子的职责如下(详见 20_request-anyware.md 中的表格):

  • encode:接口层,规范化 GraphQL 请求(含变量编码);
  • pack:传输层,把 GraphQL 请求转换为 HTTP 请求对象(POST 生成 JSON body,GET 生成 search params),并提供 searchParams、body 两个可覆写的槽(slot);
  • exchange:传输层,真正用 fetch 发送请求(提供可覆写的 fetch 槽);
  • unpack:传输层,把 HTTP 响应对象转换回 GraphQL 结果;
  • decode:接口层,解码结果数据。

对应的 HTTP 传输实现位于 TransportHttp.ts:pack 步骤依据 methodMode 生成请求方法与请求头(TransportHttp.ts),exchange 步骤调用 slots.fetch(input.request.url.value, input.request) 发送请求(TransportHttp.ts),unpack 步骤对响应执行 response.json() 并解析执行结果。

因此本示例选择的 exchange 钩子正是改动即将发出的 HTTP 请求的最后时机——此时 input.request 已经是完整的 ExchangePostRequest/ExchangeGetRequest 对象(含 headers、method、url、body 等字段)。

4.3 transportType 判别联合:安全地收窄

anyware 作用于所有传输(http、memory),而不同传输在 exchange 阶段的数据形态不同(HTTP 是 fetch 请求对象,memory 直接接收 GraphQL 请求)。Graffle 用判别联合建模:所有钩子输入共享携带 transportType 属性的基础接口(见 RequestPipeline.ts)。

示例中的这行判断就是为了安全收窄:

if (exchange.input.transportType !== `http`) return exchange()

return exchange() 原样放行(即"短路":剩余钩子自动透传),仅对 HTTP 传输执行改写逻辑。若客户端通过 schema URL 创建,传输类型在类型层面即被固定为 http,TS 可以据此收窄,减少运行时判断代码。

4.4 输入覆盖(Input Overriding)机制

anyware 改写数据的方式是向钩子传入新的 input:

return exchange({
  input: {
    ...exchange.input,
    request: { ...exchange.input.request, headers: [...] },
  },
})
  • 钩子函数的 input 属性持有该钩子的原始输入,便于展开合并(只改想改的部分);
  • 传入的 input 完全替换钩子将要使用的输入;
  • 不传 input 则钩子用原始输入运行。

这也是 why 示例中能"层层展开"(...exchange.input → ...exchange.input.request → 新 headers)的原因。

4.5 多个 anyware 的执行顺序

示例注册了两个 anyware,它们按注册顺序依次执行:第一个改写请求头,第二个观测最终请求。在 20_request-anyware.md 的"Multiple Anywares"一节对此有明确说明:任意数量 anyware 均按其添加顺序执行(无论来自扩展还是直接注册),运行时存在"ware 栈"与"hook 栈"两套交错推进的调用栈。

五、横向对比:静态配置 vs 动态 anyware

关联文档所在的 examples 目录中还提供了静态请求头的对照示例 transport-http_headers_raw__headers.ts:

const graffle = Graffle
  .create()
  .transport({
    url: publicGraphQLSchemaEndpoints.Pokemon,
    headers: {
      authorization: `Bearer MY_TOKEN`,
      'x-something-to-unset': `true`,
    },
    raw: {
      headers: { 'x-from-raw': `true` },
    },
  })
  .transport({
    headers: { 'x-something-to-unset': `` },
  })

从中可以归纳出两条互补的实践路线:

需求 推荐方式 说明
固定、可提前声明的请求头 .transport({ headers }) 配置期合并进请求,空字符串值可"取消"此前设置的请求头
每次请求都不一样的请求头 .anyware(({ exchange }) => ...) 在 exchange 钩子读取/改写 input.request.headers
底层透传额外 fetch 选项 .transport({ raw }) 合并到 RequestInit,见 TransportHttp.ts 的 mergeInit 逻辑

两者可以同时使用:静态配置负责稳定的默认头,anyware 负责动态追加或按条件覆盖。

六、实战扩展:从示例到真实需求

基于本文的示例模式,可以轻松改造出几类常见能力:

1. 按传输条件动态注入认证令牌

.anyware(({ exchange }) => {
  if (exchange.input.transportType !== `http`) return exchange()
  return exchange({
    input: {
      ...exchange.input,
      request: {
        ...exchange.input.request,
        headers: [
          ...new Headers(exchange.input.request.headers),
          [`authorization`, `Bearer ${getCurrentToken()}`],
        ],
      },
    },
  })
})

2. 为每次请求注入唯一追踪 ID

[`x-request-id`, crypto.randomUUID()],

3. 条件性添加头(如仅 GET 模式追加缓存相关头)

const headers = new Headers(exchange.input.request.headers)
if (exchange.input.request.method === `get`) {
  headers.set(`cache-control`, `no-cache`)
}
return exchange({
  input: { ...exchange.input, request: { ...exchange.input.request, headers: [...headers] } },
})

注意 headers 期望的是键值对数组(HeadersInit 的一种形式),示例统一采用"先包进 Headers 再展开"的手法,既保证去重又保持原有顺序。

七、小结与延伸阅读

本文通过"动态注入 X-Sent-At-Time 请求头"这一最小可运行示例,完整演示了 Graffle anyware 的核心能力:拦截 exchange 钩子、读取 input.request、以输入覆盖(Input Overriding)的方式改写请求头、按 transportType 安全收窄传输类型,并验证了多个 anyware 按注册顺序执行。这套机制不仅适用于请求头,同样适用于请求体、URL、fetch 实现等管线各环节的自定义。

想进一步深入,可以在当前仓库继续阅读:

登录后查看全文
graffle