Graffle 动态请求头实战:用 anyware 扩展系统逐请求注入 HTTP Headers

原创2026-10-09 23:39:461,664 阅读
文章标签:后端

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。

这段输出至少揭示四个关键事实:

  1. 动态头已成功追加:headers 数组中除了默认的 accept 与 content-type,还多出了 ['X-Sent-At-Time', '1762136942519'],其值 Date.now() 在每次请求时都会不同;
  2. 默认头被完整保留:accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8' 与 content-type: 'application/json' 是 Graffle 依据 GraphQL Over HTTP 规范自动设置的(详见下文"请求头合并策略");
  3. 请求头以键值对数组表示:headers 是 [name, value] 元组数组,与 Web 标准 HeadersInit 兼容,因此可以用 new Headers(...) 展开重建;
  4. 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 标准 Headers API 互转;
  • 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 按以下顺序合并:

  1. 协议默认头(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);
  2. transport.raw 中的配置(零护栏地透传给 fetch 的 RequestInit);
  3. 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 做动态请求头时建议遵循以下实践:

  1. 务必判断 transportType:多传输场景下,先 if (exchange.input.transportType !== 'http') return exchange() 放行非 HTTP 请求,避免类型误用;
  2. 保留默认头:通过 ...new Headers(exchange.input.request.headers) 展开旧头再追加新头,不要整体替换,以免丢失 accept / content-type;
  3. 保持 exchange() 调用链:每个拦截器最后都要返回 exchange()(或携带新 input 的 exchange({ input })),否则请求管道会被截断;
  4. 顺序即执行顺序:anyware 按注册顺序执行。示例中"注入头"的拦截器注册在"打印日志"之前,因此日志看到的是注入后的完整请求;若把打印放在注入之前,则看不到动态头;
  5. 值必须是字符串:HeadersInit 的取值要求字符串,所以 Date.now() 需要 .toString(),其他非字符串值同理;
  6. 不可变更新:修改 input 时使用展开运算符逐层复制({ ...exchange.input, request: { ...exchange.input.request, headers: [...] } }),保持原有字段不动。

Graffle 官方还在 TransportHttp 扩展文档 中给出了 anyware 的另一种典型用法——在 SvelteKit 等框架中替换 exchange.fetch 为框架增强版 fetch(相对 URL 场景),这说明 anyware 不仅能改请求头,还能整体替换传输的底层执行函数,是 Graffle 扩展体系中最灵活的"横切点"。动态请求头只是它的入门应用,理解了这个机制,你就能举一反三地实现鉴权、日志、重试、断路等能力。

登录后查看全文
graffle