角色权限管理

引用文件

本文引用的文件

简介

本文件系统化梳理 Yudao Cloud 的角色权限管理体系，覆盖角色管理、权限分配、菜单授权、数据权限等核心能力。文档从数据模型、RBAC 控制机制、API 接口到缓存与继承策略进行全面阐述，并提供最佳实践与排障建议，帮助开发者与运维人员高效落地与维护权限系统。

项目结构

围绕“角色权限”主题，系统采用模块化分层组织：

控制层：提供 REST API，如角色管理、菜单管理、权限分配等
服务层：封装业务逻辑，如角色服务、权限服务、菜单服务
数据访问层：MyBatis Mapper 与 Redis 缓存
枚举与 VO：统一权限常量、请求/响应对象
文档与脚本：权限说明文档与数据库初始化脚本

Mermaid Diagram Code:

graph TB
subgraph "控制层"
RC["RoleController<br/>角色控制器"]
MC["MenuController<br/>菜单控制器"]
end
subgraph "服务层"
RS["RoleService<br/>角色服务"]
PS["PermissionService<br/>权限服务"]
MS["MenuService<br/>菜单服务"]
end
subgraph "数据访问层"
RM["RoleMapper<br/>角色映射"]
MM["MenuMapper<br/>菜单映射"]
RCM["RoleMenuMapper<br/>角色-菜单映射"]
URM["UserRoleMapper<br/>用户-角色映射"]
REDIS["Redis 缓存"]
end
subgraph "领域模型"
RoleDO["RoleDO<br/>角色实体"]
MenuDO["MenuDO<br/>菜单实体"]
end
RC --> RS
MC --> MS
RS --> RM
MS --> MM
RS --> RCM
RS --> URM
RS --> REDIS
PS --> RCM
PS --> URM
PS --> REDIS
RM --> RoleDO
MM --> MenuDO

图表来源

章节来源

核心组件

角色管理
- 控制器：提供角色创建、更新、删除、查询、分页、导出、精简列表等接口
- 服务：封装角色 CRUD、缓存读取、角色校验、数据权限设置等
- 数据模型：角色实体含名称、编码、排序、状态、类型、备注、数据范围、指定部门集合等
权限控制
- 基于角色的访问控制（RBAC）：角色-菜单、角色-用户、角色-部门
- 菜单权限：菜单类型区分目录、菜单、按钮；按钮权限以 permission 标识
- 数据权限：支持全部、自定义、本部门、本部门及以下、仅本人五种范围
菜单管理
- 菜单实体含名称、权限标识、类型、排序、父子关系、路由、图标、组件、状态、可见性、缓存等
- 提供菜单创建/更新、列表查询、树形结构等能力

章节来源

架构总览

系统采用“控制器-服务-数据访问-缓存”的分层架构，结合 Spring Security 的 @PreAuthorize 实现后端接口级权限控制，结合前端路由与按钮级权限标识实现前端可视化控制。

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理员"
participant RC as "RoleController"
participant RS as "RoleService"
participant PS as "PermissionService"
participant RM as "RoleMapper"
participant RCM as "RoleMenuMapper"
participant URM as "UserRoleMapper"
participant REDIS as "Redis"
Admin->>RC : POST /system/role/create
RC->>RS : createRole(RoleSaveReqVO)
RS->>RM : 插入角色
RS-->>RC : 返回角色ID
RC-->>Admin : 成功
Admin->>RC : POST /system/role/data-scope
RC->>PS : assignRoleDataScope(roleId, dataScope, deptIds)
PS->>REDIS : 清理/更新角色缓存
PS-->>RC : 完成
Admin->>RC : POST /system/role/menu
RC->>PS : assignRoleMenu(roleId, menuIds)
PS->>RCM : 写入角色-菜单关联
PS->>REDIS : 清理/更新菜单缓存
PS-->>RC : 完成

图表来源

详细组件分析

角色数据模型与字段设计

