项目概述

1.1 项目背景与定位

本项目基于 若依（RuoYi） 管理系统构建，若依是一款广受欢迎的开源企业级后台管理系统框架。它基于 Spring Boot 生态，提供了开箱即用的权限管理、用户管理、部门管理、日志监控等一系列后台核心功能，能够帮助开发者快速搭建企业级 Web 应用。

项目基本信息

属性	值
项目名称	RuoYi 管理系统
当前版本	3.9.2
项目描述	用于管理集团旗下公司的人员信息，具体包括 XXX、XXX 模块
开发语言	Java 17
构建工具	Maven
打包方式	JAR（内嵌 Tomcat）

1.2 技术栈介绍

本项目整合了业界主流且成熟的技术组件，确保系统的稳定性与可维护性。

1.2.1 核心框架

技术	版本	说明
Spring Boot	4.1.0	核心框架，提供自动配置、起步依赖、内嵌服务器
MyBatis	4.1.0（Starter）	ORM 持久层框架，灵活的 SQL 映射
Spring Security	---（随 Boot）	认证与授权框架，支撑权限体系

1.2.2 数据库与缓存

技术	版本	说明
Druid	1.2.28	阿里巴巴数据库连接池，内置监控统计
MySQL	---	主数据库（mysql-connector-j）
Redis	---	缓存中间件，用于会话、字典等数据缓存

1.2.3 工具与辅助

技术	版本	说明
PageHelper	4.1.1	分页插件，自动拦截 SQL 实现物理分页
Apache POI	5.5.1	Excel 导入导出工具
Fastjson2	2.0.64	阿里巴巴 JSON 解析器
JJWT	0.9.1	JWT（JSON Web Token）生成与解析
Kaptcha	2.3.3	验证码生成组件
SpringDoc OpenAPI	3.1.0	Swagger/OpenAPI 3 接口文档生成
Oshi	7.4.4	服务器硬件与操作系统监控
Commons IO	2.22.0	通用 IO 操作工具包
Velocity	2.3	模板引擎，用于代码生成器

1.3 项目模块划分

项目采用 Maven 多模块 架构，通过父 POM 统一管理依赖版本，各模块职责清晰、松耦合。

模块依赖关系

perl 复制代码

ruoyi（父工程）
├── ruoyi-common     ← 通用工具、基础类、异常、注解
├── ruoyi-framework  ← 框架核心（安全、数据源、过滤器等）
├── ruoyi-system     ← 系统业务层（Service、Mapper 等）
├── ruoyi-quartz     ← 定时任务模块
├── ruoyi-generator  ← 代码生成器
└── ruoyi-admin      ← Web 入口层（Controller、配置）

各模块职责说明

① ruoyi-common --- 通用模块

提供项目全局使用的公共组件，包括：

自定义注解 ：@Log（操作日志）、@DataScope（数据权限）、@RateLimiter（限流）、@RepeatSubmit（防重复提交）、@Sensitive（数据脱敏）等
基础类 ：BaseController（控制器基类）、BaseEntity（实体基类）、TreeEntity（树形实体）
统一响应体 ：AjaxResult、R、TableDataInfo（分页表格响应）
工具类：字符串处理、日期处理、Excel 工具、文件上传、IP 地址、HTML 过滤等
异常体系 ：ServiceException、GlobalException、用户/验证码/文件相关异常
枚举类：业务状态、操作类型、数据源类型等

② ruoyi-framework --- 框架核心模块

封装了若依框架的核心能力：

Spring Security 安全配置
多数据源 动态切换（Druid）
全局异常处理
过滤器链（XSS 防护、防重复读取、Referer 校验）
Redis 缓存配置
AOP 切面（日志记录、数据权限、限流等）

③ ruoyi-system --- 系统业务模块

承载所有系统管理业务逻辑，包括：

