383 lines
14 KiB
Markdown
383 lines
14 KiB
Markdown
|
# Platform 路由集成指南
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
### TL;DR
|
|||
|
|
|
|||
|
|
1. **shared 提供**：路由生成工具、菜单处理、设备检测
|
|||
|
|
2. **platform 定义**：布局组件映射、视图加载器
|
|||
|
|
3. **platform 生成**：调用 `generateRoutes()` 生成自己的路由
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// 1. 导入工具
|
|||
|
|
import { generateRoutes, type RouteGeneratorConfig } from 'shared/utils/route'
|
|||
|
|
import type { SysMenu } from 'shared/types'
|
|||
|
|
|
|||
|
|
// 2. 配置生成器
|
|||
|
|
const config: RouteGeneratorConfig = {
|
|||
|
|
layoutMap: { /* 布局映射 */ },
|
|||
|
|
viewLoader: (path) => { /* 组件加载 */ }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 3. 生成路由
|
|||
|
|
const routes = generateRoutes(menus, config)
|
|||
|
|
|
|||
|
|
// 4. 添加到路由
|
|||
|
|
routes.forEach(route => router.addRoute(route))
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 架构说明
|
|||
|
|
|
|||
|
|
Platform 使用 shared 提供的路由生成工具来动态生成路由。架构如下：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────┐
|
|||
|
|
│ shared │
|
|||
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ utils/route/route-generator.ts │ │
|
|||
|
|
│ │ - generateRoutes() 路由生成 │ │
|
|||
|
|
│ │ - buildMenuTree() 菜单树构建 │ │
|
|||
|
|
│ │ - filterMenusByPermissions() 权限过滤 │ │
|
|||
|
|
│ │ - findMenuByPath() 路径查找 │ │
|
|||
|
|
│ │ - getMenuPath() 面包屑路径 │ │
|
|||
|
|
│ │ - getFirstAccessibleMenuUrl() 首页跳转 │ │
|
|||
|
|
│ └───────────────────────────────────────────────────────┘ │
|
|||
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ utils/device.ts │ │
|
|||
|
|
│ │ - getDeviceType() 设备类型检测 │ │
|
|||
|
|
│ │ - isMobile() 移动端判断 │ │
|
|||
|
|
│ │ - useDevice() 响应式 Hook │ │
|
|||
|
|
│ └───────────────────────────────────────────────────────┘ │
|
|||
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ types/sys/menu.ts & types/enums.ts │ │
|
|||
|
|
│ │ - SysMenu 菜单接口 │ │
|
|||
|
|
│ │ - MenuType 菜单类型枚举 │ │
|
|||
|
|
│ └───────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────┘
|
|||
|
|
↓
|
|||
|
|
┌─────────────────────────────────────┐
|
|||
|
|
│ Module Federation (远程模块) │
|
|||
|
|
│ - shared/utils/route │
|
|||
|
|
│ - shared/utils/device │
|
|||
|
|
│ - shared/types │
|
|||
|
|
└─────────────────────────────────────┘
|
|||
|
|
↓
|
|||
|
|
┌─────────────────────────────────────────────────────────────┐
|
|||
|
|
│ platform │
|
|||
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ src/router/index.ts │ │
|
|||
|
|
│ │ 1. 定义布局组件映射 (platformLayoutMap) │ │
|
|||
|
|
│ │ 2. 定义视图组件加载器 (viewLoader) │ │
|
|||
|
|
│ │ 3. 调用 generateRoutes() 生成动态路由 │ │
|
|||
|
|
│ │ 4. 添加到 Vue Router │ │
|
|||
|
|
│ └───────────────────────────────────────────────────────┘ │
|
|||
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ src/layouts/ │ │
|
|||
|
|
│ │ - SidebarLayout.vue 侧边栏布局 │ │
|
|||
|
|
│ │ - NavigationLayout.vue 导航布局（如需） │ │
|
|||
|
|
│ │ - BasicLayout.vue 基础布局（如需） │ │
|
|||
|
|
│ └───────────────────────────────────────────────────────┘ │
|
|||
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ src/views/ │ │
|
|||
|
|
│ │ - 各种页面组件 │ │
|
|||
|
|
│ └───────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 使用步骤
|
|||
|
|
|
|||
|
|
### 1. 在 router/index.ts 中配置路由生成器
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router'
|
|||
|
|
import { generateRoutes, type RouteGeneratorConfig } from 'shared/utils/route'
|
|||
|
|
import type { SysMenu } from 'shared/types'
|
|||
|
|
import { SidebarLayout } from '../layouts'
|
|||
|
|
|
|||
|
|
// 1. 定义布局组件映射
|
|||
|
|
const platformLayoutMap: Record<string, () => Promise<any>> = {
|
|||
|
|
'SidebarLayout': () => Promise.resolve({ default: SidebarLayout }),
|
|||
|
|
'NavigationLayout': () => Promise.resolve({ default: SidebarLayout }), // 可复用或自定义
|
|||
|
|
'BasicLayout': () => Promise.resolve({ default: SidebarLayout }),
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 2. 定义视图组件加载器
|
|||
|
|
const VIEW_MODULES = import.meta.glob('../views/**/*.vue')
|
|||
|
|
|
|||
|
|
function viewLoader(componentPath: string): (() => Promise<any>) | null {
|
|||
|
|
// 将后台路径转换为实际路径
|
|||
|
|
let path = componentPath
|
|||
|
|
if (!path.startsWith('../')) {
|
|||
|
|
if (!path.startsWith('/')) {
|
|||
|
|
path = '/' + path
|
|||
|
|
}
|
|||
|
|
path = '../views' + path
|
|||
|
|
}
|
|||
|
|
if (!path.endsWith('.vue')) {
|
|||
|
|
path += '.vue'
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const loader = VIEW_MODULES[path]
|
|||
|
|
return loader ? (loader as () => Promise<any>) : null
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 3. 创建路由生成器配置
|
|||
|
|
const routeConfig: RouteGeneratorConfig = {
|
|||
|
|
layoutMap: platformLayoutMap,
|
|||
|
|
viewLoader,
|
|||
|
|
staticRoutes: routes, // 可选：静态路由
|
|||
|
|
notFoundComponent: () => import('../views/public/404.vue') // 可选
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 4. 动态添加路由的函数
|
|||
|
|
export function addDynamicRoutes(menus: SysMenu[]) {
|
|||
|
|
const dynamicRoutes = generateRoutes(menus, routeConfig)
|
|||
|
|
|
|||
|
|
dynamicRoutes.forEach(route => {
|
|||
|
|
router.addRoute(route)
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
console.log('✅ 动态路由已添加', dynamicRoutes.length, '个')
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 在应用初始化时调用
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// main.ts 或登录成功后
|
|||
|
|
import { addDynamicRoutes } from './router'
|
|||
|
|
import { menuAPI } from 'shared/api'
|
|||
|
|
|
|||
|
|
// 获取用户菜单
|
|||
|
|
const response = await menuAPI.getUserMenus()
|
|||
|
|
if (response.success && response.data) {
|
|||
|
|
// 添加动态路由
|
|||
|
|
addDynamicRoutes(response.data)
|
|||
|
|
|
|||
|
|
// 跳转到首页或指定页面
|
|||
|
|
router.push('/home')
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 菜单数据格式
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
interface SysMenu {
|
|||
|
|
menuID: string // 菜单ID，作为路由 name
|
|||
|
|
parentID?: string // 父菜单ID，'0' 表示根菜单
|
|||
|
|
name: string // 菜单名称
|
|||
|
|
url?: string // 路由路径，如 '/user/profile'
|
|||
|
|
type: MenuType // 菜单类型
|
|||
|
|
icon?: string // 图标
|
|||
|
|
component?: string // 组件路径，如 'user/profile/ProfileView'
|
|||
|
|
layout?: string // 布局名称，如 'SidebarLayout'
|
|||
|
|
orderNum?: number // 排序号
|
|||
|
|
permission?: string // 权限标识
|
|||
|
|
hidden?: boolean // 是否隐藏
|
|||
|
|
children?: SysMenu[] // 子菜单
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
enum MenuType {
|
|||
|
|
NAVIGATION = 'navigation', // 导航菜单（顶部导航）
|
|||
|
|
SIDEBAR = 'sidebar', // 侧边栏菜单
|
|||
|
|
MENU = 'menu', // 普通菜单
|
|||
|
|
PAGE = 'page', // 页面（独立路由）
|
|||
|
|
BUTTON = 'button' // 按钮（不生成路由）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 示例菜单数据
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
const menus: SysMenu[] = [
|
|||
|
|
{
|
|||
|
|
menuID: 'user-center',
|
|||
|
|
parentID: '0',
|
|||
|
|
name: '用户中心',
|
|||
|
|
url: '/user',
|
|||
|
|
type: MenuType.NAVIGATION,
|
|||
|
|
icon: 'User',
|
|||
|
|
layout: 'SidebarLayout',
|
|||
|
|
orderNum: 1,
|
|||
|
|
children: [
|
|||
|
|
{
|
|||
|
|
menuID: 'user-profile',
|
|||
|
|
parentID: 'user-center',
|
|||
|
|
name: '个人信息',
|
|||
|
|
url: '/user/profile',
|
|||
|
|
type: MenuType.MENU,
|
|||
|
|
component: 'user/profile/ProfileView',
|
|||
|
|
orderNum: 1
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
menuID: 'user-settings',
|
|||
|
|
parentID: 'user-center',
|
|||
|
|
name: '账号设置',
|
|||
|
|
url: '/user/settings',
|
|||
|
|
type: MenuType.MENU,
|
|||
|
|
component: 'user/settings/SettingsView',
|
|||
|
|
orderNum: 2
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 布局组件要求
|
|||
|
|
|
|||
|
|
布局组件必须包含 `<router-view />` 用于渲染子路由：
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<div class="sidebar-layout">
|
|||
|
|
<aside class="sidebar">
|
|||
|
|
<!-- 侧边栏内容 -->
|
|||
|
|
</aside>
|
|||
|
|
<main class="content">
|
|||
|
|
<router-view /> <!-- 重要！用于渲染页面组件 -->
|
|||
|
|
</main>
|
|||
|
|
</div>
|
|||
|
|
</template>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 响应式布局（可选）
|
|||
|
|
|
|||
|
|
如果需要移动端适配，可以使用 shared 的设备检测工具：
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
import { getDeviceType, DeviceType } from 'shared/utils/device'
|
|||
|
|
|
|||
|
|
const deviceType = getDeviceType()
|
|||
|
|
if (deviceType === DeviceType.MOBILE) {
|
|||
|
|
// 移动端逻辑
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 工具方法说明
|
|||
|
|
|
|||
|
|
所有工具方法从 `shared/utils/route` 导入：
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
import {
|
|||
|
|
generateRoutes,
|
|||
|
|
buildMenuTree,
|
|||
|
|
filterMenusByPermissions,
|
|||
|
|
findMenuByPath,
|
|||
|
|
getMenuPath,
|
|||
|
|
getFirstAccessibleMenuUrl,
|
|||
|
|
type RouteGeneratorConfig
|
|||
|
|
} from 'shared/utils/route'
|
|||
|
|
|
|||
|
|
import type { SysMenu, MenuType } from 'shared/types'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### generateRoutes(menus, config)
|
|||
|
|
根据菜单生成路由配置数组
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `menus: SysMenu[]` - 菜单列表
|
|||
|
|
- `config: RouteGeneratorConfig` - 路由生成器配置
|
|||
|
|
|
|||
|
|
**返回：** `RouteRecordRaw[]`
|
|||
|
|
|
|||
|
|
### buildMenuTree(menus, staticRoutes?)
|
|||
|
|
将扁平菜单列表转换为树形结构
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `menus: SysMenu[]` - 菜单列表
|
|||
|
|
- `staticRoutes?: RouteRecordRaw[]` - 静态路由（可选）
|
|||
|
|
|
|||
|
|
**返回：** `SysMenu[]`
|
|||
|
|
|
|||
|
|
### filterMenusByPermissions(menus, permissions)
|
|||
|
|
根据权限过滤菜单
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `menus: SysMenu[]` - 菜单列表
|
|||
|
|
- `permissions: string[]` - 权限列表
|
|||
|
|
|
|||
|
|
**返回：** `SysMenu[]`
|
|||
|
|
|
|||
|
|
### findMenuByPath(menus, path)
|
|||
|
|
根据路径查找菜单项
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `menus: SysMenu[]` - 菜单列表
|
|||
|
|
- `path: string` - 路由路径
|
|||
|
|
|
|||
|
|
**返回：** `SysMenu | null`
|
|||
|
|
|
|||
|
|
### getMenuPath(menus, targetMenuId)
|
|||
|
|
获取菜单路径数组（用于面包屑导航）
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `menus: SysMenu[]` - 菜单列表
|
|||
|
|
- `targetMenuId: string` - 目标菜单ID
|
|||
|
|
|
|||
|
|
**返回：** `SysMenu[]`
|
|||
|
|
|
|||
|
|
### getFirstAccessibleMenuUrl(menus)
|
|||
|
|
获取第一个可访问的菜单URL（用于登录后跳转）
|
|||
|
|
|
|||
|
|
**参数：**
|
|||
|
|
- `menus: SysMenu[]` - 菜单列表
|
|||
|
|
|
|||
|
|
**返回：** `string | null`
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. **shared 服务必须先启动**：因为使用 Module Federation，platform 依赖 shared 的远程模块
|
|||
|
|
2. **布局组件必须包含 router-view**：否则子路由无法渲染
|
|||
|
|
3. **组件路径映射**：确保 `viewLoader` 能正确加载组件
|
|||
|
|
4. **静态路由优先**：如果菜单标记为 `__STATIC_ROUTE__`，不会重复生成路由
|
|||
|
|
5. **路由守卫**：记得在 `router.beforeEach` 中添加权限检查
|
|||
|
|
|
|||
|
|
## 调试技巧
|
|||
|
|
|
|||
|
|
1. **查看生成的路由**：
|
|||
|
|
```typescript
|
|||
|
|
console.log('所有路由:', router.getRoutes())
|
|||
|
|
console.log('路由数量:', router.getRoutes().length)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
2. **查看菜单树结构**：
|
|||
|
|
```typescript
|
|||
|
|
import { buildMenuTree } from 'shared/utils/route'
|
|||
|
|
|
|||
|
|
const tree = buildMenuTree(menus)
|
|||
|
|
console.log('菜单树:', JSON.stringify(tree, null, 2))
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
3. **查看当前路由信息**：
|
|||
|
|
```typescript
|
|||
|
|
console.log('当前路由:', router.currentRoute.value)
|
|||
|
|
console.log('路由路径:', router.currentRoute.value.path)
|
|||
|
|
console.log('路由参数:', router.currentRoute.value.params)
|
|||
|
|
console.log('路由元数据:', router.currentRoute.value.meta)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
4. **测试菜单查找**：
|
|||
|
|
```typescript
|
|||
|
|
import { findMenuByPath, getMenuPath } from 'shared/utils/route'
|
|||
|
|
|
|||
|
|
// 根据路径查找菜单
|
|||
|
|
const menu = findMenuByPath(menus, '/user/profile')
|
|||
|
|
console.log('找到的菜单:', menu)
|
|||
|
|
|
|||
|
|
// 获取面包屑路径
|
|||
|
|
const breadcrumb = getMenuPath(menus, 'user-profile')
|
|||
|
|
console.log('面包屑:', breadcrumb.map(m => m.name).join(' > '))
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
5. **检查视图组件加载**：
|
|||
|
|
```typescript
|
|||
|
|
// 在 viewLoader 中添加日志
|
|||
|
|
function viewLoader(componentPath: string) {
|
|||
|
|
console.log('尝试加载组件:', componentPath)
|
|||
|
|
const path = /* 转换逻辑 */
|
|||
|
|
const loader = VIEW_MODULES[path]
|
|||
|
|
console.log('找到的加载器:', loader ? '✅' : '❌')
|
|||
|
|
return loader ? (loader as () => Promise<any>) : null
|
|||
|
|
}
|
|||
|
|
```
|