学习笔记若依单体 源码分析

模块深度解析 · 启动与 Web 入口层（ruoyi-admin）

📍 核心源码在 ruoyi-admin/src/main/java/com/ruoyi/。这是最薄的聚合层：不直接写业务逻辑，只负责「启动应用 + 装配 Controller + 收口 Web 增强配置」。「业务接口 + 实现」实际都在 05 章 ruoyi-system 与 ruoyi-framework 里。

1. 模块概述

ruoyi-admin 的定位是运行时壳（Runtime Shell），讲清楚一件事：jbjx 项目能跑起来、能对外提供 Web 服务，靠的是这个模块。

内容 文件/包 说明
启动类 RuoYiApplication @SpringBootApplication，由它拉起整个 Spring 容器
启动辅助 RuoYiServletInitializer 传统 war 打包时用（本项目默认 jar）
通用控制器 web/controller/common/* 验证码、文件上传下载
系统控制器 web/controller/system/* 登录、用户、角色、菜单、部门、字典、配置、通知、岗位、个人中心、首页等
监控控制器 web/controller/monitor/* 缓存、服务器、登录日志、操作日志、在线用户
工具控制器 web/controller/tool/* Swagger 测试对话框
增强配置 web/core/config/SwaggerConfig 接口文档 
graph TB
    RuoYiApplication[启动类 RuoYiApplication] --> CTX[Spring Web 容器]
    CTX --> SCH[SecurityConfig
安全过滤链]
    CTX --> CTL[Controller 层
web/controller]
    CTL --> SVC[ruoyi-system 业务 Service]
    CTL --> REDIS[RedisCache]
    CTX --> SWAGGER[SwaggerConfig 接口文档]

📌 核心事实：ruoyi-admin 里 Controller 只是「薄薄的转译层」，真正逻辑全在下层模块。这也是若依分层的精髓——controller 看不懂业务，业务在 service，数据在 mapper。

2. 启动原理：@SpringBootApplication 与组件扫描

1
2
3
4
5
6
7
8
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class RuoYiApplication
{
    public static void main(String[] args)
    {
        SpringApplication.run(RuoYiApplication.class, args);
    }
}

逐行解析（对应真实源码 RuoYiApplication.java:12-29）：

  • @SpringBootApplication 是一个组合注解，等于：
    • @Configuration：声明启动类本身是配置类；
    • @EnableAutoConfiguration：开启 Spring Boot 自动装配；
    • @ComponentScan：默认扫描启动类所在包及子包。危险点：RuoYiApplication 在 com.ruoyi 包，故能扫到 com.ruoyi.web.*、com.ruoyi.framework.*、com.ruoyi.system.*、com.ruoyi.quartz.*、com.ruoyi.generator.* 的所有 @Component/@Service/@Config 组件——这正是「分模块协作却能一键启动」的根本原因。
  • exclude = { DataSourceAutoConfiguration.class }：排除 Boot 默认数据源自动配置。因为若依用 Druid + 自建 DataSource bean（DruidDataSourceConfig 定义在 framework 里），若不禁用默认自装配，会与自定义数据源冲突导致循环/双数据源。

⚠️ 若启动后控制台未打印「若依启动成功」ASCII 大图，多半是启动线程被中间件连接阻塞或端口占用。

3. 控制器分类图谱

graph LR
    subgraph common 通用
        CAP[CaptchaController
验证码图片]
        COM[CommonController
文件上传/下载/通用下载]
    end
    subgraph system 系统
        LOGIN[SysLoginController 登录]
        IDX[SysIndexController 首页/解锁]
        REG[SysRegisterController 注册]
        SYSUSER[SysUserController 用户]
        SYSROLE[SysRoleController 角色]
        SYSMENU[SysMenuController 菜单]
        DEPT[SysDeptController 部门]
        DICT[SysDictData/TypeController 字典]
        CFG[SysConfigController 参数]
        NOTICE[SysNoticeController 通知]
        POST[SysPostController 岗位]
        PRO[SysProfileController 个人中心]
    end
    subgraph monitor 监控
        MCACHE[CacheController 缓存]
        MSRV[ServerController 服务器]
        MLOGIN[SysLogininforController 登录日志]
        MOPER[SysOperlogController 操作日志]
        MONL[SysUserOnlineController 在线用户]
    end
    subgraph tool 工具
        TEST[TestController 接口测试]
    end

几个 Controller 命名规律：SysXxxController = 系统功能控制器；SysLogininforController = 登录日志（mathscrinfor = 登录信息）；SysOperlogController = 操作日志（operlog = 操作日志）；SysUserOnlineController = 在线用户（Quartz 滑屏维护）。

4. 关键控制器逐行精讲

4.a + 4.b：CaptchaController.getCode（验证码签发）

函数：CaptchaController.getCode

  • 调用时机：前端打开登录页时 GET /captchaImage
  • 典型调用者：登录页脚本
  • 前置条件：Redis 可达；已配置 captchaEnabled
  • 目的：生成图形/数学验证码，把正确答案存 Redis，把图片转 Base64 返回
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
@GetMapping("/captchaImage")
public AjaxResult getCode(HttpServletResponse response) throws IOException
// → 返回 AjaxResult：正常时包含 uuid + base64图片 + captchaEnabled
{
    AjaxResult ajax = AjaxResult.success();
    boolean captchaEnabled = configService.selectCaptchaEnabled();
    // → 从系统参数表读取 sys.account.captchaEnabled（是否开验证码）
    ajax.put("captchaEnabled", captchaEnabled);
    if (!captchaEnabled) return ajax;
    // → 若关闭验证码则直接返回，前端跳过滑块/拼图

    String uuid = IdUtils.simpleUUID();
    // → 每次生成唯一 uuid，与图片绑定
    String verifyKey = CacheConstants.CAPTCHA_CODE_KEY + uuid;
    // → key = captcha_codes:<uuid>

    String captchaType = RuoYiConfig.getCaptchaType();
    if ("math".equals(captchaType))
    {
        // → math 模式：生成"算式"，图片显示算式，code 存答案
        String capText = captchaProducerMath.createText();
        capStr = capText.substring(0, capText.lastIndexOf("@"));
        // → 图片展示部分（如 1+2=?）
        code = capText.substring(capText.lastIndexOf("@") + 1);
        // → 答案部分（如 3）
    }
    else if ("char".equals(captchaType))
    {
        // → char 模式：图片和 code 都是随机字符，防 OCR
        capStr = code = captchaProducer.createText();
    }

    redisCache.setCacheObject(verifyKey, code, Constants.CAPTCHA_EXPIRATION, TimeUnit.MINUTES);
    // → 把正确答案存 Redis，TTL = 2 分钟
    ImageIO.write(image, "jpg", os);
    // → 图片转字节流
    ajax.put("uuid", uuid);
    ajax.put("img", Base64.encode(os.toByteArray()));
    // → 返回 uuid + base64图片数据
    return ajax;
}

📍 源码：CaptchaController.java:45-93

关键点：uuid 回传前端 → 前端 POST 登录时带上 uuid → 02 章 SysLoginService.validateCaptcha 用同一 key 从 Redis 取出答案校验并删除。答案只存 Redis 不落库，一次性使用防复用。

4.b：SysIndexController.unlockScreen（锁屏解锁校密）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@PostMapping("/unlockscreen")
public AjaxResult unlockScreen(@RequestBody Map<String, String> body)
// → 前端锁屏后输入密码解锁
{
    String password = body.get("password");
    if (StringUtils.isEmpty(password)) return AjaxResult.error("密码不能为空");
    String username = SecurityUtils.getUsername();
    // → 从当前登录态取用户名（不重新登录，只校密）
    SysUser user = userService.selectUserByUserName(username);
    if (user == null) return AjaxResult.error("服务器超时，请重新登录");
    if (!SecurityUtils.matchesPassword(password, user.getPassword()))
    // → BCrypt 比对明文密码与库中哈希
        return AjaxResult.error("密码错误，请重新输入");
    return AjaxResult.success("解锁成功");
    // → 只比对不签发 token，前端继续用旧 token
}

📍 源码：SysIndexController.java:43-63

与完整登录区别：不重建 token、不写 Redis 会话，仅「验密放行」，开销极小。

5. SwaggerConfig（接口文档）

ruoyi-web/core/config/SwaggerConfig.java 用 SpringDoc OpenAPI 装配接口文档，供 ruoyi-ui 的 Swagger 地址（默认 /swagger-ui/index.html）访问题目与分组描述。

6. 学习检查点

📝 本章小结

  1. ruoyi-admin 是聚合壳：靠 @SpringBootApplication 的包扫描把 com.ruoyi.* 全部子模块组件收进同一个容器。
  2. exclude DataSourceAutoConfiguration 解决「Boot 默认数据源与自定义 Druid 数据源」的冲突。
  3. 所有控制器只做「HTTP 转译」，业务在 ruoyi-system 的 Service；CaptchaImage 是「Redis 一次性验密」的标准示范。
  4. 控制器命名高度规律化：SysXxx 系统功能 / monitor 监控 / common 通用。

🤔 思考题

  1. 为什么必须 exclude DataSourceAutoConfiguration？

    参考答案

    Boot 的 DataSourceAutoConfiguration 会尝试用 spring.datasource.* 自动装配一个数据源；而若依用 DruidDataSourceConfig 自建 DataSource，两者都会创建 DataSource bean 引发循环依赖或覆盖。排除默认自装配后，只保留自定义 Druid 数据源（Spring Boot 3 后续版本的 @Configuration bean，定义于 ruoyi-framework 的 DruidDataSourceConfig）。

  2. 验证码答案为什么不直接存数据库，而是存 Redis 且设 2 分钟 TTL？

    参考答案

    验证码是「一次性、超短生命周期、高频创建」的临时数据：存 DB 会拖慢每次登录并残留垃圾；存 Redis 天然带 TTL 自动过期，配合 getCacheObject 后 deleteObject 实现「用了即删、未用自动消失」，并用 uuid 作为 key 保证多用户并发不串号（CaptchaController → SysLoginService.validateCaptcha 读取删除）。

交叉引用