用户管理（SysUser）
角色管理（SysRole）
菜单管理（SysMenu）
部门管理（SysDept）
岗位管理（SysPost）
字典管理（SysDictType / SysDictData）
参数配置（SysConfig）
通知公告（SysNotice）
操作日志（SysOperLog）
登录日志（SysLogininfor）

④ ruoyi-admin --- Web 入口层

作为整个应用的 唯一入口模块，负责：

RuoYiApplication.java：Spring Boot 启动类
RuoYiServletInitializer.java：支持外部 Web 容器部署
Controller 层：各模块 RESTful API 接口
核心配置 ：Swagger 文档配置（SwaggerConfig.java）
资源文件 ：application.yml、application-druid.yml、logback.xml 等

⑤ ruoyi-quartz --- 定时任务模块

基于 Quartz 的定时任务调度管理，支持：

在线 CRUD 定时任务
Cron 表达式配置
任务执行日志记录
暂停/恢复/立即执行

⑥ ruoyi-generator --- 代码生成器

根据数据库表结构自动生成代码：

支持生成 Controller、Service、Mapper、Entity
支持生成前端 Vue 页面代码
Velocity 模板驱动，可自定义模板

1.4 系统功能清单

1.4.1 系统管理

功能模块	Controller	功能说明
用户管理	`SysUserController`	用户增删改查、状态管理、重置密码、分配角色
角色管理	`SysRoleController`	角色增删改查、分配菜单权限、分配数据权限
菜单管理	`SysMenuController`	菜单树管理、按钮权限管理
部门管理	`SysDeptController`	组织架构树形管理
岗位管理	`SysPostController`	岗位字典管理、用户与岗位关联
字典管理	`SysDictTypeController`	字典类型维护
字典数据	`SysDictDataController`	字典数据维护
参数配置	`SysConfigController`	系统参数键值对管理
通知公告	`SysNoticeController`	系统公告发布与查看

1.4.2 系统监控

功能模块	Controller	功能说明
在线用户	`SysUserOnlineController`	查看当前在线用户、强退
操作日志	`SysOperlogController`	操作日志查询、删除、清空
登录日志	`SysLogininforController`	登录日志查询、删除、清空
服务监控	`ServerController`	服务器 CPU、内存、磁盘等实时信息
缓存监控	`CacheController`	Redis 缓存信息查看与管理

1.4.3 公共接口

功能模块	Controller	功能说明
用户登录	`SysLoginController`	登录认证，返回 JWT Token
用户注册	`SysRegisterController`	新用户注册
个人信息	`SysProfileController`	修改密码、更新个人信息、头像上传
验证码	`CaptchaController`	生成图形/数学验证码
通用接口	`CommonController`	文件上传下载、通用配置获取
首页	`SysIndexController`	系统首页数据统计

1.5 核心设计理念

1.5.1 权限控制模型

项目采用 RBAC（基于角色的访问控制） 模型：

markdown 复制代码

用户（SysUser）
  └── 角色（SysRole）
        └── 菜单权限（SysMenu）
              ├── 目录（M）
              ├── 菜单（C）
              └── 按钮（F）

权限标识 格式为 模块:功能:操作，例如 system:config:list
通过 @PreAuthorize("@ss.hasPermi('system:config:list')") 注解声明接口所需权限
Spring Security + JWT Token 实现无状态认证

1.5.2 统一响应结构

所有 API 返回统一的 JSON 结构：

单条数据 ：AjaxResult（包含 code、msg、data）
分页数据 ：TableDataInfo（包含 code、msg、rows、total）
通用返回 ：R（更简洁的统一返回对象）

1.5.3 代码分层架构

markdown 复制代码

Controller（接口层）
    │ 接收 HTTP 请求，参数校验，调用 Service
    ▼
Service（业务层）
    │ 业务逻辑处理，事务管理
    ▼
Mapper（持久层）
    │ MyBatis XML 映射，数据库交互
    ▼
Database（数据库）

这种分层设计使得各层职责清晰，便于维护和扩展。

下一章我们将进入 环境搭建，手把手带你从零开始运行本项目。