角色实体 RoleDO 关键字段
- 主键、名称、编码、排序、状态、类型、备注
- 数据范围（全部/自定义/部门/本部门及以下/仅本人）
- 指定部门集合（JSON 序列化存储）
角色类型枚举 RoleTypeEnum
- 内置角色、自定义角色
数据范围枚举 DataScopeEnum
- 全部、自定义、部门、部门及以下、仅本人

Mermaid Diagram Code:

erDiagram
ROLE {
bigint id PK
varchar name
varchar code
int sort
int status
int type
varchar remark
int data_scope
json data_scope_dept_ids
}

图表来源

章节来源

菜单数据模型与权限标识

菜单实体 MenuDO 关键字段
- 名称、权限标识 permission（按钮级别）、类型（目录/菜单/按钮）、排序、父子关系
- 路由 path（外链判断）、图标、组件、组件名
- 状态、可见性、缓存、总是显示
菜单类型枚举 MenuTypeEnum
- 目录、菜单、按钮

Mermaid Diagram Code:

erDiagram
MENU {
bigint id PK
varchar name
varchar permission
int type
int sort
bigint parent_id
varchar path
varchar icon
varchar component
varchar component_name
int status
boolean visible
boolean keep_alive
boolean always_show
}

图表来源

章节来源

RBAC 权限控制机制

角色-菜单：角色拥有若干菜单，菜单 permission 用于后端接口鉴权
角色-用户：用户拥有若干角色，形成权限叠加
角色-部门：角色具备数据权限范围，决定数据可见性
前端控制：菜单 visible/keepAlive/alwaysShow 与按钮 permission 控制展示与可用性

Mermaid Diagram Code:

classDiagram
class RoleDO
class MenuDO
class RoleService
class PermissionService
RoleService --> RoleDO : "管理"
PermissionService --> RoleDO : "设置数据范围"
PermissionService --> MenuDO : "设置菜单权限"

图表来源

章节来源

PermissionService.java

权限API接口文档

角色管理
- POST /system/role/create：创建角色（需要权限 system:role:create）
- PUT /system/role/update：更新角色（需要权限 system:role:update）
- DELETE /system/role/delete?id=...：删除角色（需要权限 system:role:delete）
- GET /system/role/get?id=...：获取角色详情（需要权限 system:role:query）
- GET /system/role/page：分页查询角色（需要权限 system:role:query）
- GET /system/role/simple-list：获取启用状态的角色列表（前端下拉）
- GET /system/role/export-excel：导出角色 Excel（需要权限 system:role:export）
菜单授权
- POST /system/role/menu：赋予角色菜单权限（请求体包含角色ID与菜单ID集合）
数据权限
- POST /system/role/data-scope：设置角色数据权限（请求体包含角色ID、数据范围、部门ID集合）

章节来源

菜单管理API与VO

菜单创建/更新
- 请求体：名称、权限标识（按钮时必填）、类型、排序、父子关系、路由、图标、组件、组件名
菜单列表
- 查询条件：名称（模糊）、状态
菜单响应
- 响应字段：ID、名称、权限标识、类型、排序、父子关系、路由、图标、组件、组件名、状态、可见性、缓存、总是显示
精简菜单
- 响应字段：ID、名称、父ID、类型

章节来源

权限继承、计算与缓存

权限继承
- 用户通过多角色叠加获得权限；角色可拥有多个菜单与数据范围
权限计算
- 菜单权限：角色拥有的菜单集合，前端据此渲染路由与按钮
- 数据权限：根据角色数据范围与用户所在部门计算可查看的部门集合
缓存策略
- 角色、菜单、用户角色映射等关键数据使用 Redis 缓存，更新时清理对应键，保证一致性

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> LoadUser["加载用户角色集合"]
LoadUser --> MergeRoles["合并角色权限"]
MergeRoles --> CalcMenu["计算菜单权限集合"]
MergeRoles --> CalcData["计算数据权限范围"]
CalcMenu --> RenderUI["前端渲染路由/按钮"]
CalcData --> FilterData["过滤数据可见性"]
RenderUI --> End(["结束"])
FilterData --> End

