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

若依微服务系统（RuoYi-Cloud）学习文档

1. 项目简介

RuoYi-Cloud 是若依（RuoYi）系列中的 微服务版本，基于 Spring Cloud & Alibaba 全家桶构建的企业级快速开发平台。项目版本为 v3.6.8，采用 JDK 17 + Spring Boot 4.0 + Spring Cloud 2025.1.1 + Spring Cloud Alibaba 2025.1.0.0。

核心特性

特性 实现方式
服务治理 Nacos 注册中心 + 配置中心
网关路由 Spring Cloud Gateway + Sentinel 熔断
认证授权 JWT + Redis 双令牌 + Spring AOP 注解鉴权
数据权限 自定义 @DataScope 注解，基于 AOP 实现五级数据隔离
操作日志 @Log 注解 + AOP，异步入库
代码生成 Velocity 模板引擎，支持单表/树表/主子表
定时任务 Quartz 集群调度，支持并发控制
文件存储 支持本地存储 + Minio 对象存储
服务调用 OpenFeign + 请求头自动传递

2. 核心概念速览

2.1 双令牌认证机制

若依的认证体系采用 JWT + Redis 组合策略：

  • JWT 作为客户端持有的令牌，包含 user_key（UUID）、user_id、username 三个声明
  • Redis 以 user_key 为键存储完整的 LoginUser 对象（含角色、权限列表）
  • 网关 AuthFilter 先解析 JWT 获取 user_key，再查 Redis 验证登录状态

这样设计的好处是：JWT 无状态、适合分布式传递；Redis 提供集中式的登录状态控制和即时失效能力。

2.2 请求链路中的身份传递

1
2
3
4
5
6
7
8
客户端 → Gateway(AuthFilter) → Auth服务 → System服务 → 数据库
         │                        │
         ├─ JWT解析               ├─ Feign拦截器
         ├─ Redis验证              │  自动传递请求头
         └─ 请求头注入             └─ HeaderInterceptor
              user_id                 从请求头恢复用户上下文
              username
              user_key

2.3 AOP 三层切面体系

若依通过三个 AOP 切面实现了横切关注点的优雅分离：

切面 注解 触发时机 职责
PreAuthorizeAspect @RequiresPermissions / @RequiresRoles / @RequiresLogin 方法执行前 基于注解的权限校验
DataScopeAspect @DataScope 方法执行前 动态拼接数据权限 SQL
LogAspect @Log 方法执行后 操作日志记录，异步入库

2.4 数据权限五级模型

1
2
3
4
5
全部数据权限 (DATA_SCOPE_ALL)
    └── 自定义数据权限 (DATA_SCOPE_CUSTOM)
        └── 部门数据权限 (DATA_SCOPE_DEPT)
            └── 部门及以下数据权限 (DATA_SCOPE_DEPT_AND_CHILD)
                └── 仅本人数据权限 (DATA_SCOPE_SELF)

数据权限通过 DataScopeAspect.dataScopeFilter() 方法动态生成 SQL WHERE 子句，注入到 BaseEntity 的 params.dataScope 字段中。

3. 典型场景剖析

场景一：用户登录全链路

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
用户输入用户名/密码
        │
        ▼
┌──────────────────┐
│  Gateway         │  绕过白名单，直接转发到 Auth 服务
│  (ValidateCodeFilter)│
└──────────────────┘
        │
        ▼
┌──────────────────┐
│  Auth 服务        │
│  TokenController  │  POST /login
│    ↓              │
│  SysLoginService  │  1. 参数校验（长度/范围）
│    .login()       │  2. IP黑名单检查
│                   │  3. Feign 调用 System 服务查询用户
│                   │  4. 密码校验（BCrypt）
│                   │  5. 用户状态校验（删除/停用）
│    ↓              │
│  TokenService     │  6. 生成 UUID 作为 user_key
│    .createToken() │  7. 构建 JWT (user_key, user_id, username)
│                   │  8. LoginUser 存入 Redis（过期时间可配）
│                   │  9. 返回 JWT 给客户端
└──────────────────┘
        │
        ▼
