若依管理系统 RuoYi-Vue-springboot3 源码深度解析 · 总览
⚠️ 本文档基于
RuoYi-Vue-springboot3的源码展开分析，属于教科书式学习笔记，用于理解若依前后端分离框架（Spring Boot 3 分支）的核心原理、模块结构与复刻方法。文中的所有代码摘录均来自真实源码，链接指向仓库内对应行号。
1. 项目简介
RuoYi（若依） 是目前国内使用最广泛的 Java 快速开发平台之一，基于 Spring Boot 3 + Vue 3 + MyBatis + Redis + JWT 的前后端分离架构。本仓库是官方 springboot3 分支（v3.9.2），要求 JDK 17+。
它提供的不是”玩具 demo”，而是一整套可直接接手的后台管理系统骨架，内置了绝大多数管理系统都要重复实现的通用能力：
- 权限体系：用户、角色、菜单三级模型，细化到按钮级权限标识；支持数据权限（按部门/自定义/本部门及下属/仅本人）自动过滤 SQL。
- 认证体系：基于 JWT + Redis 的 Token 认证，无状态、支持 Web / App / 小程序多端接入；30 分钟过期 + 自动续期。
- 系统管理：部门、岗位、字典、参数、通知公告等高频基础模块。
- 运维监控：操作日志、登录日志、在线用户、服务监控（CPU/内存/JVM）、缓存监控、数据源连接池监控。
- 定时任务：内置 Quartz，可视化在线增删改定时任务，支持 Cron 表达式与反射调用。
- 代码生成：内置 Velocity 代码生成器，根据数据库表一键生成
Java / Vue / XML / SQL前后端全套代码。 - 通用能力：Excel 导入导出（POI）、验证码、防重复提交、接口限流、XSS 过滤、IP 黑名单、多数据源动态切换、Swagger 接口文档。
1.1 技术栈速览
| 层次 | 技术选型 |
|---|---|
| 后端框架 | Spring Boot 3.5.16 |
| 安全框架 | Spring Security 6 + JWT(0.9.1) |
| ORM | MyBatis (mybatis-spring-boot 3.0.5) + PageHelper 分页插件 |
| 连接池 | 阿里 Druid 1.2.28（含监控） |
| 缓存 | Spring Data Redis (Lettuce) |
| 数据库 | MySQL（默认） |
| 定时任务 | Quartz |
| 接口文档 | SpringDoc OpenAPI 2.9.0 |
| JSON | Fastjson2 |
| 代码生成 | Apache Velocity 2.3 |
| 系统监控 | oshi-core 7.4.4 |
| Excel | Apache POI 5.5.1 |
| 构建 | Maven 多模块，JDK 17 |
📍 版本与依赖管理见 pom.xml:15-34
1.2 多模块 Maven 结构
顶层 pom.xml 声明了 6 个模块（pom.xml:176-183）：
graph TB
subgraph 启动层
ADMIN[ruoyi-admin
启动入口 + Controller]
end
subgraph 框架层
FRAMEWORK[ruoyi-framework
安全/切面/数据源/配置]
end
subgraph 业务层
SYSTEM[ruoyi-system
用户/角色/菜单等 Service+Mapper]
QUARTZ[ruoyi-quartz
定时任务]
GENERATOR[ruoyi-generator
代码生成]
end
subgraph 基础层
COMMON[ruoyi-common
工具/域对象/注解/异常/Redis]
end
FRAMEWORK --> SYSTEM
FRAMEWORK --> COMMON
SYSTEM --> COMMON
QUARTZ --> COMMON
GENERATOR --> COMMON
ADMIN --> FRAMEWORK
ADMIN --> SYSTEM
ADMIN --> QUARTZ
ADMIN --> GENERATOR
模块职责划分（后面各章展开）：
- ruoyi-admin（24 文件）：
RuoYiApplication启动类 + 全部@RestControllerController + Swagger 配置。 - ruoyi-framework（45 文件）：框架核心——安全认证、AOP 切面、多数据源、拦截器、异步线程池、全局异常、Web 域对象。
- ruoyi-system（56 文件）：业务 service / impl / mapper 接口与 XML。
- ruoyi-common（110 文件）：通用工具、领域实体、注解、常量、枚举、异常、分页模型、Redis 封装。
- ruoyi-quartz（18 文件）：定时任务动态调度。
- ruoyi-generator（13 文件）：代码生成器 + Velocity 模板。
2. 核心概念速览
2.1 认证：Token（JWT 只做身份载体，真正状态在 Redis）
这是若依最容易被误解的一点。JWT 仅仅是”登录凭证的载体”，Token 里存的是 uuid（随机串），真正的用户状态 LoginUser 存在 Redis 里，key 为 login_tokens:<uuid>。
sequenceDiagram
participant C as 前端
participant F as JwtAuthenticationTokenFilter
participant T as TokenService
participant R as Redis
C->>F: 请求头 Authorization: Bearer
F->>T: getLoginUser(request)
T->>T: parseToken 解析出 uuid
T->>R: redis GET login_tokens:
R-->>T: LoginUser 对象（含用户+权限+过期时间）
T-->>F: LoginUser（校验通过）
F->>F: 写入 SecurityContext
F->>C: 放行 chain.doFilter
LoginUser实现UserDetails，是认证的核心域对象，序列化存入 Redis（01 章）。- Token 有效期 30 分钟，距过期不足 20 分钟时自动续期（滑动过期）。
- 由于用户状态在 Redis，注销、改权限、踢人都能立即生效——这是纯 JWT 做不到的（详见 02 章）。
2.2 权限：两级模型
- 认证（Authentication）：你是谁？= 登录。
- 授权（Authorization）：你能做什么？= 权限字符串
system:user:list之类。
授权分两层：
- 菜单权限（按钮级）：
@SaCheckPermission/ 自定义@ss.hasPermi('xxx')，判断LoginUser.getPermissions()这个Set<String>是否包含权限字符串。 - 数据权限（行级）：
@DataScope注解配合 AOP，在查询前根据角色data_scope自动拼AND (...)到 SQL，实现对”不同人看到不同部门数据”的过滤。超级管理员（userId==1）不受数据权限限制。
2.3 关键机制枚举
| 机制 | 注解 | 切面/处理器 | 作用 |
|---|---|---|---|
| 操作日志 | @Log |
LogAspect |
AOP 记录请求/响应到 sys_oper_log |
| 数据权限 | @DataScope |
DataScopeAspect |
AOP 拼数据过滤 SQL |
| 多数据源 | @DataSource |
DataSourceAspect |
动态切换 Druid 数据源 |
| 接口限流 | @RateLimiter |
RateLimiterAspect |
Redis Lua 脚本计数器限流 |
| 防重复提交 | @RepeatSubmit |
RepeatSubmitInterceptor |
拦截器+Redis |
| 匿名访问 | @Anonymous |
PermitAllUrlProperties |
放行指定路径 |
| 敏感字段 | @Sensitive |
SensitiveJsonSerializer |
JSON 序列化脱敏 |
3. 典型场景剖析：一次完整登录
以管理员 admin 登录为例，追踪整条链路（完整源码见 02 章）：
sequenceDiagram
participant C as "前端/POST /login"
participant LC as SysLoginController
participant LS as SysLoginService
participant AM as AuthenticationManager
participant UD as UserDetailsServiceImpl
participant PS as SysPasswordService
participant R as Redis
participant T as TokenService
LC->>LS: login(userName, password, code, uuid)
LS->>R: 校验验证码（get + delete）
LS->>LS: loginPreCheck（长度/黑名单）
LS->>AM: authenticate(token)
AM->>UD: loadUserByUsername
UD->>UD: 查询用户 + 状态校验 + SysPasswordService.validate（次数锁定）
UD->>PS: validate(user)
PS-->>UD: 密码匹配，清错误计数
UD-->>AM: LoginUser（含权限 Set）
AM-->>LS: Authentication
LS->>R: 异步记录登录日志
LS->>T: createToken(loginUser)
T->>T: uuid = fastUUID()，refreshToken
T->>R: 缓存 login_tokens:uuid = LoginUser，TTL 30min
T-->>LS: token
LS-->>LC: token
LC-->>C: 返回 {"token": "...", "msg":"操作成功"}
关键点：
SysLoginService.login首先校验验证码（从 Redis 读取并删除，一次性）。authenticationManager.authenticate是 Spring Security 的入口，会触发UserDetailsServiceImpl.loadUserByUsername。- 密码校验走
SysPasswordService：Redis 里记错误次数，连续错 5 次锁定 10 分钟（application.yml:41-46）。 - 成功后
TokenService.createToken：随机uuid作为 JWT 载荷 + Redis key，LoginUser序列化进 Redis。 - 登录日志用
AsyncManager异步写入，不阻塞主流程。 - 前端随后调用
/getInfo拿用户信息 + 角色 + 权限集合，/getRouters拿动态菜单路由。
4. 架构全景图
4.1 请求生命周期
flowchart LR
REQ[HTTP 请求] --> CORS[CorsFilter 跨域]
CORS --> XSS[XssFilter
common 过滤器链]
XSS --> REF[RefererFilter 防盗链]
REF --> JWT[JwtAuthenticationTokenFilter
解析 Token 放 SecurityContext]
JWT --> CTL[Controller]
CTL --> ASP[AOP 切面
@Log/@DataScope/@DataSource/@RateLimiter]
ASP --> SVC[Service 业务层]
SVC --> MAP[Mapper + XML]
MAP --> DB[(MySQL/Druid)]
CTL --> ERR[GlobalExceptionHandler
统一异常->AjaxResult]
ERR --> REQ
4.2 认证与授权子系统总览
graph TB
subgraph 认证链路
LC[SysLoginController] --> LS[SysLoginService]
LS --> AM[AuthenticationManager]
AM --> UD[UserDetailsServiceImpl]
UD --> PS[SysPasswordService]
UD --> SPE[SysPermissionService
loadUserByUsername 时组装权限]
LS --> TS[TokenService]
TS --> REDIS[(Redis)]
JWT[JwtAuthenticationTokenFilter] --> TS
end
subgraph 授权链路
SS[PermissionService @ss] --> SC[SecurityUtils
读 SecurityContext]
DS[DataScopeAspect] --> SC
SC --> LC2[LoginUser]
end
4.3 缓存布局（Redis Key 设计）
| Key 前缀 | 用途 | TTL |
|---|---|---|
login_tokens: |
登录用户 LoginUser 对象 |
30 分钟（滑动续期） |
captcha_codes: |
图形验证码 | 2 分钟 |
pwd_err_cnt: |
登录密码错误次数 | 10 分钟 |
sys_dict: |
字典缓存 | 长期 |
repeat_submit: |
防重复提交标记 | 由注解决定 |
rate_limit: |
接口限流计数 | 由注解决定 |
常量定义见 CacheConstants.java（01 章）。
5. 学习路线图
按”从外到内、从用到建”的顺序学习：
| 顺序 | 章节 | 你将理解 |
|---|---|---|
| 1 | 00 本总览 | 项目全貌与核心概念 |
| 2 | 01 通用模块 | 响应体、域对象、注解、异常、工具、Redis、分页 5 件套 |
| 3 | 02 框架·安全认证 | 登录、JWT+Redis、权限、数据权限 |
| 4 | 03 框架·Web 层 | 多数据源、AOP、限流、异常、过滤器 |
| 5 | 04 启动与 Web 出入口 | Controller 分层、启动、Swagger |
| 6 | 05 系统业务模块 | 用户/角色/菜单/部门/字典等业务实现 |
| 7 | 06 定时任务 | Quartz 动态调度的生命周期与反射 |
| 8 | 07 代码生成 | Velocity 表→代码流水线 |
| 9 | 08 搭建与复刻 | 从零搭建、配置、部署、二次开发复刻 |
💡 建议学完 02、03 后再回头重读 01 的工具类，你会更清楚每个工具被谁调用。
6. 章节间交叉索引
- 认证域对象 LoginUser 被 02 章认证链路 广泛使用。
- @DataScope 注解 由 DataScopeAspect 消费。
- RedisCache 是整个系统的缓存底座，所有模块都在用。
- AjaxResult 是全局统一的返回格式，GlobalExceptionHandler 也用它。