🏛️ RuoYi (若依) v4.8.3 架构学习笔记

📅 创建时间：2026-05-20

🏷️ 标签： Spring Boot 4 Apache Shiro MyBatis Thymeleaf 后台管理系统 代码生成 若依

📍 项目路径：E:\workSpace\RuoYi

🌐 官网：www.ruoyi.vip

RuoYi（若依）是国内最流行的开源 Java 后台管理系统之一，基于 Spring Boot + Shiro + MyBatis + Thymeleaf 构建，提供完整的权限管理、代码生成、系统监控等企业级功能。v4.8.3 版本升级至 Spring Boot 4.0.3 + Java 17，采用 Jakarta EE 命名空间。

UserRealm.doGetAuthorizationInfo() 加载当前用户的角色集合和菜单权限集合，返回 SimpleAuthorizationInfo，Shiro 据此做访问控制。

RuoYi 将 Shiro Session 持久化到 sys_user_online 数据库表，实现：

• 跨实例共享：多节点部署时 Session 一致
• 在线用户监控：管理后台可查看/踢出在线用户
• 设备信息记录：通过 YAUAA 解析 User-Agent，记录浏览器/OS 信息

• 加密方式：MD5 哈希（通过 SysPasswordService）
• 暴力破解防护：最多 5 次失败尝试，锁定 10 分钟（EhCache loginRecordCache 跟踪）
• XSS 防护：全局 XSS 过滤器，覆盖 /system/*, /monitor/*, /tool/*
• SQL 注入防护：SqlUtil 工具类 + Druid WallFilter

RuoYi 采用经典的 服务端渲染 模式，没有独立的前端框架（无 Vue/React/Angular）。前端由 Thymeleaf 模板 + jQuery + Bootstrap 构成，适合后台管理系统的快速开发。

ruoyi-admin/src/main/resources/
├── templates/                    # Thymeleaf 模板
│   ├── system/                   # 系统管理页面
│   │   ├── user/                 #   用户管理
│   │   ├── role/                 #   角色管理
│   │   ├── menu/                 #   菜单管理
│   │   ├── dept/                 #   部门管理
│   │   ├── dict/                 #   字典管理
│   │   ├── config/               #   参数设置
│   │   ├── notice/               #   通知公告
│   │   ├── login.html            #   登录页
│   │   ├── register.html         #   注册页
│   │   └── index.html            #   主框架页
│   ├── monitor/                  # 监控页面
│   │   ├── cache/                #   缓存监控
│   │   ├── server/               #   服务器监控
│   │   ├── online/               #   在线用户
│   │   └── operlog/, logininfor/ #   日志管理
│   ├── tool/                     # 工具页面
│   │   ├── gen/                  #   代码生成
│   │   └── build/                #   表单构建
│   ├── demo/                     # 演示页面
│   └── error/                    # 错误页面 (404, 500)
└── static/
    ├── css/                      # 样式表
    ├── js/                       # jQuery + Bootstrap + 插件
    ├── ajax/                     # AJAX 工具函数
    ├── ruoyi/                    # 若依自定义 JS/CSS
    ├── i18n/                     # 国际化资源
    ├── img/, fonts/              # 图片/字体
    └── file/                     # 上传文件目录

通过 thymeleaf-extras-shiro 在模板中直接做权限判断：

<!-- 有 user:list 权限才显示按钮 -->
<shiro:hasPermission name="system:user:add">
    <button class="btn btn-primary">新增用户</button>
</shiro:hasPermission>

<!-- 有 admin 角色才显示 -->
<shiro:hasRole name="admin">
    <div>管理员专属内容</div>
</shiro:hasRole>

所有 Controller 继承 BaseController，获得统一的分页和响应处理能力：

// AjaxResult - 操作响应
{
  "code": 0,           // 0=成功, 500=失败
  "msg": "操作成功",     // 提示信息
  "data": { ... }      // 可选的业务数据
}

// TableDataInfo - 分页响应
{
  "code": 0,
  "msg": "查询成功",
  "rows": [ ... ],     // 数据列表
  "total": 100          // 总记录数
}

@DataScope 注解 + DataScopeAspect 实现行级数据安全：

• 根据当前用户的部门层级和角色配置，自动向 SQL 追加 WHERE 条件
• 支持"全部数据"、"本部门数据"、"本部门及以下"、"仅本人数据"等粒度
• 通过 MyBatis 拦截器在 SQL 执行前动态注入过滤条件

@DataScope(deptAlias = "d", userAlias = "u")
public List<SysUser> selectUserList(SysUser user) {
    return mapper.selectUserList(user);
}
// 自动追加: AND d.dept_id IN (SELECT dept_id FROM sys_role_dept WHERE role_id = ...)

通过 @DataSource 注解 + DataSourceAspect AOP 实现声明式数据源切换：

@DataSource(value = DataSourceType.SLAVE)
public List<SysUser> selectUserListFromSlave(SysUser user) {
    return mapper.selectUserList(user);
}

底层使用 DynamicDataSource（继承 AbstractRoutingDataSource）+ ThreadLocal 实现运行时切换。从库默认禁用。

配置: 二级缓存启用，useGeneratedKeys，SLF4J 日志，PageHelper MySQL 方言分页。

所有 Controller 位于 ruoyi-admin/src/main/java/com/ruoyi/web/controller/，按功能域组织：

RuoYi 大量使用自定义注解 + AOP 切面实现横切关注点的解耦，是其架构的核心设计亮点：

AsyncManager + AsyncFactory 模式：

• AsyncManager：基于 ScheduledExecutorService 的单线程异步任务管理器
• AsyncFactory：工厂方法创建具体任务（记录登录日志、清理过期 Session 等）
• 用途：耗时操作（日志写入、缓存清理）异步执行，不阻塞主请求

// 使用示例
AsyncManager.me().execute(AsyncFactory.recordLogininfor(
    username, Constants.LOGIN_SUCCESS, MessageUtils.message("user.login.success")
));

-Xms512m -Xmx1024m                           # 堆内存 512M~1G
-XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=512m  # 元空间
-XX:+HeapDumpOnOutOfMemoryError               # OOM 时 dump
-XX:+UseParallelGC -XX:+UseParallelOldGC      # 并行 GC
-Duser.timezone=Asia/Shanghai                 # 时区设置

1. 单体应用的模块化思维

RuoYi 是单体应用，但通过 Maven 多模块实现了清晰的代码分层：common → system → framework → admin。每层职责明确，依赖单向，体现了"单体不等于混乱"的理念。

2. AOP 是框架的灵魂

@Log、@DataScope、@DataSource、@RepeatSubmit 等注解+切面的组合，让业务代码只需关注核心逻辑，横切关注点完全解耦。这是 RuoYi 最值得学习的设计模式。

3. Session-in-DB 的工程价值

将 Session 持久化到数据库，虽然性能不如 Redis，但实现简单、支持跨实例共享、且天然支持在线用户管理。对于中小型项目，这是务实的选择。

4. 代码生成器的深度集成

不是简单的模板脚手架，而是读取真实数据库元数据，生成的代码完全符合项目规范（BaseEntity、@Excel、PageHelper、Thymeleaf 模板），可直接生产使用。

5. 数据权限的行级安全

@DataScope 通过 AOP 自动向 SQL 注入过滤条件，实现行级数据安全。这种"声明式数据权限"比在每个查询中手动加条件优雅得多。

6. 服务端渲染的适用场景

Thymeleaf SSR + jQuery + Bootstrap 的组合虽然"传统"，但对于后台管理系统来说开发效率极高：不需要前端构建工具、不需要 API 文档、前后端一体化部署。

• ShiroConfig 中自定义过滤器链的配置细节
• DataScopeAspect 如何动态向 MyBatis 注入 SQL 条件
• OnlineSessionDAO 的 Session 持久化实现
• KickoutSessionFilter 的并发会话控制算法
• AsyncManager 的异步任务调度机制
• 代码生成器的 14 个 Velocity 模板如何协同工作
• Druid WallFilter 的 SQL 注入防护规则