┌──────────────────┐
│  后续请求         │
│  Gateway          │  AuthFilter 从 Header 取 JWT
│  AuthFilter       │  → 解析 JWT → 查 Redis → 注入请求头
└──────────────────┘

场景二：带数据权限的用户列表查询

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Controller: SysUserController.list()
    │  @DataScope(deptAlias = "d", userAlias = "u")
    ▼
AOP: DataScopeAspect.doBefore()
    │  1. 获取当前登录用户
    │  2. 超级管理员 → 跳过过滤
    │  3. 遍历用户角色，按数据权限级别拼 SQL
    ▼
SQL 注入: BaseEntity.params.dataScope
    │  "AND (d.dept_id = 1 OR d.dept_id IN (SELECT ...))"
    ▼
MyBatis Mapper: selectUserList()
    │  ${params.dataScope} 占位符被替换
    ▼
返回过滤后的用户列表

4. 架构全景图

graph TB
    subgraph 客户端
        UI[ruoyi-ui
Vue前端]
    end

    subgraph 网关层
        GW[ruoyi-gateway
Spring Cloud Gateway]
        GW --> AF[AuthFilter
JWT鉴权]
        GW --> VF[ValidateCodeFilter
验证码]
        GW --> XF[XssFilter
XSS防护]
    end

    subgraph 认证层
        AUTH[ruoyi-auth
登录/注册/Token]
    end

    subgraph 业务层
        SYS[ruoyi-system
用户/角色/菜单/部门]
        GEN[ruoyi-gen
代码生成]
        JOB[ruoyi-job
定时任务]
        FILE[ruoyi-file
文件管理]
    end

    subgraph 基础设施
        NACOS[Nacos
注册/配置中心]
        REDIS[(Redis
缓存/Token)]
        MYSQL[(MySQL
业务数据)]
        MINIO[(Minio
文件存储)]
        SENTINEL[Sentinel
流量控制]
    end

    subgraph 监控
        MONITOR[ruoyi-monitor
Spring Boot Admin]
    end

    UI --> GW
    GW --> AUTH
    GW --> SYS
    GW --> GEN
    GW --> JOB
    GW --> FILE
    AUTH --> SYS
    SYS --> MYSQL
    SYS --> REDIS
    GEN --> MYSQL
    JOB --> MYSQL
    FILE --> MINIO
    GW --> NACOS
    AUTH --> NACOS
    SYS --> NACOS
    MONITOR --> SYS
    MONITOR --> GEN
    MONITOR --> JOB

5. 学习路线图

建议按以下顺序学习本项目：

步骤 章节 内容 预计时间
1 微服务架构 微服务架构与基础设施 30min
2 认证授权体系 认证授权体系（JWT + Redis + AOP） 60min
3 网关模块 网关模块（过滤器链、验证码、限流） 45min
4 系统管理模块 系统管理模块（用户、角色、菜单、数据权限） 90min
5 公共模块 公共模块（核心工具、Redis、日志、安全） 60min
6 业务支撑模块 业务支撑模块（代码生成、定时任务、文件管理） 45min
7 参考资料索引 参考资料索引 10min

学习建议

  1. 先理解架构再深入细节：建议从 微服务架构 开始，了解整体技术栈和服务拓扑
  2. 安全体系是核心：认证授权体系 和 网关模块 是整个系统的入口，理解认证流程后才能理解业务模块
  3. 带着问题看源码：每章末尾都有思考题，建议先尝试回答再看参考答案
  4. 动手实践：建议拉取项目本地运行，通过 Debug 追踪请求链路

📝 本章小结

  1. RuoYi-Cloud 是 Spring Cloud 微服务架构的企业级快速开发平台，v3.6.8 采用最新的 Spring Boot 4.0 + JDK 17 技术栈
  2. 认证体系采用 JWT + Redis 双令牌机制，兼顾无状态传递和集中式状态管理
  3. 通过三个 AOP 切面实现了权限校验、数据隔离、操作日志的横切关注点分离
  4. 数据权限支持全部/自定义/部门/部门及以下/仅本人五级隔离
  5. 服务间通过 Feign + 请求头拦截器自动传递用户身份信息