TanStack Router 类型安全指南全链路类型推断、Register 注册与 TypeScript 性能优化【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router本指南基于本仓库 docs/router/guide/type-safety.md 编写并结合 packages/router-core、packages/react-router、packages/solid-router、packages/vue-router 等包的源码进行纵深佐证。TanStack Router本仓库中同时提供 React / Solid / Vue 三种框架的 router 与 start 全栈实现在设计之初就以「尽可能类型安全」为最高目标它不仅在 TypeScript 中实现更完整推断你提供的类型并顽强地把这些类型贯穿到整个路由体验的每一个环节。读完本文你将掌握如何通过Register接口声明合并让顶层导出Link、useNavigate、useParams等获得精确类型如何利用Route.useParams()/useSearch({ from })/strict: false解决组件上下文推断问题以及当应用规模膨胀时如何用as const satisfies、对象语法addChildren等技巧将 TS 检查耗时保持在可控范围。路由定义中的类型安全路由是分层的它们的类型定义同样如此。本仓库 packages/router-core/src/routeInfo.ts 等源码中RouteById、FullSearchSchema、RouteTypesById等类型工具共同构成了「按路由 ID 索引类型」的类型基础设施这正是整条类型推断链路的基石。文件式路由File-based Routing如果你使用文件式路由大部分类型安全工作已经替你完成了。路由生成器会基于你的文件路径生成routeTree.gen.ts其中每个createFileRoute(/posts)的路径字面量都会成为精确的字符串字面量类型params、search、loaderData、context的类型都会自动流入对应的路由。从源码结构看文件式路由的路径类型约束主要落在createFileRoute的路径参数与Route对象的泛型推导上开发者几乎无需手写任何类型标注。代码式路由Code-based Routing如果你直接使用Route类或各框架导出的createRoute就必须留意如何通过getParentRoute选项保证路由类型正确。原因在于子路由需要感知其全部父路由的类型。否则你在三层之上的_layout路由和_pathless layout路由里解析出的宝贵 search params就会消失在「JS 虚空」中。因此千万别忘了把父路由传给子路由const parentRoute createRoute({ getParentRoute: () parentRoute, })正是getParentRoute建立了父子路由之间的类型关联使父路由的params、search、context、loaderData类型能沿着路由树逐层向下合并。Exported Hooks、组件与工具的类型注册Register为了让你的路由类型能作用于Link、useNavigate、useParams等顶层导出这些类型必须「渗透」过 TypeScript 的模块边界直接注册进库内部。实现机制是对库导出的Register接口进行声明合并declaration merging。在 packages/router-core/src/router.ts 中可以看到Register接口及其读取方式export interface Register { // Lots of things on here like... // router // config // ssr } export type RegisteredRouterTRegister Register TRegister extends { router: infer TRouter } ? TRouter : AnyRouter也就是说RegisteredRouter通过条件类型从你填充的Register.router中提取出具体的 Router 实例类型若未注册则退化为AnyRouter一切类型皆退化为宽泛类型。这正是「注册之后才能获得精确类型」的底层原因。Reactconst router createRouter({ // ... }) declare module tanstack/react-router { interface Register { router: typeof router } }Solidconst router createRouter({ // ... }) declare module tanstack/solid-router { interface Register { router: typeof router } }Vue 框架同理注册到tanstack/vue-router模块的Register接口即可参见 packages/vue-router 的导出结构。注册完成后导出的 hooks、组件与工具就会携带你 router 的精确类型Link的to只接受真实存在的路由路径useNavigate能感知相对路径与 search 参数useParams自动知道当前有哪些路径参数——类型即文档编辑器即校验器。解决组件上下文问题Component Context Problem组件上下文Context在 React 等框架中是把依赖提供给组件的绝佳工具。然而当这个 context 在组件树中移动时类型会随之变化TypeScript 便无法推断这些变化。为此基于 context 的 hooks 与组件要求你给出一个「提示」说明它们在何处使用export const Route createFileRoute(/posts)({ component: PostsComponent, }) function PostsComponent() { // 每个路由都拥有 TanStack Router 内建 hooks 的类型安全版本 const params Route.useParams() const search Route.useSearch() // 有些 hooks 需要来自 *整个 router* 的 context而不仅是当前路由。 // 为了在这里获得类型安全必须传入 from 参数 // 告诉 hook 你在路由层级中的相对位置。 const navigate useNavigate({ from: Route.fullPath }) // ... etc }每个需要 context 提示的 hook 与组件都会提供一个from参数用于传入你当前渲染所在路由的 ID 或路径。 小贴士如果你的组件被代码分割code-split可以使用 getRouteApi 函数 避免传递Route.fullPath即可获得类型化的useParams()与useSearch()hooks。getRouteApi的底层实现在 packages/react-router/src/route.tsx它接受一个受ConstrainLiteralTId, RouteIds...约束的路由 ID 字面量返回一个预绑定到该路由 ID 的RouteApi实例其中的useSearch、useParams、useLoaderData等内部都自动填充了from: this.idexport function getRouteApi const TId, TRouter extends AnyRouter RegisteredRouter, (id: ConstrainLiteralTId, RouteIdsTRouter[routeTree]) { return new RouteApiTId, TRouter({ id }) }我不知道当前路由怎么办共享组件呢from属性是可选的如果不传你会得到 router 的「最佳猜测」类型——通常是一个所有路由类型的联合union。传错了from路径怎么办技术上可能存在某个from能通过 TypeScript 检查却在运行时与真实渲染路由不匹配。此时每个支持from的 hook 与组件都会检测「你的期望」与「实际渲染路由」是否一致不一致就抛出运行时错误。这正是「编译期类型安全」与「运行时兜底校验」的双保险设计。既不知道路由、又是共享组件、还不能传from如果你渲染的组件被多个路由共享或组件不在任何路由内可以改用strict: false替代from。这不仅能静默运行时错误还会给你一个「宽松但准确」的类型。最典型的场景是从共享组件调用useSearchfunction MyComponent() { const search useSearch({ strict: false }) }此时search的类型是 router 中所有路由 search params 的联合。从源码结构看strict: false会关闭运行时「实际路由与期望不符即报错」的断言同时让类型推断放宽到整个路由树的联合。Router Context终极的分层依赖注入Router context 是极其有用的工具它是最彻底的分层依赖注入你可以把 context 提供给 router也可以提供给它渲染的每一个路由。随着 context 的构建TanStack Router 会沿路由层级向下合并——每个路由都能访问其所有父路由的 context。createRootRouteWithContext工厂会创建一个携带实例化类型的新 router进而要求你为 router 履行相同的类型契约并确保整个路由树中的 context 类型正确const rootRoute createRootRouteWithContext{ whateverYouWant: true }()({ component: App, }) const routeTree rootRoute.addChildren([ // ... 所有子路由的 context 中都将拥有 whateverYouWant ]) const router createRouter({ routeTree, context: { // 从这里开始这项 context 将是必填的 whateverYouWant: true, }, })注意源码中的关键细节packages/router-core/src/router.ts 明确说明当根路由是用createRootRouteWithContext()创建时createRouter的context选项就是必填的。也就是说createRootRouteWithContextT把 T 注入路由树的同时也在编译期强制你在createRouter({ context })处补齐同样的 T——类型契约从根路由一路约束到 router 实例任何一处遗漏都会立刻报错。这带来一个额外好处beforeLoad/loader中解构出的context始终带有完整的父级 context 类型随层级逐层收窄。性能建议让 TS 检查时间随规模可控随着应用规模增长TypeScript 检查时间自然增加。下面是当应用扩大时值得留意的几个要点用于把 TS 检查耗时压下去。只推断你需要的类型配合客户端数据缓存如 TanStack Query时一个很好的模式是在loader中预取数据。例如下面这个路由在loader中调用queryClient.ensureQueryDataexport const Route createFileRoute(/posts/$postId/deep)({ loader: ({ context: { queryClient }, params: { postId } }) queryClient.ensureQueryData(postQueryOptions(postId)), component: PostDeepComponent, }) function PostDeepComponent() { const params Route.useParams() const data useSuspenseQuery(postQueryOptions(params.postId)) return / }这段代码看起来没问题在小路由树里你可能也察觉不到 TS 性能问题。但实际上TS 不得不去推断loader的返回类型——尽管它在路由里从未被使用。如果 loader 数据是复杂类型且许多路由都这样预取就会拖慢编辑器性能。此时改动非常简单让 TypeScript 推断出Promisevoid即可export const Route createFileRoute(/posts/$postId/deep)({ loader: async ({ context: { queryClient }, params: { postId } }) { await queryClient.ensureQueryData(postQueryOptions(postId)) }, component: PostDeepComponent, }) function PostDeepComponent() { const params Route.useParams() const data useSuspenseQuery(postQueryOptions(params.postId)) return / }这样 loader 数据永远不会被推断推断工作被推迟到你首次使用useSuspenseQuery时才发生复杂的返回类型便不会进入路由树的类型检查路径。尽可能收窄到相关路由看看下面两个Link用法Link to.. search{{ page: 0 }} / Link to. search{{ page: 0 }} /这两个示例对 TS 性能不利。原因在于此时search会解析为所有路由 search 参数的联合TS 必须把你传给search属性的值拿去和这个可能很大的联合做检查。随着应用增长该检查耗时会随路由数和 search 参数数量线性增长。官方已尽力优化此场景TS 通常只做一次并缓存结果但首次对大型联合的检查代价依然昂贵。params以及useSearch、useParams、useNavigate等 API 同理。应尽量用from或to收窄到相关路由Link from{Route.fullPath} to.. search{{page: 0}} / Link from/posts to.. search{{page: 0}} /记住你总是可以给to或from传一个联合来收窄感兴趣的路由集合const from: /posts/$postId/deep | /posts/ /posts/ Link from{from} to.. /你也可以给from传一个分支branch路径让search或params只从该分支的所有后代路由中解析const from /posts Link from{from} to.. //posts可能是一个拥有众多后代的分支这些后代共享相同的search或params。考虑使用addChildren的对象语法路由通常带有params、search、loader或context甚至可能引用同样重 TS 推断的外部依赖。对这种应用用对象创建路由树比用元组tuple更高效。addChildren同样接受对象。对于带复杂路由与外部库的大型路由树对象在 TS 类型检查上比大型元组快得多。性能收益取决于你的项目、外部依赖以及这些库类型的具体写法const routeTree rootRoute.addChildren({ postsRoute: postsRoute.addChildren({ postRoute, postsIndexRoute }), indexRoute, })注意这种语法更啰嗦但 TS 性能更好。使用文件式路由时路由树由生成器替你生成因此无需担心路由树过于冗长。避免使用未经收窄的内部类型你可能会想复用库暴露的类型比如像下面这样使用LinkPropsconst props: LinkProps { to: /posts/, } return ( Link {...props} )这对 TS 性能非常不利。问题在于LinkProps没有类型参数因此是一个极其庞大的类型它包含search所有 search 参数的联合、params所有 params 的联合。当把这个对象与Link合并时TS 要对这个巨型类型做结构比较。更好的做法是使用as const satisfies推断出精确类型而不是直接用LinkProps从而避开巨型检查const props { to: /posts/, } as const satisfies LinkProps return ( Link {...props} )因为props不再是LinkProps类型检查代价更低——类型精确得多。你还可以进一步收窄LinkProps来提升检查速度const props { to: /posts/, } as const satisfies LinkPropsRegisteredRouter, string, /posts return ( Link {...props} )这甚至更快因为我们是在针对收窄后的LinkProps做检查。你还可以用同样的手法把LinkProps收窄为某个特定类型作为 props 或函数参数使用export const myLinkProps [ { to: /posts, }, { to: /posts/$postId, params: { postId: postId }, }, ] as const satisfies ReadonlyArrayLinkProps export type MyLinkProps (typeof myLinkProps)[number] const MyComponent (props: { linkProps: MyLinkProps }) { return Link {...props.linkProps} / }这比在组件中直接使用LinkProps更快因为MyLinkProps是精确得多的类型。另一个解决方案是干脆不使用LinkProps而是提供控制反转inversion of control让使用者渲染一个已收窄到特定路由的Link。渲染属性render props就是向组件使用者反转控制的绝佳手段export interface MyComponentProps { readonly renderLink: () React.ReactNode } const MyComponent (props: MyComponentProps) { return div{props.renderLink()}/div } const Page () { return MyComponent renderLink{() Link to/absolute /} / }这个示例非常快因为我们已经把「导航到哪」的控制反转给了组件使用者Link被收窄到了我们想要导航的精确路由。泛型组件场景下的类型工具源码级补充除了原文档内容本仓库还提供了可直接复用的官方类型工具定义于 packages/router-core/src/typePrimitives.ts并由 packages/router-core/src/index.ts 统一导出ValidateLinkOptions、ValidateNavigateOptions、ValidateRedirectOptions及其*Array变体。它们通过ConstrainTOptions, NavigateOptions...之类的条件类型把「选项对象」约束到与具体from/to匹配的精确类型非常适合封装自定义导航组件import { Link, type RegisteredRouter, type ValidateLinkOptions, } from tanstack/react-router interface NavItemProps TRouter extends RegisteredRouter RegisteredRouter, TOptions unknown, { label: string linkOptions: ValidateLinkOptionsTRouter, TOptions } export function NavItemTRouter extends RegisteredRouter, TOptions( props: NavItemPropsTRouter, TOptions, ): React.ReactNode export function NavItem(props: NavItemProps): React.ReactNode { return ( li Link {...props.linkOptions}{props.label}/Link /li ) } // 使用完全类型安全 NavItem labelPosts linkOptions{{ to: /posts }} / NavItem labelPost linkOptions{{ to: /posts/$postId, params: { postId: 1 } }} /ValidateNavigateOptions与ValidateRedirectOptions遵循同样的模式可用于useNavigate与redirect的封装。核心要点是声明一个带泛型的公开重载再写一个非泛型的实现签名这样调用点保持收窄函数体内也无需任何类型断言。总结TanStack Router 的类型安全哲学可以浓缩为一句话让类型自己流动绝不手动标注或断言已被推断的值。从路由定义文件式 / 代码式、Register声明合并、from收窄与strict: false兜底到createRootRouteWithContext的分层 context 契约整条链路层层递进而as const satisfies、对象语法addChildren、避免未收窄的LinkProps等技巧则确保了类型安全不会以牺牲 TS 检查性能为代价。开发者因此可以写更少的类型获得更高的信心——这正是 TanStack Router 在 React / Solid / Vue 三个生态中一致的承诺。想深入了解代码分割场景下的类型化路由 API可继续阅读 docs/router/guide/code-splitting.md想查看各框架的完整实现可研读 packages/router-core/src/router.ts、packages/react-router/src/route.tsx、packages/solid-router/src/route.tsx 与 packages/vue-router/src/route.ts。【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
