Express 5.0 中间件类型错误解析与解决方案

问题背景

在使用 Express 5.0 版本开发时，开发者经常会遇到中间件类型不匹配的问题。特别是在实现 JWT 令牌验证这类常见功能时，TypeScript 会抛出类型错误，提示中间件返回值与 Express 的 RequestHandler 类型不兼容。

错误现象

当开发者尝试在中间件中直接返回 res.json() 时，TypeScript 会报错：

No overload matches this call.
Argument of type '(req: Request, res: Response, next: NextFunction) => Response<any, Record<string, any>> | undefined' is not assignable to parameter of type 'RequestHandlerParams<ParamsDictionary, any, any, ParsedQs, Record<string, any>>'.

根本原因分析

这个问题的根源在于 Express 5.0 的类型定义发生了变化。在 Express 5.0 中，RequestHandler 接口明确要求中间件必须返回 void 或 Promise<void>，而直接返回 Response 对象不再被允许。

Express 5.0 的 RequestHandler 接口定义如下：

interface RequestHandler {
  (req: Request, res: Response, next: NextFunction): void | Promise<void>;
}

解决方案

方案一：使用 Express 错误处理机制

正确的做法是利用 Express 的错误处理机制，通过 next() 函数传递错误，而不是直接返回响应：

export const tokenVerifier = (
  req: Request,
  res: Response,
  next: NextFunction
): void => {
  try {
    const authHeader = req.headers.authorization;

    if (!authHeader) {
      return next(new Error("Authorization token was not provided"));
    }

    const token = authHeader.split(" ")[1];
    req.user = verify(token, process.env.JWT_SECRET!) as JwtPayload;
    next();
  } catch (err) {
    next(err);
  }
};

方案二：使用 Express 4.x 类型定义

如果项目暂时无法适应 Express 5.0 的类型约束，可以降级使用 Express 4.x 的类型定义：

npm install @types/express@4.17.0

最佳实践建议

1. 统一错误处理：建议在应用顶层配置错误处理中间件，统一处理所有错误响应。

2. 类型安全：为请求对象扩展类型时，使用可选属性：

declare global {
  namespace Express {
    interface Request {
      user?: JwtPayload;
    }
  }
}

3. HTTP状态码：在返回错误时，应该设置适当的状态码：

if (!authHeader) {
  res.status(401);
  return next(new Error("Unauthorized"));
}

总结

Express 5.0 对中间件的类型约束更加严格，这实际上是引导开发者遵循更好的实践模式。通过正确使用错误处理机制和中间件流程，可以构建出更健壮、更易维护的 Express 应用。理解这些类型约束背后的设计理念，有助于开发者写出更符合 Express 哲学的高质量代码。