在Express路由方法外定义请求处理器时自动推断req.params类型

问题背景 #

在Express中直接在路由方法内部定义请求处理器时，TypeScript可以自动从路由路径推断出req.params的结构：

import express from "express";
const app = express();

app.get("/:abc", (req, res) => {
    // req.params 被推断为 { abc: string } 类型
    const abc = req.params.abc; // 类型检查通过
    const xyz = req.params.xyz; // 类型检查不通过，符合预期
});

但如果把请求处理器定义在路由方法外部，直接使用RequestHandler类型会导致req.params被推断为宽泛的ParamsDictionary（即{[key: string]: string}），无法限制非法属性的访问：

import express, { RequestHandler } from "express";
const app = express();

const requestHandler: RequestHandler = (req, res) => {
    const abc = req.params.abc; // 类型检查通过
    const xyz = req.params.xyz; // 本应报错，但实际通过，不符合预期
};
app.get("/:abc", requestHandler);

虽然可以通过RouteParameters泛型显式指定类型，但这种方式需要重复编写路由字符串，且无法校验路由路径与处理器参数的一致性——修改路由路径后，处理器里的旧参数不会触发类型错误：

import express, { RequestHandler } from "express";
import { RouteParameters } from "express-serve-static-core";
const app = express();

const requestHandler: RequestHandler<RouteParameters<"/:abc">> = (req, res) => {
    const abc = req.params.abc; // 类型检查通过，但此时路由已修改为"/:jkl"，逻辑错误
};
app.get("/:jkl", requestHandler); // 无类型报错

解决方案 #

方案1：封装类型安全的路由注册函数

通过封装一个泛型函数，将路由路径与处理器的req.params类型绑定，实现自动推断并校验一致性：

import express, { Request, Response } from "express";
import type { RouteParameters } from "express-serve-static-core";

const app = express();

// 泛型函数：自动关联路由路径与处理器的params类型
function registerGet<Route extends string>(
    path: Route,
    handler: (req: Request<RouteParameters<Route>>, res: Response) => void
) {
    app.get(path, handler);
}

// 定义处理器时，基于路由自动推断params类型
const abcHandler = (req: Request<RouteParameters<"/:abc">>, res: Response) => {
    const abc = req.params.abc; // 类型正确
    // const xyz = req.params.xyz; // 类型错误，符合预期
};

// 注册路由，若路径与处理器不匹配会直接报错
registerGet("/:abc", abcHandler);
// registerGet("/:jkl", abcHandler); // 触发类型错误：参数类型不兼容

方案2：使用常量路由字符串推导类型

将路由路径定义为常量，基于常量推导处理器的类型，确保路由与处理器的参数同步：

import express, { Request, Response } from "express";
import type { RouteParameters } from "express-serve-static-core";

const app = express();

// 定义路由常量，确保类型是字面量类型
const ABC_ROUTE = "/:abc" as const;

// 基于路由常量推导处理器类型
type AbcRouteHandler = (req: Request<RouteParameters<typeof ABC_ROUTE>>, res: Response) => void;

// 定义处理器时自动继承正确的params类型
const abcHandler: AbcRouteHandler = (req, res) => {
    const abc = req.params.abc; // 类型正确
    // const xyz = req.params.xyz; // 类型错误
};

// 使用常量注册路由，修改常量时处理器会自动触发类型检查
app.get(ABC_ROUTE, abcHandler);
// 若修改ABC_ROUTE为"/:jkl"，处理器里的req.params.abc会立即报错

这两种方案都无需手动重复传入RouteParameters<"route-string">，同时能确保路由路径与处理器的req.params类型严格一致，避免因路由修改导致的逻辑错误。

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