学习笔记若依微服务 源码分析

1. 模块概述

ruoyi-system 是整个平台的 核心业务模块，负责用户、角色、菜单、部门、岗位、字典、配置、通知公告、操作日志、登录日志等全部系统管理功能。

模块分层架构

graph TB
    subgraph Controller层
        UC[SysUserController]
        RC[SysRoleController]
        MC[SysMenuController]
        DC[SysDeptController]
    end

    subgraph Service层
        USI[ISysUserService]
        US[SysUserServiceImpl]
        PS[SysPermissionServiceImpl]
        MS[SysMenuServiceImpl]
        RS[SysRoleServiceImpl]
    end

    subgraph Mapper层
        UM[SysUserMapper]
        RM[SysRoleMapper]
        MM[SysMenuMapper]
        DM[SysDeptMapper]
    end

    subgraph AOP切面
        DS[DataScopeAspect
数据权限]
        IA[InnerAuthAspect
内部认证]
    end

    subgraph Domain
        SYS_USER[SysUser]
        SYS_ROLE[SysRole]
        SYS_MENU[SysMenu]
    end

    UC --> USI
    RC --> RS
    MC --> MS
    DC --> DC
    USI --> US
    US --> UM
    US --> DS
    RS --> RM
    MS --> MM
    US --> PS
    PS --> RS
    PS --> MS

核心业务表关系

1
2
3
4
5
sys_user ──< sys_user_role >── sys_role ──< sys_role_menu >── sys_menu
    │                                │
    │                                ├── sys_role_dept (数据权限)
    │                                │
    └── sys_user_post ──< sys_post   └── sys_dept

2. 命名体系与易混淆函数对比

2.1 命名规律拆解

前缀 模块/对象 后缀 含义 示例
select User ById 按主键查询单个对象 selectUserById(Long)
select User ByUserName 按用户名查询 selectUserByUserName(String)
select User List 分页列表查询（含数据权限过滤） selectUserList(SysUser)
select User AllocatedList 已分配某角色的用户列表 selectAllocatedList(SysUser)
select User UnallocatedList 未分配某角色的用户列表 selectUnallocatedList(SysUser)
insert User — 新增用户（含关联表操作） insertUser(SysUser)
update User — 修改用户（先删关联再重建） updateUser(SysUser)
delete User ById 按 ID 删除用户（含关联表） deleteUserById(Long)
delete User ByIds 批量删除用户 deleteUserByIds(Long[])
check User NameUnique 校验用户名唯一性 checkUserNameUnique(SysUser)
select Menu PermsByUserId 按用户 ID 查询权限集合 selectMenuPermsByUserId(Long)
select Menu PermsByRoleId 按角色 ID 查询权限集合 selectMenuPermsByRoleId(Long)
select Menu TreeByUserId 按用户 ID 查询菜单树 selectMenuTreeByUserId(Long)
build Menus — 将菜单列表转为前端路由格式 buildMenus(List)
build Menu Tree 将菜单列表转为树结构 buildMenuTree(List)

命名规律总结：

  1. selectXxxByUserId vs selectXxxByRoleId：分别从用户维度和角色维度查询，前者用于用户登录后加载菜单，后者用于角色授权时展示可选权限
  2. buildMenus 是前端路由适配层，buildMenuTree 是通用树结构转换，两者返回类型不同（RouterVo vs SysMenu）

2.2 易混淆函数对比表

selectMenuPermsByUserId vs selectMenuPermsByRoleId vs selectMenuTreeByUserId

对比维度 selectMenuPermsByUserId selectMenuPermsByRoleId selectMenuTreeByUserId
输入 用户 ID 角色 ID 用户 ID
输出 Set<String> 权限标识 Set<String> 权限标识 List<SysMenu> 菜单树
用途 用户登录时加载权限列表 角色授权时展示可选权限 前端渲染侧边栏菜单
调用者 SysPermissionServiceImpl SysPermissionServiceImpl SysLoginService（通过 Feign）
一句话区分 用户维度查权限 vs 角色维度查权限 vs 用户维度查菜单树

getRolePermission vs getMenuPermission

