吃透后台权限系统：从架构设计到 Vue3/React 双框架完整落地
前言
权限管理模块，堪称企业级中后台系统的核心基础设施，也是前端工程化进阶之路上一块必须啃下的硬骨头。市面上关于权限的教程虽然不少，但大多存在两个明显痛点：要么只停留在表层API调用层面，缺乏顶层架构设计思维；要么Vue和React两套方案完全割裂，学完一套另一套还得从头摸索，白白耗费精力。
从工程化的视角来看，需要明确一个关键认知：权限的本质与UI框架无关。无论是Vue3还是React，权限的数据模型、鉴权逻辑、执行链路，本质上都是一致的。本文将从企业级项目标准出发，拆解出一套通用权限架构。同时，会具体给出Vue3 + React双框架下的生产级落地代码，全面覆盖路由、菜单、页面、按钮四级权限，并且适配前端静态和后端动态两种模式。目标是帮助开发者搭建一个标准化、可复用的权限体系，而不是那种写完一个项目就废弃的方案。
一、权限架构整体设计（全框架通用）
1.1 设计原则
这套权限架构，主要围绕三个核心原则来构建，能够适配大中小各类规模的中后台项目：
- 解耦性：权限内核与UI层彻底解耦。鉴权规则、数据存储、状态管理等底层逻辑全部抽象出来，与界面展示完全分离。
- 分层性：覆盖路由、菜单、页面、按钮四个层级，实现全方位的访问控制，颗粒度足够精细。
- 双模式：同时支持前端静态路由和后端动态路由，可通过配置一键切换，满足不同项目的灵活性需求。
1.2 两种权限运行模式
1）前端权限模式（frontend）
这种模式下，路由是静态定义在前端的。用户登录后，系统会根据用户的角色和权限码来过滤路由表。优点是开发简单、部署方便；比较适合那些权限规则相对固定的中小型项目。
2）后端权限模式（backend）
在这种模式下，基础路由依然由前端维护，但业务路由会存放在后端数据库里。用户登录后，前端会动态拉取属于当前用户的专属路由树，然后自动注册到系统中。优点是权限可以动态配置，无需因为修改权限而重启服务；非常适合SaaS、多租户这类复杂的大型项目。
1.3 双维度鉴权模型
行业里比较成熟的生产级方案是采用角色码 + 权限码双池分离的设计。粗粒度和细粒度互补，各自的职责完全隔离，互不干扰。
| 鉴权维度 | 数据来源 | 存储仓库 | 匹配规则 | 使用场景 |
|---|---|---|---|---|
| 角色码 | 用户信息接口 | 用户仓库 | 精确匹配 | 粗粒度身份管控（管理员/租户） |
| 权限码 | 权限列表接口 | 权限仓库 | 前缀匹配 | 细粒度操作管控（按钮/接口） |
此外，系统内置了一个超级管理员标识 *:*:*，持有这个角色的用户，所有鉴权校验都会自动放行，属于一个兜底设计。
1.4 四层权限覆盖
- 路由级：通过路由配置里的
meta.authority来过滤非法的访问路由； - 菜单级：与路由过滤逻辑同步，没有权限的路由，侧边菜单里也不会渲染出来；
- 页面级：通过Hook来判断权限，控制页面里的模块是否显示或隐藏；
- 按钮级：支持组件、指令、函数三种写法，专门管控那些操作类按钮的显隐。
1.5 统一数据存储结构
采用双仓库分离存储的策略。Vue这边基于Pinia，React那边用Zustand，但数据结构是完全对齐的。
用户仓库（UserStore）
interface UserState {
userInfo: BasicUserInfo | null;
userRoles: string[]; // 用户角色码集合
}
权限仓库（AccessStore）
interface AccessState {
accessCodes: string[]; // 权限码集合
accessMenus: MenuRecordRaw[];
accessRoutes: RouteRecordRaw[];
accessToken: string | null;
isAccessChecked: boolean; // 权限初始化状态
}
1.6 权限完整执行链路
整个流程大致是这样的：用户登录后，先持久化Token；然后路由守卫开始初始化，接着获取用户的角色和权限码，写入全局Store；之后根据当前的权限模式，生成当前用户可访问的路由表；最后渲染出对应的菜单和页面，再深入到组件层进行更细粒度的鉴权。
二、通用强制规范
2.1 权限码命名
为了避免命名混乱，统一采用三段式标准：模块:资源:操作。这种命名方式清晰易懂，可维护性也高。
2.2 路由豁免
像登录页、404页面这种公共页面，需要在路由配置里加上 meta.ignoreAccess: true 来豁免权限检查。这个配置与 authority 是互斥的，用了豁免就不能再配置权限。
{ path: "/login", meta: { ignoreAccess: true } }
2.3 权限模式切换
updatePreferences({ app: { accessMode: "frontend" | "backend" } });
三、Vue3 生产级落地
3.1 目录结构
3.2 路由权限配置
{
path: "/permission",
meta: { authority: ["sys:platform_admin", "sys:tenant_manager"] },
children: [{
path: "codes",
meta: { authority: ["sys:platform_admin"] }
}]
}
3.3 按钮鉴权三种方案
1）权限组件
新增 2）权限指令（推荐）
新增
3）编程式Hook
const { hasAccess, hasAccessByCodes } = useAccess();
const canCreate = hasAccess(['sys:user:create']);
3.4 Pro组件适配
内置的Pro工具栏、单元格组件，原生支持 auth 权限字段，可以直接在配置里声明。
toolbar: [{ name: "add", text: "新增", auth: "sys:user:create" }]
四、React 生产级落地
4.1 目录结构
4.2 路由权限配置
React这边的配置规则跟Vue完全一致，没什么两样。
{
path: "permission",
meta: { authority: ["sys:platform_admin"] }
}
4.3 按钮鉴权三种方案
1）Hook + 条件渲染（推荐）
const { hasAccessByCodes } = useAccess();
{hasAccessByCodes(['sys:user:create']) && <Button>新增Button>}
2）AccessControl 组件
<AccessControl codes={['sys:user:delete']} fallback=<span>无权限span>><Button>删除Button>AccessControl>
3）静态函数（非组件）
import { getAccessStatic } from '@/core/access';
if(getAccessStatic().hasAccessByCodes(['sys:user:create'])){}
五、工程化最佳实践
- 路由方面：业务路由配置
authority，公共页面统一开启ignoreAccess。 - 按钮方面：权限标识严格遵循三段式命名规范，禁止在业务代码里硬编码权限。
- 逻辑方面：内置API默认走“或”逻辑，如果需要多权限同时校验，需要手动叠加判断。
- 安全方面：前端只负责管控UI展示，所有接口必须由后端二次鉴权，这是铁律。
六、常见问题FAQ
- 权限调试：直接打印UserStore和AccessStore，看看
userRoles和accessCodes的值对不对。 - 权限刷新：调用
useAuth().getUserPermissionCodes()重新拉取一下权限。 - 刷新丢失：权限不做持久化属于安全设计，路由守卫会自动重新初始化，不用太担心。
- 安全边界：再次强调，前端权限永远无法替代后端校验，它的核心作用只是优化用户交互体验。
七、写在最后
中后台通用模块的底层架构，实际上具有框架无关性。像权限、字典、表单这些能力，完全可以做到一套内核，在Vue和React两端分别落地。跳出那些简单的API表层调用，真正去掌握通用的工程化架构思维，这，才是前端进阶的核心方向。
