Graffle 动态请求头实战:用 anyware 拦截 exchange 钩子按请求注入 HTTP Headers
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()
逐段拆解
- 创建客户端并配置传输:
.transport({ url })声明 GraphQL 端点,此处未声明任何静态请求头。 - 第一个 anyware:改写请求头:
- 通过解构拿到
exchange钩子(该钩子负责把打包好的请求真正发送出去); exchange.input.transportType是判别联合(discriminated union)属性,用于按传输类型收窄数据。这里先判断!== 'http',非 HTTP 传输(如memory)直接原样放行;new Headers(exchange.input.request.headers)把当前请求头包装成Headers实例,再展开成键值对数组,追加['X-Sent-At-Time', Date.now().toString()]。这样既保留原有请求头,又实现了"按请求动态计算"。
- 通过解构拿到
- 第二个 anyware:观测请求:在修改完成后打印
exchange.input.request,用于确认改动生效。 - 发送请求:
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 实现等管线各环节的自定义。
想进一步深入,可以在当前仓库继续阅读:
- anyware 完整指南:20_request-anyware.md(含五个钩子详表、跳转启动、短路、槽与多 anyware 机制);
- 请求管线源码:RequestPipeline.ts;
- HTTP 传输实现:TransportHttp.ts;
- 站点示例页:dynamic-headers.md;
- 静态请求头对照示例:transport-http_headers_raw__headers.ts。