Type-Safe Routing:深度解析

深入探索 TanStack Router 如何实现路由、参数、查询参数和 loader 数据的端到端类型安全,以及这对大型团队为何至关重要。

Jordan Kim
Jordan Kim
April 28, 202612 min read
其他语言:Deutsch · English

路由类型安全在大多数时候都被忽视,直到你在生产环境中被一个 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 暴露出来,且具备完整的类型推断:

tsx
// 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,在解析时对参数进行验证和转换:

tsx
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 返回的数据在组件中自动附带类型:

tsx
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),以便测试更简洁:

tsx
// 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> 组件是类型安全在日常开发中发挥作用的地方:

tsx
// 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 可以在迁移期间共存。具体方案:

  1. 将 TanStack Router 包裹在现有 router 外部
  2. 从新功能开始,逐个迁移路由
  3. 所有路由迁移完成后移除旧 router

迁移后的路由会立即展现出类型安全改进的好处,自然而然推动了迁移的持续进行。