如何基于URL路径参数实现TypeScript类型自动补全？

问题描述 #

注册Web路由时，pathname格式如/about/:name/:age，但在handler中输入groups.时，IDE无法自动提示name、age这类动态参数键。当前路由模块代码如下：

type Route = {
  pathname: string;
  handler: CallableFunction;
};

const routes: Route[] = [];

export type DynamicGroups<T> = {
  [key in keyof T]: string;
};

export const push = (route: Route) => {
  routes.push(route);
};

export const response = (req: Request) => {
  for (const route of routes) {
    const pattern = new URLPattern({
      pathname: route.pathname,
    });

    const result = pattern.exec(req.url);

    if (result) {
      const groups: DynamicGroups = result.pathname.groups;

      return route.handler(groups);
    }
  }

  return null;
};

解决方案 #

要实现动态参数的自动补全，需要让TypeScript从pathname字符串中提取参数名，并绑定到handler的参数类型上。通过模板字面量类型和泛型关联可以实现这一需求，具体修改如下：

1. 定义参数提取类型 #

首先创建用于解析pathname动态参数的工具类型：

// 递归提取pathname中的所有动态参数名，返回参数名联合类型
type ExtractRouteParams<Path extends string> =
  Path extends `${infer _Prefix}/:${infer Param}/${infer Rest}`
    ? Param | ExtractRouteParams<Rest>
    : Path extends `${infer _Prefix}/:${infer Param}`
    ? Param
    : never;

// 将参数名联合类型转为键值对类型，值统一为string（匹配URLPattern返回的groups结构）
type RouteParams<Path extends string> = {
  [K in ExtractRouteParams<Path>]: string;
};

2. 重构泛型Route类型 #

将Route改为泛型类型，让pathname的字面量类型与handler的参数类型绑定：

// 泛型Route类型，Path为pathname的具体字符串字面量
type Route<Path extends string> = {
  pathname: Path;
  // handler的参数类型由pathname动态推导
  handler: (groups: RouteParams<Path>) => unknown;
};

3. 修改push函数为泛型函数 #

让TypeScript自动推导注册路由时的pathname类型：

const routes: Route<string>[] = [];

// 泛型push函数，自动关联pathname和handler参数类型
export const push = <Path extends string>(route: Route<Path>) => {
  // 类型断言兼容不同path的路由数组
  routes.push(route as Route<string>);
};

4. 调整response函数 #

运行时直接传递匹配结果，编译时已通过泛型保证类型安全：

export const response = (req: Request) => {
  for (const route of routes) {
    const pattern = new URLPattern({
      pathname: route.pathname,
    });

    const result = pattern.exec(req.url);

    if (result) {
      return route.handler(result.pathname.groups as never);
    }
  }

  return null;
};

使用示例 #

注册路由时，IDE会自动补全handler中的groups参数键：

push({
  pathname: '/about/:name/:age',
  handler: (groups) => {
    // 输入groups.时，自动提示name、age
    console.log(groups.name, groups.age);
  },
});

push({
  pathname: '/user/:id',
  handler: (groups) => {
    // 自动提示id
    console.log(groups.id);
  },
});

关键说明 #

• ExtractRouteParams通过递归模板字面量解析，从pathname中提取所有:param格式的参数名，返回对应的联合类型。
• 泛型Route和push函数让TypeScript在注册路由时，自动将pathname的具体类型与handler的参数类型绑定，从而实现IDE的自动补全。
• 路由数组使用Route<string>作为通用类型，通过类型断言兼容不同path的路由，不影响编译阶段的类型检查。

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