You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
22 KiB
22 KiB
菜单权限控制
**本文引用的文件** - [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java) - [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java) - [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java) - [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java) - [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.java) - [ISysMenuService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysMenuService.java) - [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java) - [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.java) - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java) - [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java) - [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java) - [AuthLoginUser.java](file://crm-auth/src/main/java/com/crm/auth/security/AuthLoginUser.java) - [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java) - [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)目录
简介
本技术文档围绕“菜单权限控制模块”展开，重点覆盖以下能力：
- 菜单树形结构设计：支持目录、菜单、按钮等多层级组织与展示。
- 菜单权限的层级控制：基于角色-菜单关联实现细粒度权限控制。
- 动态菜单生成：根据当前登录用户及其角色，动态构建可见菜单树。
- 菜单类型枚举使用场景：目录、菜单、按钮等类型的差异化权限策略。
- 缓存机制：通过 Redis 缓存菜单树与权限集合，降低数据库压力。
- 前端集成方案：提供接口契约与数据模型说明，便于前端渲染与按钮级权限控制。
- 配置示例与常见问题：给出典型配置思路与排错清单。
项目结构
该模块位于 crm-auth 子模块中，围绕实体、枚举、映射器、服务、控制器与安全过滤器协同工作；通用能力（如 Redis 配置、工具类）位于 crm-base。
graph TB
subgraph "认证授权(crm-auth)"
A["SysMenu(实体)"]
B["SysRoleMenu(实体)"]
C["MenuTypeEnum(枚举)"]
D["SysMenuMapper(映射)"]
E["SysRoleMenuMapper(映射)"]
F["ISysMenuService(接口)"]
G["SysMenuServiceImpl(实现)"]
H["PermissionServiceImpl(实现)"]
I["AuthController(控制器)"]
J["SystemController(控制器)"]
K["JwtAuthenticationFilter(过滤器)"]
L["TokenService(令牌服务)"]
M["AuthLoginUser(登录用户上下文)"]
end
subgraph "基础能力(crm-base)"
N["RedisConfig(Redis配置)"]
O["TreeUtils(树工具)"]
end
A --> D
B --> E
F --> G
G --> D
G --> E
H --> F
I --> F
J --> F
K --> L
L --> M
G --> N
G --> O
图表来源
- SysMenu.java
- SysRoleMenu.java
- MenuTypeEnum.java
- SysMenuMapper.java
- SysRoleMenuMapper.java
- ISysMenuService.java
- SysMenuServiceImpl.java
- PermissionServiceImpl.java
- AuthController.java
- SystemController.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthLoginUser.java
- RedisConfig.java
- TreeUtils.java
章节来源
- SysMenu.java
- SysRoleMenu.java
- MenuTypeEnum.java
- ISysMenuService.java
- SysMenuServiceImpl.java
- PermissionServiceImpl.java
- AuthController.java
- SystemController.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthLoginUser.java
- RedisConfig.java
- TreeUtils.java
核心组件
- 菜单实体 SysMenu：定义菜单节点的基本信息、层级关系、排序、状态及类型字段，支撑树形结构与权限标识。
- 角色-菜单关联 SysRoleMenu：维护角色与菜单的多对多关系，用于权限判定。
- 菜单类型 MenuTypeEnum：区分目录、菜单、按钮等不同类型，驱动不同的权限控制策略。
- 映射层 SysMenuMapper / SysRoleMenuMapper：封装菜单与角色-菜单的数据访问操作。
- 服务层 ISysMenuService / SysMenuServiceImpl：提供菜单查询、树构建、权限计算、缓存读写等核心逻辑。
- 权限服务 PermissionServiceImpl：聚合用户-角色-菜单权限，输出权限集合或菜单树。
- 控制器 AuthController / SystemController：暴露获取菜单树、权限码列表等接口。
- 安全组件 JwtAuthenticationFilter / TokenService / AuthLoginUser：解析 JWT、加载用户上下文，为权限判断提供身份依据。
- 基础设施 RedisConfig / TreeUtils：提供缓存能力与树结构组装工具。
章节来源
- SysMenu.java
- SysRoleMenu.java
- MenuTypeEnum.java
- SysMenuMapper.java
- SysRoleMenuMapper.java
- ISysMenuService.java
- SysMenuServiceImpl.java
- PermissionServiceImpl.java
- AuthController.java
- SystemController.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthLoginUser.java
- RedisConfig.java
- TreeUtils.java
架构总览
下图展示了从请求进入、鉴权到菜单权限计算的完整链路。
sequenceDiagram
participant FE as "前端"
participant API as "SystemController/AuthController"
participant SVC as "ISysMenuService/SysMenuServiceImpl"
participant PERM as "PermissionServiceImpl"
participant MAP as "SysMenuMapper/SysRoleMenuMapper"
participant REDIS as "Redis"
participant AUTH as "JwtAuthenticationFilter/TokenService"
participant USER as "AuthLoginUser"
FE->>API : "请求获取菜单/权限"
API->>AUTH : "解析JWT并加载用户上下文"
AUTH-->>USER : "返回当前用户信息"
API->>SVC : "调用获取菜单树/权限接口"
SVC->>REDIS : "尝试读取缓存"
alt "缓存命中"
REDIS-->>SVC : "返回已缓存的菜单树/权限集"
else "缓存未命中"
SVC->>PERM : "计算用户权限集合"
PERM->>MAP : "查询角色-菜单关联"
MAP-->>PERM : "返回关联数据"
PERM-->>SVC : "返回权限集合"
SVC->>SVC : "构建菜单树"
SVC->>REDIS : "写入缓存"
end
SVC-->>API : "返回菜单树/权限集"
API-->>FE : "响应结果"
图表来源
- SystemController.java
- AuthController.java
- ISysMenuService.java
- SysMenuServiceImpl.java
- PermissionServiceImpl.java
- SysMenuMapper.java
- SysRoleMenuMapper.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthLoginUser.java
- RedisConfig.java
详细组件分析
菜单实体与类型设计
- SysMenu 实体包含菜单编码、名称、父节点ID、层级、排序、状态、类型等字段，用于表达树形结构与权限标识。
- MenuTypeEnum 定义目录、菜单、按钮等类型，不同类别对应不同的权限控制策略：
- 目录：仅控制可见性，不直接绑定资源。
- 菜单：控制页面路由与导航可见性。
- 按钮：控制页面内操作按钮的显示与可点击。
classDiagram
class SysMenu {
+id
+parent_id
+name
+code
+type
+sort
+status
+path
+component
+permission
}
class MenuTypeEnum {
<<enumeration>>
+目录
+菜单
+按钮
}
class SysRoleMenu {
+id
+role_id
+menu_id
}
SysMenu <.. SysRoleMenu : "被角色关联"
图表来源
- SysMenu.java
- MenuTypeEnum.java
- SysRoleMenu.java
章节来源
- SysMenu.java
- MenuTypeEnum.java
- SysRoleMenu.java
菜单树构建与权限计算流程
- 服务层负责从数据库查询菜单与角色-菜单关联，结合用户角色计算权限集合，再按类型过滤与排序构建树。
- 树构建过程中，目录作为容器，菜单作为路由节点，按钮作为叶子节点参与权限校验。
flowchart TD
Start(["开始"]) --> LoadUser["加载当前用户与角色"]
LoadUser --> CheckCache{"是否命中缓存?"}
CheckCache --> |是| ReturnCache["返回缓存中的菜单树/权限集"]
CheckCache --> |否| QueryDB["查询菜单与角色-菜单关联"]
QueryDB --> CalcPerms["计算权限集合"]
CalcPerms --> BuildTree["按类型构建菜单树"]
BuildTree --> WriteCache["写入缓存"]
WriteCache --> ReturnResult["返回结果"]
ReturnCache --> End(["结束"])
ReturnResult --> End
图表来源
- ISysMenuService.java
- SysMenuServiceImpl.java
- PermissionServiceImpl.java
- SysMenuMapper.java
- SysRoleMenuMapper.java
- TreeUtils.java
章节来源
- ISysMenuService.java
- SysMenuServiceImpl.java
- PermissionServiceImpl.java
- SysMenuMapper.java
- SysRoleMenuMapper.java
- TreeUtils.java
控制器与接口契约
- SystemController 暴露获取菜单树与权限码列表的接口，供前端初始化时拉取。
- AuthController 提供登录相关接口，登录后返回用户基本信息与令牌，后续请求携带令牌以进行权限校验。
章节来源
- SystemController.java
- AuthController.java
安全过滤器与用户上下文
- JwtAuthenticationFilter 在请求到达控制器前解析 JWT，提取用户身份信息。
- TokenService 负责令牌校验与刷新策略。
- AuthLoginUser 承载当前登录用户的上下文信息，包括用户ID、角色集合等，供权限计算使用。
章节来源
- JwtAuthenticationFilter.java
- TokenService.java
- AuthLoginUser.java
缓存机制与工具类
- RedisConfig 提供 Redis 客户端配置，用于缓存菜单树与权限集合。
- TreeUtils 提供树结构组装工具，将扁平菜单列表转换为树形结构。
章节来源
- RedisConfig.java
- TreeUtils.java
依赖关系分析
- 控制器依赖服务层，服务层依赖映射器与缓存，权限服务依赖用户上下文与角色-菜单映射。
- 安全过滤器依赖令牌服务，令牌服务依赖用户上下文。
graph LR
Controller["SystemController/AuthController"] --> Service["ISysMenuService/SysMenuServiceImpl"]
Service --> Mapper["SysMenuMapper/SysRoleMenuMapper"]
Service --> Cache["Redis"]
Service --> Utils["TreeUtils"]
Service --> Perm["PermissionServiceImpl"]
Perm --> Context["AuthLoginUser"]
Filter["JwtAuthenticationFilter"] --> Token["TokenService"]
Token --> Context
图表来源
- SystemController.java
- AuthController.java
- ISysMenuService.java
- SysMenuServiceImpl.java
- SysMenuMapper.java
- SysRoleMenuMapper.java
- PermissionServiceImpl.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthLoginUser.java
章节来源
- SystemController.java
- AuthController.java
- ISysMenuService.java
- SysMenuServiceImpl.java
- SysMenuMapper.java
- SysRoleMenuMapper.java
- PermissionServiceImpl.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthLoginUser.java
性能考虑
- 缓存优先：首次请求后缓存菜单树与权限集合，减少重复查询。
- 合理键名：按用户ID或角色维度设计缓存键，避免冲突。
- 失效策略：当菜单或角色-菜单关联变更时主动清理相关缓存。
- 分页与懒加载：对于大型菜单树，可在前端按需加载子节点。
- 索引优化：确保菜单表与角色-菜单表的关联字段有合适索引。
[本节为通用指导，无需特定文件引用]
故障排查指南
- 菜单树为空：检查用户是否有角色分配，确认角色-菜单关联是否存在。
- 权限不一致：核对缓存是否过期或未及时清理，确认权限计算逻辑是否包含目标菜单类型。
- 按钮不可见：确认按钮类型与权限码匹配，前端是否正确渲染权限指令。
- 登录失败：检查 JWT 解析与令牌服务配置，确认用户上下文是否正确加载。
- 缓存异常：检查 Redis 连接与序列化配置，确认键名与过期时间设置。
章节来源
- SysMenuServiceImpl.java
- PermissionServiceImpl.java
- JwtAuthenticationFilter.java
- TokenService.java
- AuthLoginUser.java
- RedisConfig.java
结论
本模块通过清晰的实体设计与分层架构，实现了灵活的菜单树形结构与细粒度的权限控制。借助缓存与工具类，提升了性能与可维护性。配合前端集成方案，可实现完整的动态菜单与按钮级权限控制。
[本节为总结性内容，无需特定文件引用]
附录
菜单类型与权限策略对照
- 目录：控制可见性与展开行为，不直接绑定资源权限。
- 菜单：控制页面路由与导航可见性，通常对应前端路由。
- 按钮：控制页面内操作按钮的显示与可点击，需在后端进行接口级权限校验。
章节来源
- MenuTypeEnum.java
- SysMenu.java
前端集成要点
- 登录后拉取菜单树与权限码列表，存储至本地状态。
- 路由守卫根据菜单类型与权限码决定是否允许进入。
- 按钮级权限通过指令或条件渲染控制显示与禁用。
- 菜单变更时主动刷新缓存与前端状态。
章节来源
- SystemController.java
- AuthController.java
常见配置示例（思路）
- 菜单表字段：父节点ID、编码、名称、类型、排序、状态、路径、组件、权限码。
- 角色-菜单关联：角色ID、菜单ID。
- 缓存键命名：user_menu_tree:{userId}、user_perms:{userId}。
- 失效时机：菜单增删改、角色-菜单关联变更、用户角色变更。
章节来源
- SysMenu.java
- SysRoleMenu.java
- RedisConfig.java