如何在声明文件中为FastifyRequest接口新增属性且不覆盖原有内容

在TypeScript中扩展第三方库的接口时，核心是利用接口声明合并特性，但操作不当会导致原有属性丢失，就像你遇到的headers找不到的问题。以下是具体解决方案：

问题原因 #

你当前的声明没有正确关联Fastify原有的FastifyRequest接口，TypeScript将你的代码识别为重新定义了一个全新的FastifyRequest接口，而非扩展原有接口，因此丢失了headers等原生属性。

正确的扩展步骤 #

1. 创建类型声明文件 #

在项目中新建一个*.d.ts类型声明文件（比如src/types/fastify.d.ts），用于扩展Fastify的类型：

// src/types/fastify.d.ts
// 先导入原接口类型，确保TypeScript知道要合并的目标
import type { FastifyRequest } from 'fastify';
// 导入你的User类型，替换成项目实际路径
import type { User } from '../models/user';

declare module 'fastify' {
  // 只添加需要的新属性，原有属性会自动合并
  interface FastifyRequest {
    user: User;
  }
}

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

确保tsconfig.json的include数组包含你的类型声明文件目录，比如：

{
  "compilerOptions": {
    // ...其他项目配置
  },
  "include": [
    "src/**/*",
    "src/types/**/*.d.ts" // 加入这行，让TS识别自定义类型声明
  ]
}

3. 在业务代码中正确使用 #

在auth.ts中，确保从fastify导入FastifyRequest类型，此时扩展后的接口会同时包含原生属性和你新增的user属性：

// auth.ts
import type { FastifyRequest } from 'fastify';
import jwt from 'jsonwebtoken';

// 示例中间件代码
async function authMiddleware(req: FastifyRequest) {
  const user = jwt.verify(
    req.headers.authorization ?? '', // 现在headers属性可以正常识别
    process.env.JWT_SECRET!
  ) as User;
  req.user = user;
}

关键注意事项 #

• 必须先导入原接口类型：如果跳过import type { FastifyRequest } from 'fastify'，TypeScript会认为你在定义一个全新的接口，而非合并原有接口。
• 声明文件后缀必须是.d.ts：这是TypeScript识别类型声明文件的约定。
• 保持接口名称完全一致：扩展的接口名称必须和原模块中的接口名称完全相同，才能触发声明合并特性。

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