对比维度 getRolePermission getMenuPermission
返回 角色标识集合（如 admin） 权限标识集合（如 system:user:list）
用途 角色校验（@RequiresRoles） 权限校验（@RequiresPermissions）
管理员返回值 {"admin"} {"*:*:*"}
一句话区分 告诉系统”你是谁” vs 告诉系统”你能做什么”

3. API Signatures

调用关系图

graph TD
    subgraph "用户登录权限加载"
        SLS["SysLoginService.getUserInfo"] --> SPS["PermissionService.getRolePermission"]
        SLS --> SPS2["PermissionService.getMenuPermission"]
        SPS --> RS["RoleService.selectRolePermissionByUserId"]
        SPS2 --> MS["MenuService.selectMenuPermsByUserId"]
    end

    subgraph "用户管理"
        UC1["SysUserController.list"] --> US1["SysUserServiceImpl.selectUserList"]
        UC2["SysUserController.add"] --> US2["SysUserServiceImpl.insertUser"]
        UC3["SysUserController.edit"] --> US3["SysUserServiceImpl.updateUser"]
        US1 -.->|DataScope| DS["DataScopeAspect"]
        US2 --> US2A["insertUserPost"]
        US2 --> US2B["insertUserRole"]
        US3 --> US3A["delete+insert UserRole"]
        US3 --> US3B["delete+insert UserPost"]
    end

    subgraph "菜单路由构建"
        MC1["SysMenuController.treeselect"] --> MS1["SysMenuServiceImpl.selectMenuTreeByUserId"]
        MS1 --> MS1A["getChildPerms
递归构建树"]
        MS1A --> MS1B["recursionFn
递归设置children"]
    end

    subgraph "数据权限"
        DS --> DSF["dataScopeFilter
动态拼SQL"]
        DSF --> DSL{"遍历用户角色
按数据权限级别"}
        DSL -->|ALL| DSLA["不过滤"]
        DSL -->|CUSTOM| DSLC["子查询sys_role_dept"]
        DSL -->|DEPT| DSLD["dept_id=当前部门"]
        DSL -->|DEPT_AND_CHILD| DSLE["递归查子部门"]
        DSL -->|SELF| DSLF["user_id=当前用户"]
    end

完整签名（核心函数）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
// === SysUserServiceImpl ===
@Override
@DataScope(deptAlias = "d", userAlias = "u")
public List<SysUser> selectUserList(SysUser user);
  // 分页查询用户列表，通过 @DataScope 自动注入数据权限过滤条件
  // 场景：用户管理列表页，不同角色看到不同范围的用户

@Override
@Transactional(rollbackFor = Exception.class)
public int insertUser(SysUser user);
  // 新增用户：插入用户表 + 批量插入用户-岗位关联 + 批量插入用户-角色关联
  // 场景：管理员新建用户

@Override
@Transactional(rollbackFor = Exception.class)
public int updateUser(SysUser user);
  // 修改用户：先删关联再重建（userRole + userPost）
  // 场景：管理员编辑用户信息（含角色和岗位调整）

public void checkUserAllowed(SysUser user);
  // 校验是否允许操作该用户（超级管理员不可被非管理员操作）
  // 场景：修改/删除用户前的安全检查

public void checkUserDataScope(Long userId);
  // 校验当前操作者是否有该用户的数据权限
  // 场景：修改/删除用户前的数据权限检查

@Override
public String importUser(List<SysUser> userList, Boolean isUpdateSupport, String operName);
  // 批量导入用户：遍历列表，已存在则更新（需 isUpdateSupport=true），否则新增
  // 场景：Excel 批量导入用户

// === SysMenuServiceImpl ===
@Override
public List<SysMenu> selectMenuTreeByUserId(Long userId);
  // 按用户 ID 查询菜单树（管理员查全部，普通用户查授权菜单）
  // 场景：用户登录后构建左侧菜单树

@Override
public List<RouterVo> buildMenus(List<SysMenu> menus);
  // 将 SysMenu 列表转为前端 Vue Router 格式
  // 场景：用户登录后返回路由表给前端动态渲染

@Override
public List<SysMenu> buildMenuTree(List<SysMenu> menus);
  // 将扁平菜单列表转为父子树结构
  // 场景：菜单管理页面的树形展示

@Override
public boolean checkRouteConfigUnique(SysMenu menu);
  // 校验路由名称和路径的唯一性（同级路径唯一、路由名称全局唯一）
  // 场景：新增/修改菜单时的配置校验

public List<SysMenu> getChildPerms(List<SysMenu> list, long parentId);
  // 从扁平列表中筛选指定父节点的所有子节点并递归构建子树
  // 场景：selectMenuTreeByUserId 内部调用

// === SysPermissionServiceImpl ===
@Override
public Set<String> getRolePermission(SysUser user);
  // 获取用户角色集合（管理员返回 "admin"）
  // 场景：登录时加载用户角色，供 @RequiresRoles 校验

@Override
public Set<String> getMenuPermission(SysUser user);
  // 获取用户权限集合（管理员返回 "*:*:*"）
  // 场景：登录时加载用户权限，供 @RequiresPermissions 校验

// === DataScopeAspect ===
@Before("@annotation(controllerDataScope)")
public void doBefore(JoinPoint point, DataScope controllerDataScope);
  // AOP 前置通知：先清空旧 dataScope，再根据当前用户生成新的过滤 SQL
  // 场景：被 @DataScope 标记的方法执行前触发

public static void dataScopeFilter(JoinPoint joinPoint, SysUser user, String userAlias, String deptAlias, String userField, String deptField, String permission);
  // 核心算法：遍历用户角色，按五级数据权限级别拼接 SQL WHERE 子句
  // 场景：doBefore → handleDataScope → dataScopeFilter 调用链

4. 数据结构深度解析

4.a SysUser — 为什么需要这个结构体

用户是系统的核心实体，几乎所有业务操作都需要关联到用户。SysUser 不仅承载用户的基本身份信息（用户名、密码、部门），还作为 MyBatis 的 ORM 映射对象，与 sys_user 表一一对应。其 isAdmin() 方法（判断 userId 是否为 1）是整个权限体系的关键分支点——超级管理员在数据权限和菜单权限上都有特殊处理。

4.b 结构定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public class SysUser extends BaseEntity {
    private Long userId;         // 用户ID
    private Long deptId;         // 部门ID
    private String userName;     // 登录用户名
    private String nickName;     // 昵称
    private String email;        // 邮箱
    private String phonenumber;  // 手机号
    private String sex;          // 性别
    private String avatar;       // 头像
    private String password;     // 密码（BCrypt加密）
    private String status;       // 状态（0正常 1停用）
    private String delFlag;      // 删除标记（0正常 2删除）
    private String loginIp;      // 最后登录IP
    private Date loginDate;      // 最后登录时间
    private Long[] roleIds;      // 角色组（非DB字段，用于接收前端参数）
    private Long[] postIds;      // 岗位组（非DB字段，用于接收前端参数）
    private List<SysRole> roles; // 角色列表（非DB字段，用于缓存角色信息）
    // 继承自 BaseEntity: createBy, createTime, updateBy, updateTime, remark, params
}

4.c 字段三层分析表

字段 设计动机（为什么需要） 反事实（如果去掉会怎样） 替代方案（还能怎么做）
roleIds (Long[]) 前端修改用户时一次性传入角色列表，后端接收后批量处理关联表 需要额外的接口来管理用户-角色关系，增加前端交互复杂度 可以用独立的用户授权接口，但会多一次网络请求
roles (List<SysRole>) 缓存用户拥有的完整角色对象，供数据权限过滤使用 数据权限过滤时需要每次查询角色表，增加 DB 压力 可以将角色信息存入 Redis 而不是实体中，但增加了序列化复杂度
delFlag 逻辑删除标记，保留数据用于审计和恢复 物理删除后无法追溯历史操作记录，误删无法恢复 可以用专门的归档表，但增加了数据迁移成本
status 独立于 delFlag 的停用状态，支持临时冻结账号 停用和删除混在一起，无法区分”暂时冻结”和”永久删除” 可以用一个枚举状态字段，但语义不如两个独立字段清晰
isAdmin() 一行代码判断是否为超级管理员（userId == 1），权限系统的核心分支 每个需要判断管理员的代码都要重复 userId == 1L 的判断 可以用角色判断（hasRole("admin")），但 userId 判断更快且不依赖角色数据

4.d 用户生命周期状态图

stateDiagram-v2
    [*] --> 新建: insertUser()
    新建 --> 正常: status=0, delFlag=0
    正常 --> 停用: updateUserStatus(status=1)
    停用 --> 正常: updateUserStatus(status=0)
    正常 --> 已删除: deleteUserById()
    停用 --> 已删除: deleteUserById()
    已删除 --> [*]: 数据保留不物理删除

4.e SysMenu 结构定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public class SysMenu extends BaseEntity {
    private Long menuId;        // 菜单ID
    private String menuName;    // 菜单名称
    private Long parentId;      // 父菜单ID（0=顶级）
    private Integer orderNum;   // 排序号
    private String path;        // 路由地址
    private String component;   // 组件路径
    private String query;       // 路由参数
    private String routeName;   // 路由名称
    private String isFrame;     // 是否外链
    private String isCache;     // 是否缓存
    private String menuType;    // 菜单类型（M目录 C菜单 F按钮）
    private String visible;     // 是否显示
    private String status;      // 状态
    private String perms;       // 权限标识（如 system:user:list）
    private String icon;        // 图标
    private List<SysMenu> children; // 子菜单列表（非DB字段）
}

4.f SysMenu 字段三层分析表

字段 设计动机（为什么需要） 反事实（如果去掉会怎样） 替代方案（还能怎么做）
menuType 区分目录/菜单/按钮三种类型，决定了前端如何渲染 无法区分导航节点和操作按钮，权限粒度太粗 可以用单独的权限表，但增加了表关联复杂度
perms 权限标识字符串，是 @RequiresPermissions 校验的匹配目标 只能用 URL 做权限控制，无法精细到按钮级别 可以用 RBAC 标准模型，但 system:user:list 格式更直观
component 前端 Vue 组件的路径，用于动态路由加载 前端无法知道该菜单对应哪个 .vue 文件，需要硬编码路由映射 可以用约定大于配置（路径自动推导组件），但灵活性差
children 非 DB 字段，运行时填充子菜单，用于构建树结构 每次需要树结构时都要重新查询和组装，性能差 可以存 parentId 由前端自行组装，但增加前端计算开销

5. 函数逐行精讲

5.a 菜单树构建

函数：SysMenuServiceImpl.buildMenus()

  • 调用时机：用户登录后获取路由信息
  • 典型调用者：SysLoginService.getUserInfo()（通过 Feign → Controller → Service）
  • 前置条件：已从数据库加载用户的菜单列表（含父子关系）
  • 目的：将数据库中的 SysMenu 对象转为前端 Vue Router 需要的 RouterVo 格式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
@Override
public List<RouterVo> buildMenus(List<SysMenu> menus)
// → 构建前端路由，输入是扁平菜单列表（已通过 getChildPerms 构建了 children 树）
{
    List<RouterVo> routers = new LinkedList<RouterVo>();
    // → 使用 LinkedList（非 ArrayList），因为后续有较多 add 操作
    for (SysMenu menu : menus)
    // → 遍历顶级菜单（传入的 menus 已经是顶层节点列表）
    {
        RouterVo router = new RouterVo();
        // → 为每个菜单创建前端路由对象
        router.setHidden("1".equals(menu.getVisible()));
        // → visible=1 表示隐藏，RouterVo 用 hidden 字段（语义反转）
        router.setName(getRouteName(menu));
        // → 获取路由名称（驼峰格式），用于 Vue Router 的 name 属性
        router.setPath(getRouterPath(menu));
        // → 获取路由路径，一级目录自动加 "/" 前缀
        router.setComponent(getComponent(menu));
        // → 获取 Vue 组件路径，如 "system/user/index"
        router.setQuery(menu.getQuery());
        // → 路由参数（如 ?id=1）
        router.setMeta(new MetaVo(menu.getMenuName(), menu.getIcon(), StringUtils.equals("1", menu.getIsCache()), menu.getPath()));
        // → Meta 信息：标题、图标、是否缓存、激活路径
        List<SysMenu> cMenus = menu.getChildren();
        // → 获取子菜单列表
        if (StringUtils.isNotEmpty(cMenus) && UserConstants.TYPE_DIR.equals(menu.getMenuType()))
        // → 情况1：目录类型且有子菜单 → 渲染为可展开的父路由
        {
            router.setAlwaysShow(true);
            // → 强制显示（即使只有一个子菜单）
            router.setRedirect("noRedirect");
            // → 不自动重定向到第一个子路由
            router.setChildren(buildMenus(cMenus));
            // → 递归构建子路由
        }
        else if (isMenuFrame(menu))
        // → 情况2：一级菜单且是内部跳转（非外链）
        {
            router.setMeta(null);
            // → 一级菜单不显示 meta（由子路由的 meta 代替）
            List<RouterVo> childrenList = new ArrayList<RouterVo>();
            RouterVo children = new RouterVo();
            children.setPath(menu.getPath());
            children.setComponent(menu.getComponent());
            children.setName(getRouteName(menu.getRouteName(), menu.getPath()));
            children.setMeta(new MetaVo(menu.getMenuName(), menu.getIcon(), StringUtils.equals("1", menu.getIsCache()), menu.getPath()));
            children.setQuery(menu.getQuery());
            childrenList.add(children);
            router.setChildren(childrenList);
            // → 将一级菜单自身包装为一个子路由
        }
        else if (menu.getParentId().intValue() == MENU_ROOT_ID && isInnerLink(menu))
        // → 情况3：顶级内链（如跳转到外部URL）
        {
            router.setMeta(new MetaVo(menu.getMenuName(), menu.getIcon()));
            router.setPath("/");
            List<RouterVo> childrenList = new ArrayList<RouterVo>();
            RouterVo children = new RouterVo();
            String routerPath = innerLinkReplaceEach(menu.getPath());
            // → 将 "https://" 等字符替换为 "/"，适配前端 iframe 渲染
            children.setPath(routerPath);
            children.setComponent(UserConstants.INNER_LINK);
            // → 使用内链专用组件
            children.setName(getRouteName(menu.getRouteName(), routerPath));
            children.setMeta(new MetaVo(menu.getMenuName(), menu.getIcon(), menu.getPath()));
            childrenList.add(children);
            router.setChildren(childrenList);
        }
        routers.add(router);
        // → 将构建好的路由添加到结果列表
    }
    return routers;
}
// → 如果执行到这里，返回的是可直接用于 Vue Router 的动态路由数组

5.b 数据权限 SQL 拼接

函数：DataScopeAspect.dataScopeFilter()

  • 调用时机：被 @DataScope 标记的方法执行前（AOP Before）
  • 典型调用者：DataScopeAspect.handleDataScope()
  • 前置条件：当前用户已登录，拥有角色和数据权限级别信息
  • 目的：根据用户角色的数据权限级别动态拼接 SQL WHERE 子句
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
public static void dataScopeFilter(JoinPoint joinPoint, SysUser user, String userAlias, String deptAlias, String userField, String deptField, String permission)
// → 数据权限过滤核心方法
{
    StringBuilder sqlString = new StringBuilder();
    // → 动态拼接的 SQL WHERE 条件
    List<String> conditions = new ArrayList<String>();
    // → 已处理的数据权限级别（去重用，同一级别只处理一次）
    List<String> scopeCustomIds = new ArrayList<String>();
    // → 自定义数据权限的角色 ID 列表
    user.getRoles().forEach(role -> {
    // → 第一遍遍历：收集所有自定义数据权限的角色 ID
        if (Constants.Dept.DATA_SCOPE_CUSTOM.equals(role.getDataScope()) && StringUtils.equals(role.getStatus(), UserConstants.ROLE_NORMAL) && (StringUtils.isEmpty(permission) || StringUtils.containsAny(role.getPermissions(), Convert.toStrArray(permission))))
        // → 三个条件：1) 数据权限类型为"自定义"  2) 角色状态正常  3) 角色拥有该方法的权限字符
        {
            scopeCustomIds.add(Convert.toStr(role.getRoleId()));
            // → 收集角色 ID，后续统一用 IN 查询
        }
    });

    for (SysRole role : user.getRoles())
    // → 第二遍遍历：按数据权限级别生成 SQL
    {
        String dataScope = role.getDataScope();
        // → 获取角色的数据权限级别
        if (conditions.contains(dataScope) || StringUtils.equals(role.getStatus(), UserConstants.ROLE_DISABLE))
        // → 跳过已处理的级别和已停用的角色
        {
            continue;
        }
        if (StringUtils.isNotEmpty(permission) && !StringUtils.containsAny(role.getPermissions(), Convert.toStrArray(permission)))
        // → 如果方法指定了权限字符，且该角色不包含此权限，则跳过
        {
            continue;
        }
        if (Constants.Dept.DATA_SCOPE_ALL.equals(dataScope))
        // → 全部数据权限：不需要任何过滤条件
        {
            sqlString = new StringBuilder();
            // → 清空之前拼接的条件（全部权限优先级最高）
            conditions.add(dataScope);
            break;
            // → 退出循环，无需再处理其他级别
        }
        else if (Constants.Dept.DATA_SCOPE_CUSTOM.equals(dataScope))
        // → 自定义数据权限：通过 sys_role_dept 关联表查询可访问的部门
        {
            if (scopeCustomIds.size() > 1)
            {
                // 多个自定数据权限使用in查询，避免多次拼接。
                sqlString.append(StringUtils.format(" OR {}.{} IN ( SELECT dept_id FROM sys_role_dept WHERE role_id in ({}) ) ", deptAlias, deptField, String.join(",", scopeCustomIds)));
                // → 多个自定义角色合并为一条 IN 查询，减少 SQL 复杂度
            }
            else
            {
                sqlString.append(StringUtils.format(" OR {}.{} IN ( SELECT dept_id FROM sys_role_dept WHERE role_id = {} ) ", deptAlias, deptField, role.getRoleId()));
                // → 单个自定义角色直接查
            }
        }
        else if (Constants.Dept.DATA_SCOPE_DEPT.equals(dataScope))
        // → 本部门数据权限：只能看自己部门的数据
        {
            sqlString.append(StringUtils.format(" OR {}.{} = {} ", deptAlias, deptField, user.getDeptId()));
            // → WHERE d.dept_id = 当前用户的部门ID
        }
        else if (Constants.Dept.DATA_SCOPE_DEPT_AND_CHILD.equals(dataScope))
        // → 本部门及以下数据权限：递归查子部门
        {
            sqlString.append(StringUtils.format(" OR {}.{} IN ( SELECT dept_id FROM sys_dept WHERE dept_id = {} or find_in_set( {} , ancestors ) )", deptAlias, deptField, user.getDeptId(), user.getDeptId()));
            // → 使用 MySQL 的 find_in_set 函数递归匹配 ancestors 字段（形如 "0,100,200"）
        }
        else if (Constants.Dept.DATA_SCOPE_SELF.equals(dataScope))
        // → 仅本人数据权限
        {
            if (StringUtils.isNotBlank(userAlias))
            // → 如果方法配置了 userAlias（如 selectUserList 的 userAlias="u"）
            {
                sqlString.append(StringUtils.format(" OR {}.{} = {} ", userAlias, userField, user.getUserId()));
                // → WHERE u.user_id = 当前用户ID
            }
            else
            {
                // 数据权限为仅本人且没有userAlias别名不查询任何数据
                sqlString.append(StringUtils.format(" OR {}.{} = 0 ", deptAlias, deptField));
                // → 安全策略：无法定位到用户字段时，返回空结果（dept_id = 0 永远不成立）
            }
        }
        conditions.add(dataScope);
        // → 标记该级别已处理，防止同一用户多个相同级别的角色重复拼接
    }

    // 角色都不包含传递过来的权限字符，这个时候sqlString也会为空，所以要限制一下,不查询任何数据
    if (StringUtils.isEmpty(conditions))
    // → 所有角色都不满足权限要求
    {
        sqlString.append(StringUtils.format(" OR {}.{} = 0 ", deptAlias, deptField));
        // → 强制返回空结果集
    }

    if (StringUtils.isNotBlank(sqlString.toString()))
    // → 如果生成了过滤条件
    {
        Object params = joinPoint.getArgs()[0];
        // → 获取方法的第一个参数（约定为 BaseEntity 或其子类）
        if (StringUtils.isNotNull(params) && params instanceof BaseEntity)
        {
            BaseEntity baseEntity = (BaseEntity) params;
            baseEntity.getParams().put(DATA_SCOPE, " AND (" + sqlString.substring(4) + ")");
            // → 去掉开头的 " OR "，替换为 " AND ("，注入到 params.dataScope
            // → 例如：sqlString = " OR d.dept_id = 1" → " AND (d.dept_id = 1)"
        }
    }
}
// → 如果执行到这里，SQL 过滤条件已注入到参数的 params.dataScope 中，MyBatis XML 通过 ${params.dataScope} 引用

5.c 权限加载

函数：SysPermissionServiceImpl.getMenuPermission()

  • 调用时机：用户登录时加载权限信息
  • 典型调用者：SysLoginService.getUserInfo()
  • 前置条件：用户基本信息已从数据库加载，roles 列表已填充
  • 目的：加载用户拥有的全部权限标识，区分管理员和普通用户
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@Override
public Set<String> getMenuPermission(SysUser user)
// → 获取菜单权限标识集合
{
    Set<String> perms = new HashSet<String>();
    // → 使用 HashSet 自动去重（多角色可能有重复权限）
    // 管理员拥有所有权限
    if (user.isAdmin())
    // → user.isAdmin() 即 userId == 1L
    {
        perms.add(Constants.ALL_PERMISSION);
        // → 添加 "*:*:*"，在 AuthLogic.hasPermi() 中匹配所有权限
    }
    else
    // → 非管理员用户需要按角色查询权限
    {
        List<SysRole> roles = user.getRoles();
        // → 获取用户的角色列表（在 SysLoginService.getUserInfo() 中已加载）
        if (!CollectionUtils.isEmpty(roles))
        // → 如果用户有角色
        {
            // 多角色设置permissions属性，以便数据权限匹配权限
            for (SysRole role : roles)
            // → 遍历每个角色
            {
                if (StringUtils.equals(role.getStatus(), UserConstants.ROLE_NORMAL) && !role.isAdmin())
                // → 只处理正常状态且非管理员的角色
                {
                    Set<String> rolePerms = menuService.selectMenuPermsByRoleId(role.getRoleId());
                    // → 按角色 ID 查询该角色拥有的权限标识
                    role.setPermissions(rolePerms);
                    // → 将权限写回角色对象（后续 DataScopeAspect 数据权限过滤时会用到）
                    perms.addAll(rolePerms);
                    // → 合并到总权限集合
                }
            }
        }
        else
        {
            perms.addAll(menuService.selectMenuPermsByUserId(user.getUserId()));
            // → 用户没有角色时直接按用户 ID 查权限（兼容直接给用户分配权限的场景）
        }
    }
    return perms;
}
// → 如果执行到这里，返回的是用户拥有的所有权限标识，供 AuthLogic 鉴权使用

6. 关键算法剖析

6.1 菜单树递归构建

SysMenuServiceImpl.getChildPerms() 将扁平菜单列表转为树结构：

1
2
3
4
5
6
7
8
算法步骤：
1. 遍历所有菜单，找出 parentId == 目标 parentId 的节点作为第一层
2. 对每个找到的节点，调用 recursionFn() 递归查找其所有子节点
3. recursionFn() 通过 getChildList() 找直接子节点，设置 children 属性
4. 对每个子节点继续递归，直到叶子节点

时间复杂度：O(n²) —— 每个节点都要遍历一次全列表查找子节点
优化空间：可先用 Map<parentId, List<SysMenu>> 建立索引，降至 O(n)

6.2 前端路由构建的分支逻辑

buildMenus() 处理三种菜单类型：

graph TD
    MENU[菜单节点] --> Q1{menuType = DIR
且有children?}
    Q1 -->|是| CASE1[目录路由
alwaysShow=true
递归构建children]
    Q1 -->|否| Q2{isMenuFrame?
一级菜单非外链}
    Q2 -->|是| CASE2[菜单路由
自身包装为子路由
meta设为null]
    Q2 -->|否| Q3{isInnerLink?
顶级内链}
    Q3 -->|是| CASE3[内链路由
path替换特殊字符
component=InnerLink]
    Q3 -->|否| DEFAULT[默认路由]

7. 设计决策分析

为什么 updateUser() 采用”先删后插”策略处理关联表？

updateUser() 中处理用户-角色和用户-岗位关联时，先 delete 再 insert：

1
2
userRoleMapper.deleteUserRoleByUserId(userId);  // 先全部删除
insertUserRole(user);                             // 再重新插入

原因：

  1. 简化差异计算：如果采用”diff 后增删”，需要先查出原有关联、计算新增和删除的差异、分别执行。先删后插只需要两次数据库操作
  2. 事务保证：整个过程在 @Transactional 中，失败自动回滚，不会出现数据不一致
  3. 关联数据量小：一个用户的角色和岗位数量通常很少（< 20），批量插入开销可忽略

为什么数据权限使用 params.dataScope 占位符而非 MyBatis 拦截器？

RuoYi 的数据权限通过 BaseEntity.params 的 dataScope 键传递 SQL 片段，在 MyBatis XML 中通过 ${params.dataScope} 引用。

为什么不用 MyBatis 拦截器？

  1. 灵活性：不同查询可能需要不同的表别名（如 d.dept_id vs dept.dept_id），通过 @DataScope 注解的 deptAlias 参数可灵活指定
  2. 可控性：不是所有查询都需要数据权限过滤，通过注解显式标记更清晰
  3. 调试友好：生成的 SQL 片段可在日志中直接看到，便于排查

为什么 clearDataScope() 在 handleDataScope() 之前调用？

DataScopeAspect.doBefore()：

1
2
clearDataScope(point);   // 先清空
handleDataScope(point, controllerDataScope);  // 再生成

防止 SQL 注入：如果不清空，攻击者可能通过在请求参数中注入 params.dataScope 来拼接恶意 SQL。先清空确保只有 AOP 生成的 SQL 片段才会生效。

8. 学习检查点

📝 本章小结

  1. ruoyi-system 是核心业务模块，管理用户/角色/菜单/部门/字典等，采用标准的三层架构（Controller → Service → Mapper）
  2. 数据权限通过 @DataScope 注解 + DataScopeAspect 实现五级隔离，SQL 片段通过 params.dataScope 注入
  3. SysMenuServiceImpl.buildMenus() 将数据库菜单转为 Vue Router 格式，处理目录/菜单/内链三种分支
  4. 关联表（user_role、user_post、role_menu）采用”先删后插”策略，在事务保护下简化差异计算
  5. 超级管理员（userId=1）在权限和数据范围上都有特殊分支——拥有全部权限和全部数据

🤔 思考题

  1. DataScopeAspect.dataScopeFilter() 中，如果用户同时拥有”全部数据权限”和”本部门数据权限”两个角色，最终的 SQL 条件是什么？

    参考答案

    最终 SQL 为空（不过滤）。代码第 90-95 行：当遇到 DATA_SCOPE_ALL 时，执行 sqlString = new StringBuilder() 清空所有之前拼接的条件，然后 break 跳出循环。这是因为”全部数据权限”是最高级别，其优先级覆盖所有其他级别。所以即使用户也有”本部门”角色，只要有一个角色是”全部数据权限”，就不过滤数据。

  2. SysMenuServiceImpl.checkRouteConfigUnique() 中检查了三种冲突：同级路径冲突、根目录路径冲突、路由名称冲突。如果去掉路由名称的全局唯一约束会有什么问题？

    参考答案

    路由名称（routeName）在 Vue Router 中作为路由的 name 属性，用于编程式导航（router.push({ name: 'User' })）和 <keep-alive> 缓存匹配。如果两个路由的 name 相同，Vue Router 会报警告且编程式导航可能跳转到错误页面。此外，<keep-alive :include="cachedViews"> 依赖 name 来识别缓存组件，同名会导致缓存混乱。因此路由名称的全局唯一性是必需的。

  3. SysPermissionServiceImpl.getMenuPermission() 中，对每个角色的权限查询结果调用 role.setPermissions(rolePerms) 写回角色对象。这个操作是为什么？如果不写回会怎样？

    参考答案

    写回 role.setPermissions() 是为了后续 DataScopeAspect.dataScopeFilter() 中做权限匹配。数据权限过滤时需要判断角色是否包含当前方法的权限字符（StringUtils.containsAny(role.getPermissions(), ...)），如果不写回，这个判断将始终失败，导致该角色的数据权限级别被跳过。这是 LoginUser 中角色对象的权限字段被”懒加载”的一个例子——在登录时一次性填充，避免每次鉴权都查数据库。