RuoYi 阶段一：项目概览与环境搭建

NOTE
本文是 RuoYi 学习路线的阶段一，聚焦项目结构和环境搭建。学完本篇你应该能：

在本地成功运行 RuoYi 项目

理解项目的模块划分和包结构

知道每个配置文件的作用

前端视角：RuoYi 像什么？#

如果把 RuoYi 比作前端项目：

RuoYi	前端类比
`pom.xml`	`package.json`
`src/main/java/com/ruoyi/`	`src/`
`application.yml`	`.env` + `config.js`
`RuoYiApplication.java`	`main.js` / `index.ts`
`sql/ry_20240629.sql`	数据库迁移脚本
Maven	npm / pnpm

项目结构详解#

1
RuoYi/
2
├── src/
3
│   ├── main/
4
│   │   ├── java/com/ruoyi/
5
│   │   │   ├── common/              # 公共模块
6
│   │   │   │   ├── annotation/      # 自定义注解
7
│   │   │   │   ├── config/          # 配置类
8
│   │   │   │   ├── constant/        # 常量定义
9
│   │   │   │   ├── core/            # 核心基类
10
│   │   │   │   ├── enums/           # 枚举类
11
│   │   │   │   ├── exception/       # 异常处理
12
│   │   │   │   ├── filter/          # 过滤器
13
│   │   │   │   └── utils/           # 工具类
14
│   │   │   │
15
│   │   │   ├── framework/           # 框架核心
16
│   │   │   │   ├── aspectj/         # AOP 切面
17
│   │   │   │   ├── config/          # 框架配置
18
│   │   │   │   ├── datasource/      # 数据源配置
19
│   │   │   │   ├── interceptor/     # 拦截器
20
│   │   │   │   ├── shiro/           # Shiro 安全框架
21
│   │   │   │   └── web/             # Web 配置
22
│   │   │   │
23
│   │   │   ├── generator/           # 代码生成器
24
│   │   │   │   ├── controller/      # 生成器 Controller
25
│   │   │   │   ├── domain/          # 生成器实体
26
│   │   │   │   ├── mapper/          # 生成器 Mapper
27
│   │   │   │   ├── service/         # 生成器 Service
28
│   │   │   │   └── util/            # 生成器工具
29
│   │   │   │
30
│   │   │   ├── quartz/              # 定时任务
31
│   │   │   │   ├── controller/      # 任务 Controller
32
│   │   │   │   ├── domain/          # 任务实体
33
│   │   │   │   ├── mapper/          # 任务 Mapper
34
│   │   │   │   ├── service/         # 任务 Service
35
│   │   │   │   └── util/            # 任务工具
36
│   │   │   │
37
│   │   │   ├── system/              # 系统模块（核心业务）
38
│   │   │   │   ├── controller/      # Controller 层
39
│   │   │   │   ├── domain/          # 实体类
40
│   │   │   │   ├── mapper/          # MyBatis Mapper
41
│   │   │   │   └── service/         # Service 层
42
│   │   │   │
43
│   │   │   └── web/                 # Web 层
44
│   │   │       └── controller/      # 公共 Controller
45
│   │   │
46
│   │   └── resources/
47
│   │       ├── mapper/              # MyBatis XML 映射文件
48
│   │       │   ├── generator/       # 代码生成器 Mapper XML
49
│   │       │   ├── quartz/          # 定时任务 Mapper XML
50
│   │       │   └── system/          # 系统模块 Mapper XML
51
│   │       │
52
│   │       ├── static/              # 静态资源
53
│   │       │   ├── ajax/            # Ajax 插件
54
│   │       │   ├── css/             # 样式文件
55
│   │       │   ├── fonts/           # 字体文件
56
│   │       │   ├── img/             # 图片
57
│   │       │   └── js/              # JavaScript
58
│   │       │
59
│   │       ├── templates/           # Thymeleaf 模板
60
│   │       │   ├── error/           # 错误页面
61
│   │       │   ├── include/         # 公共片段
62
│   │       │   ├── index/           # 首页
63
│   │       │   ├── login/           # 登录页
64
│   │       │   ├── monitor/         # 监控页面
65
│   │       │   ├── system/          # 系统管理页面
66
│   │       │   └── tool/            # 工具页面
67
│   │       │
68
│   │       ├── application.yml      # 主配置文件
69
│   │       ├── application-druid.yml # 数据源配置
70
│   │       ├── logback.xml          # 日志配置
71
│   │       └── banner.txt           # 启动 Banner
72
│   │
73
│   └── test/                        # 测试代码
74
│
75
├── sql/                             # 数据库脚本
76
│   ├── ry_20240629.sql              # 主库脚本
77
│   └── quartz.sql                   # 定时任务脚本
78
│
79
├── pom.xml                          # Maven 配置
80
├── README.md                        # 项目说明
81
└── LICENSE                          # 开源协议

Maven 配置 (pom.xml)#

pom.xml 是项目的”package.json”，定义了依赖和构建配置：

