Express.js中TypeScript无法给req.query添加属性并读取的问题求助

问题原因 #

Express的Request接口中，req.query默认类型为ParsedQs，TypeScript会对该类型的属性进行严格检查。直接给req.query添加未声明的属性时，不仅会触发类型报错，甚至可能在运行时因为类型约束导致属性未被正确赋值，最终出现读取到undefined的情况。而JavaScript作为动态类型语言，不存在这类类型限制，因此可以正常运行。

解决方法 #

方法一：类型断言（快速临时方案） #

通过类型断言将req.query转换为可扩展的键值对类型，绕过TypeScript的类型检查：

// aliasTopTours 中间件
import { Response, Request, NextFunction } from 'express';

const aliasTopTours = (req: Request, res: Response, next: NextFunction) => {
  // 将req.query断言为可扩展的字符串键值对类型
  const query = req.query as Record<string, string | undefined>;
  query.limit = '5';
  query.sort = '-ratingsAverage,price';
  query.fields = 'name,price,ratingsAverage,summary,difficulty';
  next();
};

export { aliasTopTours };

在读取属性的中间件中同样使用断言：

const getAllTours = async (req: Request, res: Response, next: NextFunction) => {
  const query = req.query as Record<string, string | undefined>;
  console.log(query.limit); // 输出 '5'
  console.log(query.sort); // 输出 '-ratingsAverage,price'
  console.log(query.fields); // 输出 'name,price,ratingsAverage,summary,difficulty'
  res.end('tours');
};

方法二：扩展Express Request接口（规范长期方案） #

通过自定义类型声明扩展Express的Request接口，让TypeScript识别自定义的查询参数：

1. 在项目中创建类型声明文件，比如src/types/express.d.ts：

import 'express';

declare module 'express' {
  interface Request {
    query: {
      limit?: string;
      sort?: string;
      fields?: string;
      // 保留任意键值对的兼容性
      [key: string]: string | undefined;
    };
  }
}

2. 修改tsconfig.json确保类型声明文件被正确识别：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"]
  }
}

之后就可以直接给req.query赋值，无需额外断言：

const aliasTopTours = (req: Request, res: Response, next: NextFunction) => {
  req.query.limit = '5';
  req.query.sort = '-ratingsAverage,price';
  req.query.fields = 'name,price,ratingsAverage,summary,difficulty';
  next();
};

方法三：替换req.query对象（简单直接） #

直接创建包含原有属性和新属性的对象，替换掉原来的req.query，同时通过类型断言保持类型兼容：

const aliasTopTours = (req: Request, res: Response, next: NextFunction) => {
  req.query = {
    ...req.query,
    limit: '5',
    sort: '-ratingsAverage,price',
    fields: 'name,price,ratingsAverage,summary,difficulty'
  } as typeof req.query;
  next();
};

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