后台权限系统架构设计与Vue3/React双框架落地实践

吃透后台权限系统：从架构设计到 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表层调用，真正去掌握通用的工程化架构思维，这，才是前端进阶的核心方向。