图表来源

章节来源

PermissionService.java

菜单权限与按钮权限

菜单类型
- 目录、菜单、按钮三类
按钮权限
- 仅按钮类型具备 permission，用于后端接口鉴权与前端按钮显隐控制
示例菜单权限标识
- 角色新增、修改、删除等菜单对应的 permission

章节来源

数据权限计算流程

全部数据：返回 all=true
自定义部门：返回指定部门集合 + 用户所在部门
本部门：返回用户所在部门
本部门及以下：返回用户所在部门及其子部门
仅本人：返回 self=true

Mermaid Diagram Code:

flowchart TD
S(["进入 getDeptDataPermission"]) --> GetRoles["获取用户角色列表"]
GetRoles --> Scope{"角色数据范围"}
Scope --> |全部| All["all=true, deptIds=[]"]
Scope --> |自定义| Custom["deptIds=自定义+用户部门"]
Scope --> |本部门| DeptOnly["deptIds=[用户部门]"]
Scope --> |本部门及以下| DeptChild["deptIds=[用户部门+子部门]"]
Scope --> |仅本人| Self["self=true, deptIds=[]"]
All --> R(["返回"])
Custom --> R
DeptOnly --> R
DeptChild --> R
Self --> R

图表来源

章节来源

前端菜单与按钮控制

前端菜单响应包含可见性、缓存、总是显示等字段，用于控制路由渲染
按钮权限标识 permission 用于控制按钮显隐

章节来源

依赖关系分析

控制器依赖服务接口，服务接口依赖 Mapper 与 Redis 缓存
角色服务与权限服务共同依赖枚举与 DTO
菜单实体与角色实体构成权限关联的基础

Mermaid Diagram Code:

graph LR
RC["RoleController"] --> RS["RoleService"]
RC --> PS["PermissionService"]
RS --> RoleDO["RoleDO"]
PS --> MenuDO["MenuDO"]
RS --> REDIS["Redis"]
PS --> REDIS

图表来源

章节来源

性能考量

缓存命中率
- 角色、菜单、用户角色映射等热点数据使用 Redis 缓存，降低数据库压力
批量操作
- 菜单授权与数据权限设置采用批量写入，减少事务开销
查询优化
- 分页查询与简单列表查询分离，避免不必要的字段传输
并发控制
- 使用分布式锁或幂等设计防止并发更新导致的脏数据

故障排查指南

角色权限不生效
- 检查角色状态是否启用、角色是否绑定目标菜单、按钮权限标识是否正确
- 确认 @PreAuthorize 注解与 permission 是否一致
数据权限异常
- 核对角色数据范围与用户所在部门层级，确认 getDeptDataPermission 计算逻辑
缓存不一致
- 更新角色/菜单/权限后，检查缓存清理逻辑是否执行
导出失败
- 检查导出接口分页大小限制与 Excel 写入逻辑

章节来源

结论

Yudao Cloud 的角色权限体系以 RBAC 为核心，结合菜单权限、按钮权限与数据权限，形成多层次的安全控制。通过清晰的领域模型、完善的 API 接口与缓存策略，系统在保证安全性的同时兼顾性能与可维护性。建议在生产环境中严格遵循权限最小化原则，定期审计角色与权限配置，并完善监控与告警机制。

附录

角色管理操作指南与字段说明可参考官方文档
菜单权限标识可在数据库初始化脚本中查看示例

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

角色数据模型与字段设计​

菜单数据模型与权限标识​

RBAC 权限控制机制​

权限API接口文档​

菜单管理API与VO​

权限继承、计算与缓存​

菜单权限与按钮权限​

数据权限计算流程​

前端菜单与按钮控制​

依赖关系分析​

性能考量​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

角色数据模型与字段设计

菜单数据模型与权限标识

RBAC 权限控制机制

权限API接口文档

菜单管理API与VO

权限继承、计算与缓存

菜单权限与按钮权限

数据权限计算流程

前端菜单与按钮控制

依赖关系分析

性能考量

故障排查指南

结论

附录