做中后台系统,权限管理永远是绕不开的话题。但很多人对权限的理解停留在 "某个按钮能不能点" 这个层面,实际上权限是一条完整的链路 ------ 从登录态、菜单树、页面路由、按钮权限到角色授权,环环相扣。
最近在做途友(Tuyou)后台管理系统的权限模块,最终落地了一套 "菜单驱动路由、权限键驱动操作、角色配置反向生成用户可见能力" 的方案。这篇文章结合项目实现,聊聊这套动态路由和动态权限配置的设计思路、工程取舍,以及踩过的坑。
一、为什么不能用静态路由 + 页面内 if 判断
如果路由按静态方式写死,页面里用 v-if / 条件渲染控制按钮显示,短期看确实开发快,逻辑简单,但随着页面越来越多,会逐渐暴露三个问题:
第一,路由表和菜单表割裂。 前端维护一份路由,后端维护一份菜单,两边各改各的,迟早配不齐。菜单有但路由没注册,或者路由有但菜单没配,都是常见问题。
第二,首页、菜单、面包屑来源不一致。 首页写死一个 redirect,菜单从接口拉,面包屑读静态路由配置。三个数据源各走各的,维护成本随着页面数量线性增长。
第三,角色菜单变更后,前端很难在运行时同步刷新。 管理员改了角色配置,当前登录用户不退出重登的话,权限就是旧的。
所以最终我们采用:后端返回菜单树,前端在运行时重建路由。
二、整体架构:一条闭环的权限链路
先给全貌。当前权限系统的数据流转是这样的:
bash
登录 → getMe() 获取当前用户信息
↓
menu_tree + perm_keys
↙ ↘
运行时路由重建 权限判断函数
↓ ↓
菜单/首页/面包屑 页面级/按钮级控制
最核心的两个数据:
menu_tree:决定用户 "能看到哪些页面、菜单和导航结构"perm_keys:决定用户 "在页面里能执行哪些动作"
这两个数据都收敛在一次 getMe() 调用里返回,后续所有权限能力都以它为源头。
这里有个设计原则我觉得很重要:权限原始数据尽量单点收敛。不要让菜单、角色、按钮权限分别从多个接口零散拉取再拼装,对前端来说,最好有一个 "当前用户可访问能力快照" 接口,作为运行时权限的唯一源头。
三、核心实现一:运行时重建路由
项目的静态路由配置非常薄,只保留了登录页、403、404 和布局壳,业务页面一个都没在 config/routes.ts 里铺开。
为什么?因为前端不再预先声明 "所有用户可能访问的业务路由",而是只在用户信息到手后,动态生成该用户真正可访问的路由集合。
在 Umi 框架里,这依赖两个运行时 API:
getInitialState():应用启动时拉取当前用户信息patchRoutes():根据当前用户菜单树,重建 Umi 的运行时路由
typescript
// app.tsx 简化版
export async function getInitialState(): Promise<CurrentInfo> {
const token = localStorage.getItem('token');
if (!token) return {} as CurrentInfo;
const userInfo = await getMe();
return userInfo; // 包含 menu_tree 和 perm_keys
}
export function patchRoutes({ routes }) {
const user = getCurrentUserFromCache();
if (!user?.menu_tree) return;
const appRoutes = buildAppRoutes(user.menu_tree);
// 把生成的业务路由挂到布局路由的 children 下
const layoutRoute = routes.find(r => r.path === '/');
if (layoutRoute) {
layoutRoute.routes = [...appRoutes, ...layoutRoute.routes];
}
}
这意味着项目并不是 "先有完整业务路由,再靠权限拦截做裁剪",而是从源头上只生成当前用户有资格访问的路由。
直接收益很明显:
- 侧边菜单和可访问页面天然一致,不会出现 "菜单能点但页面 404"
- 首页重定向可以自动指向用户第一个可访问页面
- 403 更聚焦于越权访问,而不是给所有未配置页面兜底
四、核心实现二:菜单树如何转成路由树
真正负责把菜单树转换成路由结构的是 route.ts 里的 transformMenu() 和 buildAppRoutes()。这里有几个设计点值得展开说。
1. 菜单树和路由树同源
transformMenu() 递归遍历后端返回的菜单树,转成前端可消费的路由结构。转换时保留关键字段映射:
typescript
// 菜单字段 → 路由字段
menu_name → name // 菜单名称
route_path → path // 路由路径
icon → icon // 图标
hide_in_menu → hideInMenu // 是否隐藏
component → 页面组件标识 // 关键!
这样设计后,菜单不只是 "显示层数据",而是整个运行时导航结构的源数据。菜单改了,路由、面包屑、首页全部跟着变。
2. 目录节点自动补重定向
如果一个菜单节点本身不是页面,而是目录(没有 component 字段),transformMenu() 会自动给这个目录路径补一个 redirect,让它跳到第一个可访问子页面。
这个细节看起来小,但直接解决了两个经典问题:
- 点击目录型菜单后地址存在,但页面空白
- 首页或父级菜单不知道该跳到哪个子页面
3. 首页自动取 "第一个可访问页面"
buildAppRoutes() 会通过 firstPath(menuTree) 计算当前用户的首页地址,如果没有任何可访问业务页,就退化到 /403。
这比写死首页路径稳得多,因为不同角色的首页不一定相同。管理员可能第一个页面是数据看板,普通运营可能第一个页面是订单列表。
4. 路径统一做归一化
专门写了个 normalizePath(),用于移除非根路径末尾斜杠:
typescript
function normalizePath(path: string): string {
if (path === '/') return '/';
return path.endsWith('/') ? path.slice(0, -1) : path;
}
这个处理对动态路由非常关键。菜单命中、面包屑匹配、登录跳转、首页重定向都依赖路径比较。如果不先归一化,/user/list 和 /user/list/ 很容易被系统当成两个地址,最后出现 "权限正常但导航状态异常" 的诡异问题。
五、核心实现三:动态路由的安全收口
很多团队第一次做动态路由时,会把后端返回的 component 直接当成可执行路径去加载页面。这种做法灵活,但风险很高,尤其容易演化成不可控的 "字符串驱动前端"。
我们这里做了一个很重要的安全收口:页面组件必须经过 pageMap 白名单映射。
typescript
const pageMap: Record<string, React.ComponentType> = {
'dashboard/analysis': Analysis,
'user/list': UserList,
'authority/menu': MenuPage,
'authority/role': RolePage,
// ... 更多页面
};
也就是说:
- 后端可以返回组件标识(比如
'user/list') - 前端只认白名单中已注册的组件
- 某些组件还可以进一步限制允许绑定的路径
对应的校验函数 isValidPage() 会做多层检查:
- 有
component字段 - 路径不是保留地址(如
/login、/403) component在pageMap中存在- 如果该页面声明了允许路径,则
route_path必须命中
这个设计本质上是在动态和可控之间做平衡:动态性来自后端菜单配置,可控性来自前端白名单约束。
这也是我认为这套方案里最值得保留的点之一。动态路由如果没有白名单收口,排障和安全都会失控 ------ 你永远不知道后端传了个什么奇怪的组件字符串过来。
六、核心实现四:perm_keys 驱动按钮级权限
如果说 menu_tree 解决的是 "能不能看到页面",那 perm_keys 解决的就是 "进了页面之后能做什么"。
项目把按钮级权限收敛在 access.ts 里,逻辑非常轻:
typescript
// access.ts
export default function access(initialState: { perm_keys?: string[] }) {
const permSet = new Set(initialState?.perm_keys || []);
return {
hasPerm: (permKey: string) => permSet.has(permKey),
};
}
页面里直接用:
typescript
// 菜单管理页示例
const { hasPerm } = useAccess();
return (
<div>
{hasPerm('menu:create') && <Button>新增菜单</Button>}
<Table
columns={[
// ...
{
title: '操作',
render: (_, record) => (
<>
{hasPerm('menu:edit') && <a>编辑</a>}
{hasPerm('menu:delete') && <a>删除</a>}
</>
),
},
]}
/>
</div>
);
这套设计的优点是简单而稳定:
- 页面不需要自己解析权限树
- 页面不需要关心角色和菜单的映射细节
- 权限判断语义直接落在
hasPerm('xxx')
另一个原则:页面层只消费结论,不解析原始权限结构。页面开发只应该知道 "我有没有这个权限",不应该反复参与解析角色树、菜单树和权限树。这种解析必须收敛到统一入口。
七、核心实现五:菜单、首页、面包屑保持同源
权限系统容易做散的一个地方,是导航相关能力经常来自不同数据源:
- 菜单来自菜单接口
- 面包屑来自静态路由配置
- 首页来自写死的 redirect
一旦三者不同源,就会出现 "菜单能点,面包屑不对"" 页面能进,但首页跳错 " 的问题。
我们的处理方式比较统一:
- 路由来自
menu_tree - 首页来自
firstPath(menuTree) - 面包屑来自
buildMenuMeta(menuTree)
顶部面包屑不是直接依赖静态路由,而是先根据当前用户的 menu_tree 生成一份菜单元信息,再和当前路径做匹配。
这意味着:
- 用户能访问的页面,面包屑才可能出现
- 菜单变了,面包屑跟着变
- 页面层不需要单独维护导航文案
这是一个很典型的**"同源建模优于多处同步"**的实践。一份数据源派生多个能力,比多份配置各自维护要稳得多。
八、动态权限配置如何反向作用到运行时路由
只做运行时动态路由还不够,真正完整的权限管理还需要 "配置入口"。项目里这个入口主要落在角色管理和菜单管理两个页面。
角色授权:菜单权限 + 接口权限分离
角色授权弹窗会并行拉取两类数据:
menu_tree:角色拥有的菜单树permission_tree:角色拥有的接口 / 按钮权限树
界面上拆成两个 Tab:菜单权限、接口按钮权限。
最终保存时,前端提交的是非常干净的两个数组:
menu_idsperm_ids
这个建模非常实用,因为它把 "角色拥有什么能力" 的配置维度拆清楚了:
- 菜单能力决定路由和导航可见范围
- 权限键决定页面内操作可执行范围
两者不是二选一,而是互补关系。
菜单管理:运行时路由的源数据编辑器
菜单管理页的价值不只是 CRUD 菜单项,它实际上是在维护运行时路由的源数据。
每次查询菜单列表时,会并行再调用一次 getMe()。原因很直接:如果当前登录用户的菜单树因为某次菜单调整发生了变化,就要把本地缓存和 initialState 同步更新,并在必要时触发整页刷新。
判断逻辑很朴素:
- 旧
menu_tree和新menu_tree做字符串比较 - 一旦变化,刷新页面
同样的逻辑也出现在 getInitialState 中:如果最新菜单树和缓存不一致,会直接跳回 /,让应用按新菜单重新完成一轮路由构建。
这就是这套系统能 "动态" 起来的关键闭环:
bash
角色/菜单配置变更
↓
getMe() 返回新菜单树
↓
前端检测到菜单结构变化
↓
触发刷新或重定向
↓
重新生成当前用户路由
九、几个关键取舍
任何权限系统都不只是实现问题,更是取舍问题。
取舍一:页面权限和按钮权限分层,而不是混在一起
如果把所有权限都压成一组 perm_keys,短期很方便,但会让菜单、路由和操作权限混在一个维度里,后续很难解释 "为什么能进页面但不能操作"。
现在的拆法更清晰:
menu_tree负责页面结构perm_keys负责操作能力
这是很适合后台系统的建模方式。
取舍二:使用运行时重建,而不是纯前端静态守卫
静态路由 + 页面内判断也能做权限,但会让 "不可访问页面" 仍然存在于前端路由里。运行时重建直接把不可访问页面从路由层移掉了,导航体验更干净。
代价是实现复杂度更高,需要处理缓存同步、刷新机制等问题。
取舍三:使用白名单映射,而不是直接动态 import 字符串
这一步不是可有可无,而是动态路由落地时必须有的收口。否则后续菜单配置一旦失控,前端将很难排查到底是配置问题还是组件装载问题。
代价是新页面接入时需要同步补白名单,多了一步手动操作。但和安全可控比起来,这个成本完全可以接受。
十、踩过的坑和注意点
1. 菜单配置错误会直接影响路由可达性
动态路由的灵活性,本质上也是对配置正确性的放大。只要 route_path、component、父子层级关系配置错了,就可能出现:
- 菜单有,但页面进不去
- 页面组件存在,但不会被注册成路由
- 父级菜单能展开,但点进去跳不到正确页面
这也是为什么 isValidPage() 里要对保留路径、组件白名单、路径限制做多层校验。
2. 路由重建依赖本地缓存用户信息
patchRoutes() 读取的是本地缓存的用户信息,而不是实时接口结果。这意味着:
- 缓存必须和服务端
getMe()结果保持同步 - 菜单变化后必须触发刷新或重定向
否则新权限不会及时进入运行时路由系统。
3. 图标和组件映射都有前端维护成本
iconMap 和 pageMap 都是有限集合。优点是安全可控,缺点是:
- 新页面接入时需要同步补白名单
- 后端传入未支持图标时只会无图标显示
这类问题不严重,但需要团队有明确约定。
4. 菜单变更后的刷新体验还可以优化
现在项目在菜单变更后采用的是 window.location.reload() 或 window.location.replace('/')。它能保证一致性,但体验上仍偏直接。
后续如果框架层支持更平滑的运行时路由更新,可以继续优化成无整页刷新的重建方式。不过在当前阶段,这种实现虽然朴素,但稳定性优先,是可以接受的工程取舍。
十一、后续可优化方向
如果后面继续演进,这套权限系统还可以往下做三件事:
第一,补齐菜单配置校验能力。 可以在菜单管理页增加更强的前端校验 ------ 组件标识是否合法、路径是否重复、目录节点和页面节点的字段组合是否合法。把很多动态路由问题提前拦在配置阶段。
第二,抽象 "权限刷新" 机制。 目前菜单变化后的刷新逻辑分别散落在初始化和菜单管理页中,可以统一抽成一个权限刷新流程,减少重复判断与页面级侵入。
第三,补一份可视化权限时序图。 这套实现已经具备很强的可读性,如果再配一张 "登录 → getMe → patchRoutes → 菜单生成 → hasPerm 判断 → 角色授权回写" 的时序图,新成员理解成本会更低。
结语
这次权限管理的实现,本质上不是单纯把 "动态路由" 做出来,而是把 "谁能看到什么、谁能操作什么、配置变化后如何回流到运行时" 这件事做成了一条闭环。
最终的方案可以概括成一句话:
用
menu_tree管页面结构,用perm_keys管操作能力,用运行时路由重建把权限结果真正落到页面访问层。
从工程角度看,这套设计最有价值的地方,不是它有多复杂,而是它把权限能力拆得足够清楚,同时又让菜单、路由、首页和按钮权限保持了一致的数据来源。