References: Next.js / Remix / TanStack Router / Vue Router / Angular Router official docs, Web Standards History API, Stripe / Linear routing practices.
Applicable Scenarios
- Route structure design
- Nested layouts
- Dynamic routes / wildcards
- Route guards (auth / roles)
- Lazy loading (code splitting)
- Data preloading (loaders)
- Navigation transitions / scroll restoration
Core Principles
1. URL 是状态
可分享 / 可书签 / 可后退
筛选 / 分页 / 排序都该进 URL
2. 路由 = 页面
不要把弹窗 / 抽屉做成路由(除非确实需要分享)
3. 嵌套布局共享
Layout 不重复渲染
只更新内层
4. 懒加载是默认
每个路由 = 一个 chunk
首屏只加载需要的
5. 数据预加载
路由切换前并行加载(Loaders)
6. 守卫分层
全局(鉴权)+ 路由(角色)+ 组件(细粒度)
7. 404 / 错误页面统一
每层 layout 都有 fallback
Routing System Comparison
| Solution | Type | File routing | Loaders | Guards | SSR |
|---|---|---|---|---|---|
| Next.js App Router | File | ✅ | ✅ | middleware | ✅ |
| Next.js Pages Router | File | ✅ | getServerSideProps | middleware | ✅ |
| React Router 7 | Config | Optional | ✅ loaders | element | ✅ |
| TanStack Router | Type-safe | ✅ | ✅ | beforeLoad | ✅ |
| Vue Router 4 | Config | No (use Nuxt) | Hooks | beforeEach | - |
| Nuxt Router | File | ✅ | useFetch | middleware | ✅ |
| Angular Router | Config | ❌ | resolvers | guards | ✅ |
| SvelteKit | File | ✅ | load | hooks | ✅ |
Next.js App Router (recommended for React projects)
app/
├── layout.tsx ← 根布局(HTML / providers)
├── page.tsx ← /
├── (auth)/ ← 路由组(不影响 URL)
│ ├── login/page.tsx ← /login
│ └── register/page.tsx ← /register
├── (dashboard)/
│ ├── layout.tsx ← /dashboard 共享布局
│ ├── orders/
│ │ ├── page.tsx ← /orders
│ │ ├── [id]/page.tsx ← /orders/[id]
│ │ └── [id]/edit/page.tsx ← /orders/[id]/edit
│ └── users/
│ └── page.tsx
├── api/ ← API 路由
│ └── orders/route.ts
├── loading.tsx ← 加载 fallback
├── error.tsx ← 错误 fallback
└── not-found.tsx ← 404
// app/(dashboard)/orders/page.tsx
export default async function OrdersPage({ searchParams }: { searchParams: { page?: string } }) {
// Server Component:直接 await 数据
const orders = await fetchOrders({ page: searchParams.page ?? '1' });
return (
<>
<h1>Orders</h1>
<OrderList orders={orders} />
</>
);
}
// 动态路由
// app/(dashboard)/orders/[id]/page.tsx
export default async function OrderDetailPage({ params }: { params: { id: string } }) {
const order = await fetchOrder(params.id);
if (!order) notFound();
return <OrderDetail order={order} />;
}
// middleware.ts 全局守卫
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
const token = request.cookies.get('token');
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url));
}
}
export const config = { matcher: ['/dashboard/:path*'] };
React Router 7
import { createBrowserRouter, RouterProvider, redirect } from 'react-router';
const router = createBrowserRouter([
{
path: '/',
Component: RootLayout,
errorElement: <ErrorBoundary />,
children: [
{ index: true, Component: Home },
{ path: 'login', Component: Login },
{
path: 'dashboard',
Component: DashboardLayout,
loader: requireAuth, // 守卫
children: [
{
path: 'orders',
Component: OrderList,
loader: async ({ request }) => {
const url = new URL(request.url);
const page = url.searchParams.get('page') ?? '1';
return await fetchOrders({ page });
},
},
{
path: 'orders/:id',
Component: OrderDetail,
loader: async ({ params }) => {
const order = await fetchOrder(params.id);
if (!order) throw new Response('Not Found', { status: 404 });
return order;
},
},
],
},
],
},
]);
// 守卫
async function requireAuth({ request }: LoaderFunctionArgs) {
const user = await getCurrentUser();
if (!user) {
const params = new URLSearchParams({ redirect: new URL(request.url).pathname });
throw redirect(`/login?${params}`);
}
return user;
}
// 用 loader 数据
function OrderList() {
const orders = useLoaderData() as Order[];
return <List items={orders} />;
}
// 主入口
<RouterProvider router={router} />
TanStack Router (type-safe)
// routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router';
export const Route = createRootRoute({
component: () => (
<>
<Header />
<Outlet />
</>
),
});
// routes/orders/$id.tsx
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/orders/$id')({
beforeLoad: async ({ params }) => {
const user = await requireAuth();
return { user };
},
loader: async ({ params }) => {
return await fetchOrder(params.id);
},
component: OrderDetail,
});
function OrderDetail() {
const { id } = Route.useParams(); // 类型安全
const order = Route.useLoaderData(); // 类型安全
return <div>{order.title}</div>;
}
Vue Router 4
// router/index.ts
import { createRouter, createWebHistory } from 'vue-router';
const routes = [
{ path: '/', component: () => import('@/pages/Home.vue') },
{ path: '/login', component: () => import('@/pages/Login.vue') },
{
path: '/dashboard',
component: () => import('@/layouts/Dashboard.vue'),
meta: { requiresAuth: true },
children: [
{ path: 'orders', component: () => import('@/pages/orders/List.vue') },
{ path: 'orders/:id', component: () => import('@/pages/orders/Detail.vue') },
],
},
{ path: '/:pathMatch(.*)*', component: () => import('@/pages/NotFound.vue') },
];
const router = createRouter({ history: createWebHistory(), routes });
// 全局守卫
router.beforeEach(async (to) => {
const userStore = useUserStore();
if (to.meta.requiresAuth && !userStore.user) {
return { path: '/login', query: { redirect: to.fullPath } };
}
});
export default router;
<!-- 使用 -->
<script setup lang="ts">
import { useRoute, useRouter } from 'vue-router';
const route = useRoute();
const router = useRouter();
const id = computed(() => route.params.id as string);
async function navigateToEdit() {
await router.push(`/orders/${id.value}/edit`);
}
</script>
<template>
<RouterLink to="/orders/123">Order 123</RouterLink>
<RouterView />
</template>
SvelteKit
src/routes/
├── +layout.svelte ← 根布局
├── +page.svelte ← /
├── login/+page.svelte ← /login
├── dashboard/
│ ├── +layout.svelte ← /dashboard 布局
│ ├── +layout.server.ts ← 服务端守卫
│ └── orders/
│ ├── +page.svelte
│ ├── +page.ts ← Universal load
│ └── [id]/+page.svelte
├── +error.svelte ← 错误页
└── hooks.server.ts ← 全局守卫
// routes/dashboard/+layout.server.ts
import { redirect } from '@sveltejs/kit';
export async function load({ cookies }) {
const token = cookies.get('token');
if (!token) throw redirect(303, '/login');
return { user: await getUser(token) };
}
// routes/orders/[id]/+page.ts
import { error } from '@sveltejs/kit';
export async function load({ params, fetch }) {
const res = await fetch(`/api/orders/${params.id}`);
if (!res.ok) throw error(404, 'Order not found');
return { order: await res.json() };
}
Angular Router
// app.routes.ts
import { Routes } from '@angular/router';
import { authGuard } from './guards/auth.guard';
export const routes: Routes = [
{ path: '', loadComponent: () => import('./home/home.component').then(m => m.HomeComponent) },
{ path: 'login', loadComponent: () => import('./auth/login.component').then(m => m.LoginComponent) },
{
path: 'dashboard',
canActivate: [authGuard],
loadComponent: () => import('./layouts/dashboard.component').then(m => m.DashboardComponent),
children: [
{ path: 'orders', loadComponent: () => import('./orders/list.component').then(m => m.OrderListComponent) },
{
path: 'orders/:id',
loadComponent: () => import('./orders/detail.component').then(m => m.OrderDetailComponent),
resolve: { order: orderResolver },
},
],
},
{ path: '**', loadComponent: () => import('./not-found.component').then(m => m.NotFoundComponent) },
];
// guards/auth.guard.ts
import { inject } from '@angular/core';
import { Router } from '@angular/router';
export const authGuard = () => {
const auth = inject(AuthService);
const router = inject(Router);
if (!auth.isLoggedIn()) {
router.navigate(['/login']);
return false;
}
return true;
};
URL State (search / filter / pagination)
// React + nuqs(推荐)
import { useQueryState, useQueryStates, parseAsInteger, parseAsString } from 'nuqs';
function ProductList() {
const [search, setSearch] = useQueryState('q', parseAsString.withDefault(''));
const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
const [filters, setFilters] = useQueryStates({
category: parseAsString,
sort: parseAsString.withDefault('newest'),
});
// URL 自动 sync
// ?q=keyboard&page=2&category=electronics&sort=price-asc
}
<!-- Vue 3 -->
<script setup>
import { useRoute, useRouter } from 'vue-router';
const route = useRoute();
const router = useRouter();
const search = computed({
get: () => route.query.q as string ?? '',
set: (val) => router.push({ query: { ...route.query, q: val || undefined } }),
});
</script>
Guard Layers
1. 全局守卫(middleware)
- 鉴权检查
- i18n 重定向
- A/B 测试分流
2. 路由级守卫(guard / loader)
- 角色权限
- 数据预加载
- 重定向
3. 组件级守卫
- 字段权限
- 二次确认(弹框)
Lazy Loading (Code Splitting)
// React
const OrderList = lazy(() => import('./pages/OrderList'));
<Suspense fallback={<Skeleton />}>
<OrderList />
</Suspense>
// Vue
{ component: () => import('./pages/OrderList.vue') }
// Angular
loadComponent: () => import('./order-list/order-list.component').then(m => m.OrderListComponent)
// 自动:Next.js / Nuxt / SvelteKit 默认每页面一 chunk
Scroll Restoration
浏览器后退应回到原位置:
Next.js / Nuxt / SvelteKit:默认支持
React Router 7:<ScrollRestoration /> 组件
Vue Router:scrollBehavior 配置
Workflow
1. 设计 URL 结构(与 PM 同步)
- RESTful:/users / /users/:id / /users/:id/edit
- 不在 URL 暴露内部信息
2. 列路由清单
- 公开 vs 需登录 vs 角色限定
3. 设计布局
- 嵌套 layout(共享 sidebar / header)
4. 实现路由
- 文件路由(如可)
- 懒加载所有页面
5. 守卫
- 全局:登录
- 路由级:角色
- 组件级:字段权限
6. 数据预加载(loaders)
- 并行加载
7. 错误 / 404 / loading 页面
8. URL 状态(筛选 / 分页)
9. 滚动恢复 / 过渡
10. 测试
Supporting Templates
templates/routing-template.md— route table + guards + lazy loading + URL state + error handling
Quality Self-Check
□ URL 结构清晰
□ 嵌套布局共享
□ 所有页面懒加载
□ 鉴权全局守卫
□ 角色路由级守卫
□ 数据预加载(loaders)
□ 404 / 错误 / loading 页面
□ URL 状态用 search params
□ 滚动恢复
□ 不暴露内部 ID(如可)
□ 路由测试覆盖
Common Pitfalls
- Making modals into routes——back button opens them
- Filter parameters not in URL——lost on refresh, cannot be shared
- Guards only on the frontend——calling the API directly still grants access
- No lazy loading——1MB of JS on first screen
- Nested layout duplicate requests——loader not layered correctly
- 404 not unified——each page writes its own
- No loading on route change——blank screen
- Scroll not restored——back goes to top
- URL exposes internal ID——crawling / privilege escalation
- Route parameters not decoded——garbled Chinese characters
- Not using prefetch——hover can already preload
- Hash routing vs History——SEO failure
- Guard returns false without redirecting——blank screen
Collaboration with Other Skills
上游:
ui-ux-designer 工作流 user-flow → 路由结构
api-designer auth-permission → 角色矩阵
下游:
state-management → URL 状态
data-fetching → loader / prefetch
performance-optimization → 懒加载
accessibility-implementation → 焦点管理
Related References
- Project root
references/frontend-tech-stack-guide.md— routing library