路由与页签
讲解 TanStack 文件路由的目录约定、后端菜单的加载与访问守卫、占位页机制与页签栏的行为。
新增一个业务页面、或菜单配好了却打不开时,读这页。路由由 TanStack Router 的文件路由承担:src/routes/ 目录即路由表,Vite 插件(vite.config.ts 的 tanstackRouter)把目录结构编译成 src/routeTree.gen.ts。菜单数据完全由后端下发,前端目录决定「路径怎么对应组件」,后端菜单决定「用户能看到什么」。
路由目录
src/routes/ 下的分段如下,括号分段((main)、(app))只做分组,不进 URL。
| 路径 | 内容 |
|---|---|
__root.tsx | 根路由:挂载认证、外观偏好 Provider 与全局 Toaster,统一 404 与错误页 |
(external)/index.tsx | 根路径重定向到 /dashboard |
(main)/(app)/route.tsx | 登录后业务区的布局路由:守卫、菜单加载、BaseLayout 都在这一层 |
(main)/(app)/<模块>/route.tsx | 业务页面,如 system/user/route.tsx |
(main)/(app)/$.tsx | 兜底占位页:菜单里有、前端还没有对应页面时显示 |
(main)/auth/ | 登录页(登录前可达) |
(main)/social/callback | 第三方登录回调(登录前可达) |
(main)/unauthorized.tsx | 无权限页 |
routes/-components/ | 跨路由共享的路由级组件(404、错误页、状态页),不参与路由 |
业务模块按后端功能域分目录:dashboard、monitor(log、online)、open/app、schedule(job、log)、system(config、dept、dict、file、menu、notice、role、sms、user)、tenant(management、package)。每个页面目录里,route.tsx 是路由入口,页面私有组件放同目录的 -components/,横线前缀的目录不参与路由。
页面文件本身很薄,组件放 -components/ 里(src/routes/(main)/(app)/system/user/route.tsx):
import { createFileRoute } from '@tanstack/react-router'
import { UserList } from './-components/user-list'
export const Route = createFileRoute('/(main)/(app)/system/user')({
component: UserList
})新增页面的约定
新页面 = 在 src/routes/(main)/(app)/ 下按菜单路径建目录并写一个 route.tsx。菜单的「组件路径」字段(component)在新前端的用途是占位页里的提示:占位页把 system/user/index 这类值换算成建议路径 src/routes/(main)/(app)/system/user/route.tsx 显示出来(src/routes/(main)/(app)/$.tsx:31),文件建好后占位页消失,路由直接命中。
菜单路径 /system/goods,组件路径 system/goods/index
→ 建文件 src/routes/(main)/(app)/system/goods/route.tsx菜单里配了入口但文件还没建时,访问该路径会显示一张 Construction 卡片,标注菜单标题与建议文件路径,不是 404。这是刻意设计:菜单先配、页面渐进补齐,缺口一目了然。
菜单加载与守卫
菜单来自 GET /auth/user/route(src/lib/api/auth.ts 的 getUserRoutes),后端已按当前用户权限过滤。加载逻辑在 src/hooks/use-menu.ts:查询键 MENU_QUERY_KEY = ['auth', 'menu'](use-menu.ts:15),请求结果写入 localStorage 缓存(src/lib/menu-cache.ts,键 continew.menu-cache),下次进入应用先用缓存渲染、后台静默重新校验,只有首次登录才等待网络请求。
守卫链挂在 (main)/(app)/route.tsx 的 beforeLoad(src/routes/(main)/(app)/route.tsx:14),按顺序执行三步。
- 登录判定:
requireAuth(src/lib/auth-guard.ts)检查 Access Token,没有就跳/auth/login并带上目标地址redirect参数;/auth、/unauthorized是公开路径不拦。 - 菜单加载:
ensureMenuLoaded等菜单就绪。菜单决定「这个用户有哪些页面」,必须先于页面渲染落定;菜单请求期间会话过期的话,第二步的requireAuth会再次兜底。 - 访问控制:
requireRouteAccess(src/lib/route-access.ts)核对当前路径是否在菜单里。菜单由后端按权限过滤过,不在菜单里等于没权限,跳/unauthorized。两种情况放行:$兜底路由自己处理未知路径;菜单为空也放行(菜单接口偶发失败时不能把所有用户锁在门外,让页面自己的请求去回答 403)。
侧边栏的分组由 src/navigation/menu.ts 的 toMenuGroups 转换:顶级目录变标签组,菜单变链接项,更深的目录拍平成一层子项;类型 3(按钮)与 isHidden 节点不出现在侧边栏。应用自有的静态入口(/dashboard,STATIC_MENU_ITEMS)不依赖 sys_menu 记录,始终排在最前。菜单节点还带 isExternal(外链新开标签页)与 redirect(占位页直接跳转)字段。
菜单里隐藏(isHidden)的节点不出现在侧边栏,但只要在菜单树里就仍然可以访问。访问控制看的是「菜单树里有没有」,与显不显示无关。
页签
页签状态在 zustand store src/stores/tabs.ts,默认持久化到 sessionStorage(键 continew_in_header_tabs,外观偏好 tabbar_persist 关闭时停止写入并清空)。/dashboard 是固定页签,不可关闭。
核心行为:
- 打开页面时经
addTab追加页签,超出tabbar_max_count上限时按访问历史淘汰最久未访问的页签(0 表示不限); - 关闭当前页签时按访问历史回退到上一个页签(
closeTab返回的路径驱动导航); - 支持关闭其他/左侧/右侧/全部、固定(固定页签排前且只能在自己区内排序)、拖拽排序(dnd-kit);
- 菜单变化后
pruneTabs清掉已不在菜单里的页签;登出经resetTabs重置。
页签切换没有组件级缓存。切走的页面组件会卸载,切回时重新挂载;列表数据命中 TanStack Query 缓存(默认 5 分钟新鲜期),不会重新转圈。菜单管理里的 isCache 字段只是登记项,当前前端没有对应的缓存实现。页签上的刷新按钮走另一条路:src/stores/shell.ts 的 refresh 计数器加一,页面内容以该计数为 key 重新挂载,等效于「强制刷新当前页面」。
相关源码
- src/routes/:文件路由目录全貌
- src/hooks/use-menu.ts:菜单查询、缓存与侧边栏分组入口
- src/navigation/menu.ts:菜单树到分组/页签的转换与路径判定
- src/lib/route-access.ts:路由访问守卫
- src/stores/tabs.ts:页签 store 与持久化
- MenuController.java:菜单数据的后端来源