使用Axios拦截器动态生成CorrelationID报头时遇TypeScript类型错误

问题描述 #

我尝试为每个请求动态生成并发送CorrelationID，但遇到如下TypeScript类型错误：

错误信息：
TS2322: 类型“{ corRelationId: string; }”不能分配给类型“AxiosRequestHeaders”。
类型“{ corRelationId: string; }”缺少类型“AxiosHeaders”中的以下属性: set, get, has, delete 以及另外23个属性。

错误指向代码中config.headers = { 'corRelationId': correlationId };这一行。

原代码如下：

import axios, { AxiosInstance } from "axios";
import { v4 as uuidv4 } from 'uuid';


const axiosInstance: AxiosInstance = axios.create({
  baseURL: "http://localhost:8080",
  timeout: 10000, // 10 s
  headers: {
    "Content-Type": "application/json",
  },
});

axiosInstance.interceptors.request.use(config => {
  // Generate a unique correlation ID
  const correlationId = uuidv4();
  
  // Attach the correlation ID to the headers
  if (config.headers) {
    config.headers['X-Correlation-ID'] = correlationId;
  } else {
    config.headers = {
      'corRelationId': correlationId,
    };
  }

  return config;
}, error => {
  return Promise.reject(error);
});

export default axiosInstance;

问题原因 #

1. 类型不匹配：Axios v0.27+版本中，config.headers的类型是AxiosHeaders（一个带操作方法的特殊对象），而非普通键值对对象，直接赋值普通对象会触发类型检查错误。
2. 键名不一致：else分支里的header键名写成了corRelationId，和if分支的X-Correlation-ID不统一，同时不符合HTTP请求头的命名规范。

解决方案 #

方案一：使用AxiosHeaders构造函数（规范做法） #

通过Axios提供的AxiosHeaders构造函数创建符合类型要求的headers对象：

import axios, { AxiosInstance, AxiosHeaders } from "axios";
import { v4 as uuidv4 } from 'uuid';


const axiosInstance: AxiosInstance = axios.create({
  baseURL: "http://localhost:8080",
  timeout: 10000, // 10 s
  headers: {
    "Content-Type": "application/json",
  },
});

axiosInstance.interceptors.request.use(config => {
  const correlationId = uuidv4();
  
  if (config.headers) {
    config.headers['X-Correlation-ID'] = correlationId;
  } else {
    config.headers = new AxiosHeaders({
      'X-Correlation-ID': correlationId
    });
  }

  return config;
}, error => {
  return Promise.reject(error);
});

export default axiosInstance;

方案二：类型断言（快速修复） #

用类型断言告知TypeScript当前对象符合AxiosRequestHeaders类型：

// 其他代码不变
axiosInstance.interceptors.request.use(config => {
  const correlationId = uuidv4();
  
  if (config.headers) {
    config.headers['X-Correlation-ID'] = correlationId;
  } else {
    config.headers = {
      'X-Correlation-ID': correlationId
    } as AxiosRequestHeaders;
  }

  return config;
}, error => {
  return Promise.reject(error);
});

方案三：简化逻辑（推荐） #

直接合并headers，依赖Axios内置的类型处理逻辑：

// 其他代码不变
axiosInstance.interceptors.request.use(config => {
  const correlationId = uuidv4();
  config.headers = {
    ...config.headers,
    'X-Correlation-ID': correlationId
  };
  return config;
}, error => {
  return Promise.reject(error);
});

补充说明 #

• 统一使用X-Correlation-ID作为请求头键名，遵循HTTP请求头的命名规范；
• Axios v0.27+版本对headers类型做了严格限制，升级后需注意类型匹配问题。

内容的提问来源于stack exchange，提问作者Pirathikaran