1
<!-- pom.xml 核心依赖 -->
2
<dependencies>
3
    <!-- Spring Boot 核心 -->
4
    <dependency>
5
        <groupId>org.springframework.boot</groupId>
6
        <artifactId>spring-boot-starter-web</artifactId>
7
    </dependency>
8

9
    <!-- Spring Boot 测试 -->
10
    <dependency>
11
        <groupId>org.springframework.boot</groupId>
12
        <artifactId>spring-boot-starter-test</artifactId>
13
        <scope>test</scope>
14
    </dependency>
15

16
    <!-- MyBatis -->
17
    <dependency>
18
        <groupId>org.mybatis.spring.boot</groupId>
19
        <artifactId>mybatis-spring-boot-starter</artifactId>
20
        <version>2.3.1</version>
21
    </dependency>
22

23
    <!-- MySQL 驱动 -->
24
    <dependency>
25
        <groupId>com.mysql</groupId>
26
        <artifactId>mysql-connector-j</artifactId>
27
        <scope>runtime</scope>
28
    </dependency>
29

30
    <!-- Druid 连接池 -->
31
    <dependency>
32
        <groupId>com.alibaba</groupId>
33
        <artifactId>druid-spring-boot-starter</artifactId>
34
        <version>1.2.20</version>
35
    </dependency>
36

37
    <!-- Shiro 安全框架 -->
38
    <dependency>
39
        <groupId>org.apache.shiro</groupId>
40
        <artifactId>shiro-spring</artifactId>
41
        <version>1.13.0</version>
42
    </dependency>
43

44
    <!-- Thymeleaf 模板引擎 -->
45
    <dependency>
46
        <groupId>org.springframework.boot</groupId>
47
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
48
    </dependency>
49

50
    <!-- Quartz 定时任务 -->
51
    <dependency>
52
        <groupId>org.quartz-scheduler</groupId>
53
        <artifactId>quartz</artifactId>
54
    </dependency>
55

56
    <!-- 代码生成器模板引擎 -->
57
    <dependency>
58
        <groupId>org.apache.velocity</groupId>
59
        <artifactId>velocity-engine-core</artifactId>
60
        <version>2.3</version>
61
    </dependency>
62
</dependencies>

TIP
Maven 依赖管理对比 npm：

mvn clean install ≈ npm install

mvn spring-boot:run ≈ npm run dev

pom.xml 的 <dependencies> ≈ package.json 的 dependencies

配置文件详解#

application.yml（主配置）#

1
spring:
2
  # 环境配置
3
  profiles:
4
    active: druid
5

6
  # 文件上传限制
7
  servlet:
8
    multipart:
9
      max-file-size: 10MB
10
      max-request-size: 20MB
11

12
  # Thymeleaf 模板引擎
13
  thymeleaf:
14
    mode: HTML
15
    encoding: utf-8
16
    cache: false  # 开发环境关闭缓存
17

18
  # 静态资源
19
  web:
20
    resources:
21
      static-locations: classpath:/static/,classpath:/public/
22

23
# MyBatis 配置
24
mybatis:
25
  typeAliasesPackage: com.ruoyi.**.domain
26
  mapperLocations: classpath:mapper/**/*.xml
27
  configLocation: classpath:mybatis/mybatis-config.xml
28

29
# Shiro 配置
30
shiro:
31
  user:
32
    # 登录地址
33
    loginUrl: /login
34
    # 首页
35
    indexUrl: /index
36
    # 密码错误次数
37
    password:
38
      maxRetryCount: 5
39
      lockTime: 10  # 锁定时间（分钟）
40

41
# 项目相关配置
42
ruoyi:
43
  # 名称
44
  name: RuoYi
45
  # 版本
46
  version: 4.8.3
47
  # 版权年份
48
  copyrightYear: 2024
49
  # 实例演示开关
50
  demoEnabled: true
51
  # 文件路径（上传文件存储位置）
52
  profile: D:/ruoyi/uploadPath
53
  # 获取 IP 地址的 header 键
54
  addressEnabled: false

application-druid.yml（数据源配置）#

1
spring:
2
  datasource:
3
    type: com.alibaba.druid.pool.DruidDataSource
4
    driverClassName: com.mysql.cj.jdbc.Driver
5
    druid:
6
      # 主库数据源
7
      master:
8
        url: jdbc:mysql://localhost:3306/ry?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
9
        username: root
10
        password: your_password
11
      # 从库数据源（可选）
12
      slave:
13
        enabled: false
14
        url:
15
        username:
16
        password:
17
      # 初始连接数
18
      initialSize: 5
19
      # 最小连接池数量
20
      minIdle: 10
21
      # 最大连接池数量
22
      maxActive: 20
23
      # 配置获取连接等待超时的时间
24
      maxWait: 60000
25
      # 配置检测间隔时间
26
      timeBetweenEvictionRunsMillis: 60000
27
      # 配置连接最小生存时间
