如何在Express+TypeScript中扩展Request并解决自定义接口类型错误？

问题背景 #

已通过全局声明扩展Express的Request接口：

declare global {
  namespace Express {
    interface Request {
      user: string;
    }
  }
}

希望为部分路由创建自定义Request接口：

interface UserRequest extends Request {
  name: string
}

但在路由中使用该接口定义的处理函数时，TypeScript抛出类型不兼容错误：
路由代码：

router.get(
  "/",
  getUserByPageAndAmount // 报错位置
);

错误信息：

No overload matches this call.
The last overload gave the following error.
Argument of type '(req: UserRequest, res: Response, next: NextFunction) => Promise' is not assignable to parameter of type 'RequestHandlerParams<ParamsDictionary, any, any, ParsedQs, Record<string, any>>'.
Type '(req: UserRequest, res: Response, next: NextFunction) => Promise' is not assignable to type 'RequestHandler<ParamsDictionary, any, any, ParsedQs, Record<string, any>>'.
Types of parameters 'req' and 'req' are incompatible.
Property 'name' is missing in type 'Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>' but required in type 'UserRequest'.ts(2769)

解决方案 #

方案1：将自定义属性设为可选 #

修改UserRequest，把name标记为可选属性，让它兼容默认的Request类型：

interface UserRequest extends Request {
  name?: string;
}

在处理函数中先校验属性存在性再使用：

const getUserByPageAndAmount = async (req: UserRequest, res: Response, next: NextFunction) => {
  if (!req.name) {
    return next(new Error('name 属性未设置'));
  }
  // 后续业务逻辑
};

方案2：使用类型断言 #

在处理函数内部将req断言为UserRequest，保留属性的必填性：

const getUserByPageAndAmount = async (req: Request, res: Response, next: NextFunction) => {
  const userReq = req as UserRequest;
  // 直接使用 userReq.name
};

⚠️ 注意：必须确保该处理函数执行前，已有中间件为req.name赋值，避免运行时出现undefined。

方案3：利用RequestHandler泛型参数 #

Express的RequestHandler支持泛型，通过第五个泛型参数指定自定义属性，TypeScript会自动合并到Request中：

import { RequestHandler, ParamsDictionary, ParsedQs, Response, NextFunction } from 'express';

const getUserByPageAndAmount: RequestHandler<ParamsDictionary, any, any, ParsedQs, { name: string }> = async (req, res, next) => {
  // 此时 req 包含 name 属性，无需额外类型转换
};

方案4：编写类型守卫函数 #

创建类型守卫严格校验请求对象类型，确保类型安全：

function isUserRequest(req: Request): req is UserRequest {
  return typeof (req as UserRequest).name === 'string';
}

const getUserByPageAndAmount = async (req: Request, res: Response, next: NextFunction) => {
  if (!isUserRequest(req)) {
    return next(new Error('请求不符合 UserRequest 类型'));
  }
  // 此处 req 会被自动推断为 UserRequest 类型
};

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