604 lines
12 KiB
Markdown
604 lines
12 KiB
Markdown
# Nova Admin 路由系统文档
|
|
|
|
## 概述
|
|
|
|
Nova Admin 基于 Vue Router 4 构建了一套完整的路由管理系统，支持静态路由和动态路由，具备完善的路由守卫、权限控制、菜单生成等功能。
|
|
|
|
## 🏗️ 路由架构
|
|
|
|
### 核心组件
|
|
|
|
1. **路由配置** (`src/router/`)
|
|
2. **路由守卫** (`src/router/guard.ts`)
|
|
3. **路由状态管理** (`src/store/router/`)
|
|
4. **菜单生成** (`src/store/router/helper.ts`)
|
|
5. **标签页管理** (`src/store/tab.ts`)
|
|
|
|
### 文件结构
|
|
|
|
```
|
|
src/router/
|
|
├── index.ts # 路由主配置文件
|
|
├── guard.ts # 路由守卫
|
|
├── routes.inner.ts # 内置路由（登录、错误页等）
|
|
└── routes.static.ts # 静态路由配置
|
|
|
|
src/store/router/
|
|
├── index.ts # 路由状态管理
|
|
└── helper.ts # 路由处理辅助函数
|
|
```
|
|
|
|
## 🛣️ 路由类型
|
|
|
|
### 1. 内置路由 (Inner Routes)
|
|
|
|
位置：`src/router/routes.inner.ts`
|
|
|
|
包含系统基础路由：
|
|
- 根路由 (`/`)
|
|
- 登录页 (`/login`)
|
|
- 错误页 (`/403`, `/404`, `/500`)
|
|
- 通配符路由 (404 处理)
|
|
|
|
```typescript
|
|
export const routes: RouteRecordRaw[] = [
|
|
{
|
|
path: '/',
|
|
name: 'root',
|
|
redirect: '/appRoot',
|
|
},
|
|
{
|
|
path: '/login',
|
|
name: 'login',
|
|
component: () => import('@/views/login/index.vue'),
|
|
meta: {
|
|
title: '登录',
|
|
withoutTab: true,
|
|
},
|
|
},
|
|
// ... 错误页路由
|
|
]
|
|
```
|
|
|
|
### 2. 静态路由 (Static Routes)
|
|
|
|
位置：`src/router/routes.static.ts`
|
|
|
|
业务功能路由配置：
|
|
|
|
```typescript
|
|
export const staticRoutes: AppRoute.RowRoute[] = [
|
|
{
|
|
name: 'monitor',
|
|
path: '/dashboard/monitor',
|
|
title: '仪表盘',
|
|
requiresAuth: true,
|
|
icon: 'icon-park-outline:anchor',
|
|
menuType: 'page',
|
|
componentPath: '/dashboard/monitor/index.vue',
|
|
id: 3,
|
|
pid: null,
|
|
},
|
|
// ... 其他业务路由
|
|
]
|
|
```
|
|
|
|
### 3. 动态路由 (Dynamic Routes)
|
|
|
|
通过 API 从后端获取的路由配置，结构与静态路由相同。
|
|
|
|
## 📋 路由数据结构
|
|
|
|
### AppRoute.RowRoute 接口
|
|
|
|
```typescript
|
|
interface AppRoute.RowRoute {
|
|
/** 路由名称 */
|
|
name: string
|
|
/** 路由路径 */
|
|
path: string
|
|
/** 页面标题 */
|
|
title: string
|
|
/** 是否需要认证 */
|
|
requiresAuth?: boolean
|
|
/** 访问角色 */
|
|
roles?: Entity.RoleType[]
|
|
/** 图标 */
|
|
icon?: string
|
|
/** 菜单类型 */
|
|
menuType?: 'dir' | 'page'
|
|
/** 组件路径 */
|
|
componentPath?: string | null
|
|
/** 路由ID */
|
|
id: number
|
|
/** 父路由ID */
|
|
pid: number | null
|
|
/** 是否隐藏 */
|
|
hide?: boolean
|
|
/** 排序权重 */
|
|
order?: number
|
|
/** 外链地址 */
|
|
href?: string
|
|
/** 激活菜单 */
|
|
activeMenu?: string
|
|
/** 不显示标签页 */
|
|
withoutTab?: boolean
|
|
/** 固定标签页 */
|
|
pinTab?: boolean
|
|
/** 是否缓存 */
|
|
keepAlive?: boolean
|
|
}
|
|
```
|
|
|
|
### 路由元信息 (Meta)
|
|
|
|
```typescript
|
|
interface RouteMeta {
|
|
/** 页面标题 */
|
|
title: string
|
|
/** 图标 */
|
|
icon?: string
|
|
/** 是否需要认证 */
|
|
requiresAuth?: boolean
|
|
/** 访问角色 */
|
|
roles?: Entity.RoleType[]
|
|
/** 是否缓存 */
|
|
keepAlive?: boolean
|
|
/** 是否隐藏 */
|
|
hide?: boolean
|
|
/** 排序权重 */
|
|
order?: number
|
|
/** 外链地址 */
|
|
href?: string
|
|
/** 激活菜单 */
|
|
activeMenu?: string
|
|
/** 不显示标签页 */
|
|
withoutTab?: boolean
|
|
/** 固定标签页 */
|
|
pinTab?: boolean
|
|
/** 菜单类型 */
|
|
menuType?: 'dir' | 'page'
|
|
}
|
|
```
|
|
|
|
## 🔄 路由处理流程
|
|
|
|
### 1. 路由初始化流程
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant App as 应用启动
|
|
participant Router as 路由系统
|
|
participant Guard as 路由守卫
|
|
participant Store as RouteStore
|
|
participant API as 后端API
|
|
|
|
App->>Router: 创建路由实例
|
|
Router->>Guard: 安装路由守卫
|
|
App->>Store: 初始化路由状态
|
|
|
|
Note over Router,Store: 用户访问路由时
|
|
Router->>Guard: beforeEach 触发
|
|
Guard->>Store: 检查路由是否初始化
|
|
Store->>Store: initAuthRoute()
|
|
|
|
alt 动态路由模式
|
|
Store->>API: fetchUserRoutes()
|
|
API-->>Store: 返回用户路由数据
|
|
else 静态路由模式
|
|
Store->>Store: 使用 staticRoutes
|
|
end
|
|
|
|
Store->>Store: createRoutes() 生成路由
|
|
Store->>Router: addRoute() 注册路由
|
|
Store->>Store: createMenus() 生成菜单
|
|
Guard->>Router: next() 继续导航
|
|
```
|
|
|
|
### 2. 路由守卫执行流程
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[路由跳转] --> B{外链路由?}
|
|
B -->|是| C[打开新窗口]
|
|
B -->|否| D[开始 LoadingBar]
|
|
|
|
D --> E{登录页?}
|
|
E -->|是| F[直接放行]
|
|
E -->|否| G{requiresAuth=false?}
|
|
G -->|是| F
|
|
G -->|否| H{需要认证且未登录?}
|
|
H -->|是| I[重定向到登录页]
|
|
H -->|否| J{路由已初始化?}
|
|
|
|
J -->|否| K[初始化路由]
|
|
K --> L{是404页面?}
|
|
L -->|是| M[重新导航到正确路径]
|
|
L -->|否| N[继续导航]
|
|
|
|
J -->|是| O{已登录访问登录页?}
|
|
O -->|是| P[重定向到首页]
|
|
O -->|否| N
|
|
|
|
F --> N
|
|
N --> Q[设置菜单高亮]
|
|
Q --> R[添加标签页]
|
|
R --> S[设置页面标题]
|
|
S --> T[结束 LoadingBar]
|
|
```
|
|
|
|
## 🎯 路由守卫详解
|
|
|
|
### beforeEach 守卫
|
|
|
|
位置：`src/router/guard.ts`
|
|
|
|
#### 主要功能
|
|
|
|
1. **外链处理**: 检测并打开外部链接
|
|
2. **进度条控制**: 开始 LoadingBar
|
|
3. **登录验证**: 检查用户认证状态
|
|
4. **路由初始化**: 动态加载和注册路由
|
|
5. **重定向处理**: 处理各种重定向场景
|
|
|
|
#### 核心逻辑
|
|
|
|
```typescript
|
|
router.beforeEach(async (to, from, next) => {
|
|
// 1. 外链处理
|
|
if (to.meta.href) {
|
|
window.open(to.meta.href)
|
|
next(false)
|
|
return
|
|
}
|
|
|
|
// 2. 开始进度条
|
|
appStore.showProgress && window.$loadingBar?.start()
|
|
|
|
// 3. 登录验证
|
|
const isLogin = Boolean(local.get('accessToken'))
|
|
|
|
if (to.meta.requiresAuth === true && !isLogin) {
|
|
const redirect = to.name === '404' ? undefined : to.fullPath
|
|
next({ path: '/login', query: { redirect } })
|
|
return
|
|
}
|
|
|
|
// 4. 路由初始化
|
|
if (!routeStore.isInitAuthRoute) {
|
|
await routeStore.initAuthRoute()
|
|
if (to.name === '404') {
|
|
next({ path: to.fullPath, replace: true })
|
|
return
|
|
}
|
|
}
|
|
|
|
// 5. 登录页重定向
|
|
if (to.name === 'login' && isLogin) {
|
|
next({ path: '/' })
|
|
return
|
|
}
|
|
|
|
next()
|
|
})
|
|
```
|
|
|
|
### beforeResolve 守卫
|
|
|
|
```typescript
|
|
router.beforeResolve((to) => {
|
|
// 设置菜单高亮
|
|
routeStore.setActiveMenu(to.meta.activeMenu ?? to.fullPath)
|
|
// 添加标签页
|
|
tabStore.addTab(to)
|
|
// 设置当前标签页
|
|
tabStore.setCurrentTab(to.fullPath)
|
|
})
|
|
```
|
|
|
|
### afterEach 守卫
|
|
|
|
```typescript
|
|
router.afterEach((to) => {
|
|
// 设置页面标题
|
|
document.title = `${to.meta.title} - ${title}`
|
|
// 结束进度条
|
|
appStore.showProgress && window.$loadingBar?.finish()
|
|
})
|
|
```
|
|
|
|
## 🏪 路由状态管理
|
|
|
|
### RouteStore 状态
|
|
|
|
```typescript
|
|
interface RoutesStatus {
|
|
/** 路由是否已初始化 */
|
|
isInitAuthRoute: boolean
|
|
/** 菜单数据 */
|
|
menus: MenuOption[]
|
|
/** 原始路由数据 */
|
|
rowRoutes: AppRoute.RowRoute[]
|
|
/** 当前激活菜单 */
|
|
activeMenu: string | null
|
|
/** 缓存路由 */
|
|
cacheRoutes: string[]
|
|
}
|
|
```
|
|
|
|
### 核心方法
|
|
|
|
#### initAuthRoute()
|
|
|
|
初始化认证路由的完整流程：
|
|
|
|
```typescript
|
|
async initAuthRoute() {
|
|
this.isInitAuthRoute = false
|
|
|
|
// 1. 获取路由数据
|
|
const rowRoutes = await this.initRouteInfo()
|
|
if (!rowRoutes) return
|
|
|
|
this.rowRoutes = rowRoutes
|
|
|
|
// 2. 生成实际路由并注册
|
|
const routes = createRoutes(rowRoutes)
|
|
router.addRoute(routes)
|
|
|
|
// 3. 生成侧边菜单
|
|
this.menus = createMenus(rowRoutes)
|
|
|
|
// 4. 生成路由缓存
|
|
this.cacheRoutes = generateCacheRoutes(rowRoutes)
|
|
|
|
this.isInitAuthRoute = true
|
|
}
|
|
```
|
|
|
|
#### initRouteInfo()
|
|
|
|
根据配置模式获取路由信息：
|
|
|
|
```typescript
|
|
async initRouteInfo() {
|
|
if (import.meta.env.VITE_ROUTE_LOAD_MODE === 'dynamic') {
|
|
// 动态路由：从 API 获取
|
|
const userInfo = local.get('userInfo')
|
|
const { data } = await fetchUserRoutes({ id: userInfo.id })
|
|
return data
|
|
} else {
|
|
// 静态路由：使用本地配置
|
|
this.rowRoutes = staticRoutes
|
|
return staticRoutes
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🎨 菜单生成
|
|
|
|
### 菜单生成流程
|
|
|
|
```typescript
|
|
export function createMenus(routes: AppRoute.RowRoute[]) {
|
|
const { hasPermission } = usePermission()
|
|
|
|
// 1. 权限过滤
|
|
let resultMenus = routes.filter(i => hasPermission(i.roles))
|
|
|
|
// 2. 隐藏项过滤
|
|
resultMenus = resultMenus.filter(i => !i.hide)
|
|
|
|
// 3. 转换菜单格式
|
|
const menus = resultMenus.map(transformRouteToMenu)
|
|
|
|
// 4. 生成菜单树
|
|
return arrayToTree(menus)
|
|
}
|
|
```
|
|
|
|
### 菜单数据结构
|
|
|
|
```typescript
|
|
interface MenuOption {
|
|
label: string // 菜单标题
|
|
key: string // 菜单键值
|
|
icon?: () => VNode // 菜单图标
|
|
children?: MenuOption[] // 子菜单
|
|
disabled?: boolean // 是否禁用
|
|
}
|
|
```
|
|
|
|
## 🏷️ 标签页系统
|
|
|
|
### TabStore 管理
|
|
|
|
标签页系统与路由系统紧密集成：
|
|
|
|
```typescript
|
|
// 添加标签页
|
|
tabStore.addTab(route)
|
|
|
|
// 设置当前标签页
|
|
tabStore.setCurrentTab(route.fullPath)
|
|
|
|
// 关闭标签页
|
|
tabStore.closeTab(fullPath)
|
|
```
|
|
|
|
### 特殊标签页类型
|
|
|
|
1. **固定标签页** (`pinTab: true`): 不可关闭的标签页
|
|
2. **无标签页** (`withoutTab: true`): 不显示在标签栏的页面
|
|
|
|
## ⚙️ 配置选项
|
|
|
|
### 环境变量
|
|
|
|
```bash
|
|
# 路由加载模式
|
|
VITE_ROUTE_LOAD_MODE=static|dynamic
|
|
|
|
# 默认首页路径
|
|
VITE_HOME_PATH=/dashboard/monitor
|
|
|
|
# 应用名称
|
|
VITE_APP_NAME=Nova Admin
|
|
```
|
|
|
|
### 路由模式配置
|
|
|
|
```typescript
|
|
// vite.config.ts 或 .env 文件
|
|
const { VITE_ROUTE_MODE = 'hash', VITE_BASE_URL } = import.meta.env
|
|
|
|
export const router = createRouter({
|
|
history: VITE_ROUTE_MODE === 'hash'
|
|
? createWebHashHistory(VITE_BASE_URL)
|
|
: createWebHistory(VITE_BASE_URL),
|
|
routes,
|
|
})
|
|
```
|
|
|
|
## 🛠️ 开发指南
|
|
|
|
### 1. 添加新路由
|
|
|
|
#### 静态路由方式
|
|
|
|
在 `src/router/routes.static.ts` 中添加：
|
|
|
|
```typescript
|
|
{
|
|
name: 'newPage',
|
|
path: '/new-page',
|
|
title: '新页面',
|
|
requiresAuth: true,
|
|
icon: 'icon-park-outline:new',
|
|
menuType: 'page',
|
|
componentPath: '/new/page/index.vue',
|
|
id: 100,
|
|
pid: null,
|
|
}
|
|
```
|
|
|
|
#### 动态路由方式
|
|
|
|
通过后端 API 返回路由配置，格式与静态路由相同。
|
|
|
|
### 2. 路由权限配置
|
|
|
|
```typescript
|
|
{
|
|
name: 'adminPage',
|
|
path: '/admin',
|
|
title: '管理页面',
|
|
requiresAuth: true,
|
|
roles: ['admin', 'super'], // 权限控制
|
|
// ...
|
|
}
|
|
```
|
|
|
|
### 3. 嵌套路由
|
|
|
|
```typescript
|
|
// 父路由
|
|
{
|
|
name: 'parent',
|
|
path: '/parent',
|
|
title: '父级菜单',
|
|
menuType: 'dir',
|
|
componentPath: null,
|
|
id: 1,
|
|
pid: null,
|
|
}
|
|
|
|
// 子路由
|
|
{
|
|
name: 'child',
|
|
path: '/parent/child',
|
|
title: '子级菜单',
|
|
menuType: 'page',
|
|
componentPath: '/parent/child/index.vue',
|
|
id: 2,
|
|
pid: 1, // 指向父路由ID
|
|
}
|
|
```
|
|
|
|
### 4. 路由缓存
|
|
|
|
```typescript
|
|
{
|
|
name: 'cachedPage',
|
|
path: '/cached',
|
|
title: '缓存页面',
|
|
keepAlive: true, // 启用路由缓存
|
|
// ...
|
|
}
|
|
```
|
|
|
|
## 🐛 常见问题
|
|
|
|
### 1. 动态路由不生效
|
|
|
|
检查：
|
|
- 路由数据格式是否正确
|
|
- 组件路径是否存在
|
|
- 权限配置是否正确
|
|
|
|
### 2. 菜单不显示
|
|
|
|
检查：
|
|
- `hide` 属性是否为 `true`
|
|
- 权限验证是否通过
|
|
- `menuType` 是否正确设置
|
|
|
|
### 3. 404 页面循环
|
|
|
|
确保：
|
|
- 静态路由已正确配置
|
|
- 路由初始化完成
|
|
- 通配符路由放在最后
|
|
|
|
### 4. 标签页问题
|
|
|
|
检查：
|
|
- `withoutTab` 设置
|
|
- 路由路径是否正确
|
|
- TabStore 状态是否正常
|
|
|
|
## 🎯 最佳实践
|
|
|
|
### 1. 路由命名规范
|
|
|
|
```typescript
|
|
// 推荐命名方式
|
|
name: 'userManagement' // 驼峰命名
|
|
name: 'user-management' // 中划线命名
|
|
name: 'user_management' // 下划线命名
|
|
```
|
|
|
|
### 2. 路径规范
|
|
|
|
```typescript
|
|
// 路径应该语义化
|
|
path: '/user/management' // ✅ 好的
|
|
path: '/user/mgmt' // ❌ 避免缩写
|
|
path: '/u/m' // ❌ 避免单字符
|
|
```
|
|
|
|
### 3. 权限设计
|
|
|
|
```typescript
|
|
// 明确的权限配置
|
|
roles: ['admin'] // ✅ 单角色
|
|
roles: ['admin', 'manager'] // ✅ 多角色
|
|
requiresAuth: true // ✅ 明确需要认证
|
|
```
|
|
|
|
## 📚 相关文档
|
|
|
|
- [登录鉴权文档](./登录鉴权系统文档)
|
|
- [权限系统文档](./权限管理系统文档)
|
|
- [整体架构文档](./整体架构文档)
|