Graffle 动态请求头实战:用 anyware 扩展系统逐请求注入 HTTP Headers
Graffle 动态请求头实战:用 anyware 扩展系统逐请求注入 HTTP Headers
本篇技术指南讲解如何在 Graffle GraphQL 客户端中,利用 anyware(请求管道拦截器)扩展机制,在每次请求真正发出之前动态地修改 HTTP 请求头——例如注入时间戳、刷新后的认证令牌、链路追踪 ID 等。文章以官方 "Dynamic Headers" 示例为骨架,结合仓库中请求管道与 HTTP 传输扩展的源码,带你理解 exchange 钩子的输入结构、请求头合并策略与验证方法。读完你将掌握 Graffle 扩展体系中处理"横切关注点"(认证、日志、重试)的核心套路。
一、为什么需要"动态"请求头
在 TransportHttp 扩展文档 中,Graffle 支持通过 .transport({ headers: { authorization: '...' } }) 静态地配置请求头。但对于以下场景,静态配置显然不够:
- 短期令牌:
Authorization头需要携带每次调用时实时刷新的 token; - 请求时间戳 / 防重放:需要记录
Date.now()级别的发送时刻; - 链路追踪:每个请求携带唯一的
trace-id/x-request-id; - A/B 实验、限流配额:头值随上下文变化。
这类"每次请求动态计算头值"的需求,正是 anyware 拦截器的用武之地。Graffle 官方为此提供了专门示例 transport-http_extension_headers__dynamicHeaders.ts,对应的文档页面为 website/content/examples/10_transport-http/dynamic-headers.md。
二、示例全貌:逐请求注入时间戳请求头
以下是官方 Dynamic Headers 示例的完整代码(snippet 位于 website/content/_snippets/examples/transport-http/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()
示例运行后,第二个 anyware 打印出的请求对象如下:
{
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:',
username: '',
password: '',
host: 'localhost:3000',
hostname: 'localhost',
port: '3000',
pathname: '/graphql',
search: '',
searchParams: URLSearchParams {},
hash: ''
}
},
body: '{"query":"{ pokemons { name } }"}'
}
输出结果同样被持久化为仓库内的可验证产物:examples/outputs/10_transport-http/transport-http_extension_headers__dynamicHeaders.output.txt。
这段输出至少揭示四个关键事实:
- 动态头已成功追加:
headers数组中除了默认的accept与content-type,还多出了['X-Sent-At-Time', '1762136942519'],其值Date.now()在每次请求时都会不同; - 默认头被完整保留:
accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8'与content-type: 'application/json'是 Graffle 依据 GraphQL Over HTTP 规范自动设置的(详见下文"请求头合并策略"); - 请求头以键值对数组表示:
headers是[name, value]元组数组,与 Web 标准HeadersInit兼容,因此可以用new Headers(...)展开重建; - URL 是带判别标记的结构:
url: { _tag: 'url', value: URL {...} },_tag用于区分绝对 URL 与相对路径。
三、anyware 机制原理:请求管道五步走
anyware 是 Graffle 客户端提供的拦截器 API。在 client.ts 的 JSDoc 中,其定义如下:
Interceptors (called "anyware") allow you to intercept and modify requests at various stages, such as adding authentication headers, logging, error handling, or retrying failed requests.
关键特性:不可变性——调用 anyware(interceptor) 返回一个新的客户端实例,原客户端不被修改;如果操作没有产生有效变化,则出于性能考虑返回同一实例。
从 RequestPipeline.ts 的源码可见,每个请求都会依次流经五个具名步骤:
| 步骤 | 名称 | 职责 |
|---|---|---|
| 1 | encode |
规范化请求、按 schema 映射(SDDM)与标量编解码器编码变量 |
| 2 | pack |
将 GraphQL 请求打包为传输层可发送的形态(HTTP 请求头、URL、body) |
| 3 | exchange |
真正"交换"数据:对 HTTP 传输即调用 fetch 发出网络请求 |
| 4 | unpack |
解析传输层响应(如 response.json() 并校验执行结果结构) |
| 5 | decode |
按 schema 映射解码结果数据,返回给调用方 |
anyware 钩子通过解构拿到某个步骤的执行函数(如 ({ exchange }) => ...),先观察 exchange.input,再决定是原样 return exchange() 放行,还是携带修改后的 input 重新调用 exchange({ input: {...} }) 注入变更。
钩子输入中的 transportType
示例第一行判断 exchange.input.transportType !== 'http' 才继续处理。transportType 是钩子输入的一部分,其值与当前生效传输的名称一致。仓库测试 anyware.test.ts 明确验证了这一点:测试 hook inputs have transportType in interceptor 断言 pack.input.transportType 等于传输名;当客户端同时挂载多个传输时,transportType 的类型会收窄为各传输名称的联合类型。
这个判断的意义在于:一个 Graffle 客户端可以挂载多种传输(例如 http 与 memory),针对 HTTP 的动态头注入逻辑只应在 transportType === 'http' 时生效,对其他传输直接放行,避免误改非 HTTP 请求。
四、exchange 钩子输入结构剖析
示例中第二个 anyware 打印的 exchange.input.request 对象,正是 TransportHttp.ts 中定义的 ExchangeRequest 类型(ExchangePostRequest | ExchangeGetRequest)的实例:
methodMode:'post' | 'getReads',对应传输配置项。默认是'post'(见 TransportHttp.ts 的configurationDefault);配置为'getReads'后,只读操作会改用 HTTP GET,payload 以 URL 搜索参数发送;method:最终 HTTP 方法。由pack步骤根据methodMode与操作类型(query/mutation)计算得出(TransportHttp.ts);headers:[name, value]元组数组,兼容HeadersInit,便于与 Web 标准HeadersAPI 互转;url:判别联合URLInputType——{ _tag: 'url', value: URL }表示绝对 URL,{ _tag: 'path', value: string }表示相对路径(/api、./api、../api)。判别逻辑见 TransportHttp.ts 的parseURLInput;body(仅 POST):JSON.stringify({ query, variables, operationName })序列化后的请求体。
动态注入的实现技巧
示例中的注入代码值得拆解:
headers: [
...new Headers(exchange.input.request.headers),
[`X-Sent-At-Time`, Date.now().toString()],
]
new Headers(exchange.input.request.headers) 把现有的键值对数组转成标准 Headers 对象(可自动去重同名头),再通过展开运算符 ... 把其中的键值对展开进新数组,最后追加新的元组 ['X-Sent-At-Time', Date.now().toString()]。这是一种"先规范化、后追加"的安全写法:既保留默认头,又避免同名头重复。
五、请求头合并策略与静态配置对照
为了理解动态注入后输出中的默认头来源,需要看 TransportHttp 的 pack 步骤。在 TransportHttp.ts 中,请求头通过 Http.Req.mergeInit 按以下顺序合并:
- 协议默认头(src/lib/graphql-kit/http/__.ts 定义的
postRequestHeadersRec/getRequestHeadersRec):- POST:
accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8'与content-type: 'application/json'; - GET:仅
accept(payload 走 URL 搜索参数,无需 JSON content-type);
- POST:
transport.raw中的配置(零护栏地透传给fetch的RequestInit);transport.headers中的静态配置。
优先级上,raw 高于 transport 下其他属性;而 anyware 拦截器作用于 pack 之后、exchange 之前,因此可以覆盖以上全部结果——这正是动态注入能生效的位置保证。
文档还强调了两条合并规则(见 TransportHttp 扩展文档):
- 头是合并的,不会互相覆盖丢失;
- 值为空字符串的头会"删除"之前设置的同名头。例如示例 transport-http_headers_raw__headers.ts 展示了用
transport({ headers: { 'x-something-to-unset': '' } })撤销先前设置的头。
作为对照,动态方案与静态配置的使用场景可以这样区分:
| 方式 | 语法 | 适用场景 |
|---|---|---|
| 静态头 | .transport({ headers: {...} }) |
固定不变的常量头 |
| raw 透传 | .transport({ raw: { headers: {...}, mode: 'cors' } }) |
需要零护栏直接控制 RequestInit(见 transport-http_raw.ts) |
| anyware 动态 | .anyware(({ exchange }) => ...) |
每次请求重新计算的头值、条件注入、日志、重试 |
六、注意事项与最佳实践
综合源码与示例,使用 anyware 做动态请求头时建议遵循以下实践:
- 务必判断
transportType:多传输场景下,先if (exchange.input.transportType !== 'http') return exchange()放行非 HTTP 请求,避免类型误用; - 保留默认头:通过
...new Headers(exchange.input.request.headers)展开旧头再追加新头,不要整体替换,以免丢失accept/content-type; - 保持
exchange()调用链:每个拦截器最后都要返回exchange()(或携带新 input 的exchange({ input })),否则请求管道会被截断; - 顺序即执行顺序:
anyware按注册顺序执行。示例中"注入头"的拦截器注册在"打印日志"之前,因此日志看到的是注入后的完整请求;若把打印放在注入之前,则看不到动态头; - 值必须是字符串:
HeadersInit的取值要求字符串,所以Date.now()需要.toString(),其他非字符串值同理; - 不可变更新:修改 input 时使用展开运算符逐层复制(
{ ...exchange.input, request: { ...exchange.input.request, headers: [...] } }),保持原有字段不动。
Graffle 官方还在 TransportHttp 扩展文档 中给出了 anyware 的另一种典型用法——在 SvelteKit 等框架中替换 exchange.fetch 为框架增强版 fetch(相对 URL 场景),这说明 anyware 不仅能改请求头,还能整体替换传输的底层执行函数,是 Graffle 扩展体系中最灵活的"横切点"。动态请求头只是它的入门应用,理解了这个机制,你就能举一反三地实现鉴权、日志、重试、断路等能力。