28
      minEvictableIdleTimeMillis: 300000
29
      # 配置检测连接是否有效
30
      validationQuery: SELECT 1 FROM DUAL
31
      testWhileIdle: true
32
      testOnBorrow: false
33
      testOnReturn: false

启动类#

1
package com.ruoyi;
2

3
import org.springframework.boot.SpringApplication;
4
import org.springframework.boot.autoconfigure.SpringBootApplication;
5
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
6

7
/**
8
 * 启动程序
9
 *
10
 * @author ruoyi
11
 */
12
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
13
public class RuoYiApplication {
14
    public static void main(String[] args) {
15
        SpringApplication.run(RuoYiApplication.class, args);
16
        System.out.println("(♥◠‿◠)ﾉﾞ  RuoYi 启动成功   ლ(´ڡ`ლ)ﾞ");
17
    }
18
}

WARNING
@SpringBootApplication 是一个组合注解，包含：

@SpringBootConfiguration：标注配置类

@EnableAutoConfiguration：启用自动配置

@ComponentScan：组件扫描

exclude = { DataSourceAutoConfiguration.class } 排除了 Spring Boot 默认的数据源配置，因为 RuoYi 使用 Druid 自定义数据源。

数据库脚本导入#

RuoYi 提供了两个 SQL 脚本：

脚本	说明
`sql/ry_20240629.sql`	主库脚本（用户、角色、菜单、部门等表）
`sql/quartz.sql`	定时任务脚本（Quartz 相关表）

导入步骤#

1
# 1. 创建数据库
2
mysql -u root -p
3
CREATE DATABASE ry DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
4
EXIT;
5

6
# 2. 导入主库脚本
7
mysql -u root -p ry < sql/ry_20240629.sql
8

9
# 3. 导入定时任务脚本
10
mysql -u root -p ry < sql/quartz.sql
11

12
# 4. 验证
13
mysql -u root -p
14
USE ry;
15
SHOW TABLES;
16
# 应该看到 sys_user, sys_role, sys_menu, sys_dept 等表

核心数据表#

表名	说明
`sys_user`	用户表
`sys_role`	角色表
`sys_menu`	菜单表
`sys_dept`	部门表
`sys_post`	岗位表
`sys_dict_type`	字典类型表
`sys_dict_data`	字典数据表
`sys_config`	参数配置表
`sys_logininfor`	登录日志表
`sys_oper_log`	操作日志表
`sys_user_role`	用户-角色关联表
`sys_role_menu`	角色-菜单关联表
`sys_role_dept`	角色-部门关联表
`sys_user_post`	用户-岗位关联表

启动与验证#

IDEA 启动#

用 IDEA 打开项目（选择 pom.xml 作为项目导入）
等待 Maven 下载依赖
修改 application-druid.yml 中的数据库密码
运行 RuoYiApplication.java

命令行启动#

1
# 编译项目
2
mvn clean install -DskipTests
3

4
# 启动
5
mvn spring-boot:run
6

7
# 或者打包后运行
8
mvn clean package -DskipTests
9
java -jar target/ruoyi.jar

访问验证#

1
http://localhost:80

默认账号：

用户名：admin
密码：admin123

常见启动问题#

1. 数据库连接失败#

1
Communications link failure

解决：检查 application-druid.yml 中的数据库 URL、用户名、密码。

2. 端口被占用#

1
Port 80 was already in use

解决：修改 application.yml 中的端口，或关闭占用端口的程序。

1
server:
2
  port: 8080  # 改成其他端口

3. Maven 依赖下载慢#

解决：配置阿里云镜像。

1
<mirrors>
2
    <mirror>
3
        <id>aliyunmaven</id>
4
        <mirrorOf>*</mirrorOf>
5
        <name>阿里云公共仓库</name>
6
        <url>https://maven.aliyun.com/repository/public</url>
7
    </mirror>
8
</mirrors>

4. Thymeleaf 模板找不到#

1
Template might not exist or might not be accessible

解决：确保 spring.thymeleaf.cache: false（开发环境），并检查模板路径。

复习卡片#

1
// RuoYi 项目结构记忆口诀
2
// common  - 公共工具
3
// framework - 框架核心
4
// system  - 系统业务
5
// generator - 代码生成
6
// quartz  - 定时任务
7

8
// 启动类关键注解
9
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
10

11
// 配置文件加载顺序
12
// application.yml -> application-{profile}.yml
13

14
// 默认账号
15
// admin / admin123

文件	作用
`pom.xml`	Maven 依赖管理
`application.yml`	主配置文件
`application-druid.yml`	数据源配置
`RuoYiApplication.java`	启动入口
`sql/ry_20240629.sql`	主库脚本
`sql/quartz.sql`	定时任务脚本

TIP
下一步：阶段二：Spring Boot 基础与项目结构
在阶段二中，我们将深入理解 Spring Boot 的自动配置原理，以及 RuoYi 是如何利用 Spring Boot 的特性来简化开发的。