在TypeScript+Express.js中为res.setHeader()实现自定义Header自动补全

要为Express的res.setHeader()添加自定义Header的自动补全与类型校验，你需要正确合并Express的类型声明，而不是简单重载Response接口的方法。以下是具体实现步骤：

1. 创建类型声明文件 #

在项目中创建一个类型扩展文件（比如src/types/express.d.ts），确保它被TypeScript识别（需在tsconfig.json的include范围内）。

方法一：扩展响应头类型（覆盖所有响应头相关方法） #

这种方式会让res.setHeader()、res.header()等所有操作响应头的方法都获得自定义Header的支持：

declare module "express-serve-static-core" {
  interface ResponseHeaders {
    "X-Trace-ID"?: string;
  }

  interface RequestHeaders {
    "X-Trace-ID"?: string;
  }
}

// 必须导出空对象，将文件标记为模块，确保类型合并生效
export {};

方法二：重载setHeader方法（针对性扩展） #

如果你只想针对setHeader做扩展，可以直接重载该方法的类型：

declare global {
  namespace Express {
    interface Request {
      // 扩展请求头类型，让req.headers["X-Trace-ID"]获得类型提示
      headers: {
        "X-Trace-ID"?: string;
      } & Request["headers"];
    }

    interface Response {
      // 优先匹配自定义Header的类型规则
      setHeader(field: "X-Trace-ID", value: string): this;
      // 保留原有方法的通用类型，避免覆盖默认行为
      setHeader(field: string, value: string | string[] | number): this;
    }
  }
}

export {};

2. 配置TypeScript识别声明文件 #

确保你的tsconfig.json包含该类型文件：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"],
    "target": "ES2020",
    "module": "CommonJS"
  },
  "include": ["src/**/*", "src/types/**/*"]
}

3. 验证效果 #

现在你的中间件代码会获得完整的类型支持：

• 输入res.setHeader("X-时会自动补全X-Trace-ID
• 如果传入非string类型的value，TypeScript会抛出类型错误
• req.headers["X-Trace-ID"]会被推断为string | undefined，而非宽泛的string | string[] | undefined

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