路由类型安全在大多数时候都被忽视,直到你在生产环境中被一个 undefined 路由参数或一个拼写错误的 URL 坑过。TanStack Router v1 从根本上解决了这一问题。让我们深入了解它的工作原理,以及架构决策背后的原因。
路由树
每个 TanStack Router 应用都有一棵路由树——一种表示所有可能导航状态的类型化数据结构:
关键洞察:这棵树是根据你的文件结构自动生成的,并成为一个 TypeScript 类型。每一次导航操作都在编译时对照该类型进行检查。
类型推断如何工作
创建路由文件时,TanStack Router 会根据文件名推断参数类型:
blog.$slug.tsx → params: { slug: string }
users.$userId.tsx → params: { userId: string }
org.$orgId.repo.$repoId.tsx → params: { orgId: string, repoId: string }
这些类型通过 Route.useParams() hook 暴露出来,且具备完整的类型推断:
// In blog.$slug.tsx
export const Route = createFileRoute('/blog/$slug')({
component: BlogPost,
})
function BlogPost() {
// TypeScript 知道 `slug` 是 string,无需手动类型转换
const { slug } = Route.useParams()
return <article>{slug}</article>
}
经过验证的查询参数
原始查询参数都是字符串——但你很少真的想要字符串。TanStack Router 允许你用 Zod 定义 Schema,在解析时对参数进行验证和转换:
import { z } from 'zod'
const productsSearch = z.object({
page: z.number().catch(1), // 无效时默认值为 1
sort: z.enum(['price', 'name', 'date']).catch('name'),
minPrice: z.number().optional(),
maxPrice: z.number().optional(),
inStock: z.boolean().default(true),
})
export const Route = createFileRoute('/products')({
validateSearch: productsSearch,
component: ProductsPage,
})
function ProductsPage() {
// 类型完整:page 是 number,sort 是 'price'|'name'|'date' 等
const { page, sort, minPrice, inStock } = Route.useSearch()
}
catch() 方法至关重要——它意味着无效的 URL 会优雅降级,而不会导致崩溃。
Loader 数据类型
路由 loader 返回的数据在组件中自动附带类型:
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
// 返回类型从这里推断
const post = await db.posts.findUnique({ where: { id: params.postId } })
if (!post) throw notFound()
const author = await db.users.findUnique({ where: { id: post.authorId } })
return { post, author }
},
component: PostPage,
})
function PostPage() {
// TypeScript 知道 post 和 author 的确切形状
const { post, author } = Route.useLoaderData()
return (
<article>
<h1>{post.title}</h1>
<p>作者:{author?.name}</p>
</article>
)
}
Context 与依赖注入
通过路由 context 传递依赖(如 queryClient),以便测试更简洁:
// router.tsx
const router = createRouter({
routeTree,
context: {
queryClient,
auth: undefined as AuthState | undefined,
},
})
// 在任意路由 loader 中
export const Route = createFileRoute('/dashboard')({
beforeLoad: ({ context }) => {
if (!context.auth) throw redirect({ to: '/login' })
},
loader: async ({ context }) => {
return context.queryClient.ensureQueryData(dashboardQueryOptions())
},
})
Link 组件
<Link> 组件是类型安全在日常开发中发挥作用的地方:
// TypeScript 强制校验路由和参数的合法性
<Link to="/blog/$slug" params={{ slug: post.slug }}>阅读更多</Link>
// 查询参数同样具备类型
<Link to="/products" search={{ page: 2, sort: 'price' }}>下一页</Link>
// 无效路由在编译时报错,而非运行时
<Link to="/nont-existent">报错!</Link>
// ^^^^^^^^^^^^^^^
// 类型错误:'/nont-existent' 不能赋值给任何合法路由路径
这对团队为何重要
在大型团队中,路由 bug 的代价是叠加的:
- 开发者修改了一个路由路径 → 应用中所有相关链接静默失效
- URL 参数拼写错误 → 引发难以追踪的 404
- 新增了一个必填参数 → 其他页面忘记传递该参数
使用 TanStack Router,上述所有问题都变成 CI 在上线前就能捕获的编译错误。前期投入的搭建成本,在第一次阻止生产事故发生时就已经回本了。
迁移路径
已经在使用 React Router 或 Next.js?TanStack Router 可以在迁移期间共存。具体方案:
- 将 TanStack Router 包裹在现有 router 外部
- 从新功能开始,逐个迁移路由
- 所有路由迁移完成后移除旧 router
迁移后的路由会立即展现出类型安全改进的好处,自然而然推动了迁移的持续进行。