如何使用TypeScript模板字面量类型构建异步路由参数的强类型约束体系

TypeScript模板字面量类型可构建强类型异步路由体系，统一路径结构、参数类型与加载时机，实现客户端跳转、服务端预取和参数校验的类型共享与自动推导。

用 TypeScript 模板字面量类型构建异步路由参数的强类型约束体系，核心是把“路径结构 + 参数类型 + 异步加载时机”三者在类型层面耦合起来，让参数校验、跳转调用、服务端预取（如 Next.js 的 generateStaticParams 或 getServerSideProps）全部共享同一套类型定义，避免运行时解析错误或漏传字段。

一、用模板字面量编码带异步语义的路径类型

异步路由常含动态段（如 /post/[id]）、可选段（如 /user/[id]/[tab?]）或嵌套路由组（如 /admin/[...rest]）。模板字面量可逐层建模这些语义：

• 基础动态段：用 string 或更窄类型占位，如 type PostId = `${number}`（强制数字字符串）或 type Slug = `a-${string}-z`（带固定前缀后缀）
• 可选段：用联合类型模拟，如 type TabSegment = '' | `/[tab]`，再组合进完整路径：type UserRoute = `/user/[id]${TabSegment}`
• 捕获所有剩余路径：用递归模板字面量模拟 [...rest] 行为，例如 type RestPath = `${string}/${RestPath}` | `${string}`，再约束为合法子集：type AdminSubpath = 'dashboard' | 'settings' | 'logs'; type AdminRoute = `/admin/${AdminSubpath}` | `/admin/${RestPath & `${AdminSubpath}/${string}`}`

二、自动推导异步参数对象并绑定加载逻辑

仅定义路径类型不够，关键是要让 generateStaticParams、getServerSideProps 或自定义 load() 函数能根据路径字面量自动获得参数结构和返回类型：

• 用条件类型 + infer 提取参数名与类型：
  type ExtractParams<P> = P extends <code>`/${infer First}/${infer Rest}` ? { [K in First]: string } & ExtractParams<`/${Rest}`> : {};
  配合映射类型进一步将 id 映射为 number，slug 映射为 string
• 为每个路由路径定义专属加载函数类型：
  type RouteLoader<P> = (params: ExtractParams<P>) => Promise<{ data: any; meta?: object }>;
  这样 /post/[id] 的 loader 必须接收 { id: string }，而 /user/[uid]/[lang?] 的 loader 接收 { uid: string; lang?: string }
• Next.js 场景下，直接把 generateStaticParams 的返回值类型设为 Array<ExtractParams<AppRoute>>，TS 会检查你返回的对象是否覆盖所有必需字段，且值类型匹配

三、统一客户端跳转与服务端预取的参数校验

异步路由的痛点常在于客户端导航（如 router.push()）和服务端生成（如 generateStaticParams）使用两套参数逻辑。模板字面量可桥接二者：

• 定义一个泛型跳转函数：
  function navigateTo<P extends AppRoute>(path: P, params: ExtractParams<P>): void { ... }
  调用 navigateTo('/post/[id]', { id: '123' }) 合法，但 navigateTo('/post/[id]', { id: 123 }) 报错（类型不匹配），navigateTo('/post/[id]', {}) 也报错（漏传）
• 服务端侧复用同一类型：
  export async function generateStaticParams() { return [{ id: '1' }, { id: '2' }] satisfies Array<ExtractParams<'/post/[id]'>; }
  satisfies 确保数组结构符合预期，又保留字面量精度供 IDE 补全
• 若路由支持多语言前缀（如 /[lang]/post/[id]），可扩展为：type LocalizedRoute = `${LangPrefix}${AppRoute}`，再用嵌套 ExtractParams 分离 lang 和业务参数

四、对接框架运行时，保持类型与行为一致

最终要落地，需把类型系统和框架机制对齐：

• Next.js App Router：将 AppRoute 类型用于 RouteSegmentConfig 的 path 字段，并在 layout/server component 中用 useSelectedLayoutSegment() 的返回值做类型守卫
• React Router：自定义 TypedNavigate Hook，其参数签名由传入的路径字符串 infer 出来，同时支持 loader 配置项的类型自动关联
• 错误兜底：即使类型完备，仍建议在 loader 内部加运行时校验，例如 if (!params.id || !/^d+$/.test(params.id)) throw new Error('Invalid post ID')，防止恶意构造 URL 绕过编译检查