element-plus-x 中 useSend/XRequest 如何动态设置请求头？

Question

在使用 `element-plus-x` 的 `useSend` 或 `XRequest` 发起请求时，常遇到动态设置请求头（如 Token、Tenant-ID、Trace-ID）的难题：其默认配置为静态对象，无法在每次调用时根据登录态、路由参数或业务上下文实时注入；若在全局拦截器中统一设置，又难以支持多实例、多租户或临时覆盖场景（如带不同权限令牌的并发请求）。开发者尝试通过 `config.headers` 直接传参，却发现部分版本不支持运行时 header 合并；也有用户误将响应拦截器逻辑前置到请求构造阶段，导致异步 token 获取未完成即发包。如何在保持组合式 API 清晰性的同时，安全、可复用地实现 per-request 级别的动态 header 注入？这已成为接入微前端、多租户 SaaS 或灰度发布体系时的高频痛点。

Answer 1

```html

一、现象层：动态 Header 缺失的典型报错与行为特征

• 401 Unauthorized：Token 未注入或过期，但控制台无显式错误；
• 403 Forbidden：Tenant-ID 缺失或错配，后端租户路由拦截触发；
• 并发请求中 Trace-ID 重复或缺失，链路追踪断链（如 SkyWalking/Jaeger）；
• 调用 useSend({ headers: { Authorization: 'Bearer xxx' } }) 后仍走默认 header；
• 在 onMounted 中 await token 获取后调用 XRequest，但请求已发出（竞态条件）。

二、机制层：element-plus-x 请求生命周期与 header 注入时机剖析

下图展示了 useSend / XRequest 的核心执行流与 header 合并策略：

flowchart LR
  A[调用 useSend/config] --> B[解析 config.headers]
  B --> C{是否支持 runtime merge?}
  C -- 是 --> D[浅合并：defaults + config.headers + dynamicHeaders()]
  C -- 否 --> E[完全覆盖：config.headers 覆盖 defaults]
  D --> F[进入请求拦截器]
  E --> F
  F --> G[异步 Token 获取？→ 必须 await!]
  G --> H[最终发送]

三、设计层：per-request 动态 header 的四大实现范式

范式	适用场景	关键约束	是否支持多实例
① 函数式 header 工厂	单实例 + 路由/上下文强耦合	需确保工厂同步返回（Token 必须已就绪）	✅
② Promise-aware config wrapper	需异步获取 Token/Tenant	必须封装为 async () => config 并 await 调用	✅✅
③ 实例级 request builder	微前端子应用隔离、灰度通道	每个 builder 持有独立 auth store 和拦截器栈	✅✅✅
④ 组合式 Hook 封装（推荐）	全场景：SaaS 多租户 + 权限分级 + trace 链路	依赖 useAuthStore, useRoute, useTrace 组合	✅✅✅✅

四、实践层：可复用的组合式解决方案（TypeScript + Pinia）

import { useAuthStore } from '@/stores/auth'
import { useRoute } from 'vue-router'
import { useTrace } from '@/composables/useTrace'

export function useXRequestWithDynamicHeaders() {
  const auth = useAuthStore()
  const route = useRoute()
  const trace = useTrace()

  return async (config) => {
    // ✅ 异步安全：await 所有动态依赖
    await auth.ensureValidToken() // 自动刷新逻辑内建

    // ✅ 上下文感知：从路由、store、全局状态提取
    const tenantId = route.meta.tenantId || auth.currentTenant?.id || 'default'
    const traceId = trace.generate()

    // ✅ per-request header 合并（兼容旧版 element-plus-x）
    const dynamicHeaders = {
      'Authorization': `Bearer ${auth.token}`,
      'Tenant-ID': tenantId,
      'Trace-ID': traceId,
      'X-Client-Version': __APP_VERSION__,
      ...config.headers // 显式保留用户传入头（覆盖优先）
    }

    return XRequest({
      ...config,
      headers: dynamicHeaders
    })
  }
}

// 使用示例：
// const send = useXRequestWithDynamicHeaders()
// const { data } = await send({ url: '/api/users', method: 'GET' })

五、架构层：面向微前端与 SaaS 的 header 策略治理模型

• 租户维度：Header 注入器按 qiankun.instanceName 或 window.__MICRO_APP_ENVIRONMENT__ 分区；
• 权限维度：支持 impersonateAs: 'admin@tenant-a' 临时覆盖 Authorization；
• 灰度维度：通过 headers['X-Release-Phase'] = 'canary-v2' 控制后端分流；
• 可观测性：自动注入 X-Request-Start: Date.now() 用于客户端耗时分析；
• 安全兜底：对敏感 header（如 Authorization）做内存缓存 TTL 校验，避免 stale token 重放。

六、演进层：从 useSend 到声明式请求编排的未来路径

随着 element-plus-x@2.5+ 引入 defineRequest 和 requestPipeline，动态 header 将向声明式演进：

defineRequest('/api/orders', {
  method: 'POST',
  headers: {
    'Authorization': $computed(() => `Bearer ${auth.token}`),
    'Tenant-ID': $computed(() => route.params.tenantId),
    'Trace-ID': $computed(() => trace.id)
  },
  // 支持 pipeline 插件链：token-refresh → tenant-validate → trace-inject
  pipeline: [refreshTokenPlugin, validateTenantPlugin]
})

该模式将 header 动态性提升至响应式计算层面，彻底解耦执行时序与配置定义。

```