graphql-request 请求中间件中Headers对象处理的注意事项

在graphql-request库中使用请求中间件(RequestMiddleware)时，开发者可能会遇到一个常见陷阱：直接展开(spread)Headers对象会导致原始请求头丢失。本文深入分析这个问题并提供解决方案。

问题现象

当开发者按照示例代码编写请求中间件时：

const requestMiddleware: RequestMiddleware = async (request) => {
  return {
    ...request,
    headers: {
      ...request.headers,  // 这里会丢失原始headers
      'x-auth-token': await getAccessToken(),
    },
  }
}

会发现原始请求头全部丢失，只保留了新添加的'x-auth-token'头。这是因为request.headers是Headers类的实例，而展开运算符(...)对Headers实例的处理方式与普通对象不同。

技术原理

Headers是Fetch API规范定义的接口，它实现了特定的迭代行为。当尝试用展开运算符处理Headers实例时：

1. Headers实例不是纯JavaScript对象
2. 它的可枚举属性与普通对象不同
3. 直接展开只会得到一个空对象

解决方案

方案一：使用Headers API

const requestMiddleware: RequestMiddleware = async (request) => {
  const headers = new Headers(request.headers);
  headers.set('x-auth-token', await getAccessToken());

  return {
    ...request,
    headers
  }
}

这种方法：

• 创建新的Headers实例
• 保留所有原始头信息
• 使用标准API添加新头

方案二：转换为普通对象

const requestMiddleware: RequestMiddleware = async (request) => {
  const headers = Object.fromEntries(request.headers.entries());
  
  return {
    ...request,
    headers: {
      ...headers,
      'x-auth-token': await getAccessToken(),
    }
  }
}

这种方法：

• 先将Headers转换为键值对对象
• 然后可以正常使用展开运算符
• 但返回的是普通对象而非Headers实例

最佳实践建议

1. 如果后续处理需要Headers实例，优先使用方案一
2. 如果需要与期望普通对象的其他库交互，可以使用方案二
3. 在中间件中明确处理头的合并逻辑，避免意外覆盖

版本兼容性说明

这个问题在不同版本的graphql-request中表现可能不同，因为：

• 早期版本可能在内部进行了Headers转换
• 新版本更严格遵循Fetch规范
• 建议开发者不要依赖隐式的类型转换

理解这些底层细节有助于开发者编写更健壮的graphql请求中间件，避免在身份验证、跟踪等重要功能中出现难以调试的问题。