将JS应用迁移到TS时，Express中间件验证后仍遇req.files类型错误

下面是几种不用重复检查或手动类型收窄的解决办法：

1. 自定义类型断言函数 #

写一个专门的断言函数，用来告诉TypeScript当前请求已经通过了文件验证，req.files.image肯定存在。这个函数在运行时几乎不会触发错误（毕竟中间件已经做过检查），主要是给TS做类型提示：

import { Request, Response } from 'express';

function assertHasValidImage(req: Request): asserts req is Request & {
  files: { image: Express.Multer.File[] }
} {
  if (!req.files?.image) {
    throw new Error('Missing valid image file');
  }
}

// 在uploadImage里调用
async function uploadImage(req: Request, res: Response) {
  assertHasValidImage(req);
  // 这里req.files.image就不会再报类型错误了
  const imageFile = req.files.image[0];
  // 后续逻辑...
}

2. 把中间件改成类型守卫 #

调整中间件的类型，让它成为一个类型守卫函数，明确告诉TS：经过这个中间件的请求，一定包含合法的req.files.image。示例：

import { Request, Response, NextFunction } from 'express';

type ValidatedImageRequest = Request & {
  files: { image: Express.Multer.File[] };
};

function validateUploadImageData(
  req: Request,
  res: Response,
  next: NextFunction
): asserts req is ValidatedImageRequest {
  // 原有的验证逻辑
  if (!req.files?.image) {
    return res.status(400).json({ error: 'Image file is required' });
  }
  // 检查图片类型、大小...
  if (!req.files.image[0].mimetype.startsWith('image/')) {
    return res.status(400).json({ error: 'Invalid image type' });
  }
  // 验证通过，放行
  next();
}

// 路由里使用后，uploadImage会自动推断req的类型
imageRouter.route('/upload').post(validateUploadImageData, uploadImage);

// uploadImage的定义可以直接用ValidatedImageRequest
async function uploadImage(req: ValidatedImageRequest, res: Response) {
  const image = req.files.image[0];
  // 处理逻辑...
}

3. 封装泛型路由工具 #

如果项目里有很多类似的验证场景，可以封装一个泛型路由函数，用来绑定中间件和处理函数，并明确处理函数接收的请求类型：

import { Router, Request, Response, NextFunction } from 'express';

type ValidatedRequest<T> = Request & T;
type ValidatedHandler<T> = (req: ValidatedRequest<T>, res: Response, next: NextFunction) => void;

function validatedPost<T>(
  router: Router,
  path: string,
  validator: (req: Request, res: Response, next: NextFunction) => void,
  handler: ValidatedHandler<T>
) {
  router.post(path, validator, handler as ValidatedHandler<{}>);
}

// 定义验证后的请求类型
type ImageUploadRequest = {
  files: { image: Express.Multer.File[] };
};

// 使用封装的路由函数
validatedPost<ImageUploadRequest>(
  imageRouter,
  '/upload',
  validateUploadImageData,
  async (req, res) => {
    // 这里req.files.image是安全的
    const image = req.files.image[0];
    // 处理逻辑...
  }
);

4. 框架层面的类型支持（如NestJS） #

如果用的是NestJS这类自带类型支持的框架，可以通过自定义管道或守卫来标记请求类型，比如：

import { Controller, Post, Req, UseGuards } from '@nestjs/common';
import { ImageValidationGuard } from './image-validation.guard';

type ValidatedImageRequest = Request & {
  files: { image: Express.Multer.File[] };
};

@Controller('image')
export class ImageController {
  @Post('upload')
  @UseGuards(ImageValidationGuard)
  uploadImage(@Req() req: ValidatedImageRequest) {
    // 直接使用req.files.image即可
  }
}

这里的ImageValidationGuard就是实现了验证逻辑的守卫，同时让TS知道经过守卫后的请求符合ValidatedImageRequest类型。

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