第一章. 若依极速搭建

在本章中，我们将像搭建乐高一样，遵循清晰的步骤，快速构建起我们的开发环境：

1. 首先，我们将明确要使用的 若依版本，确保我们站在现代技术的最前沿。
2. 接着，我们会校验并准备好所有必需的 开发环境，这是保证项目顺利运行的前提。
3. 然后，我们将一步步 启动后端服务，包括克隆代码、初始化数据库和修改配置。
4. 最后，我们将 启动前端服务，并完成首次登录，亲眼见证我们的工作成果。

1.1. 版本选择

在开始之前，了解若依的版本生态至关重要，这能帮助我们理解为何做出当前的选择。

1.1.1. 官方与社区版本概览

若依框架为了适应不同的开发场景，官方和社区共同构建了一个丰富的产品矩阵。主要包括：

• RuoYi (混合版): 传统的 Spring Boot + Thymeleaf 架构，前后端代码耦合。
• RuoYi-Vue (分离版): 主流的前后端分离架构，官方长期维护 Vue 2 版本。
• RuoYi-Cloud (微服务版): 基于 Spring Cloud Alibaba 的微服务架构。
• RuoYi-App (移动端版): 使用 Uniapp 开发跨平台移动应用。
• 社区增强版: 如 RuoYi-Vue3 (升级前端到 Vue 3/Vite) 和 RuoYi-Vue-Plus (增强后端功能) 等。

1.1.2. 我们的选择：官方 Spring Boot 3 分支

为了紧跟技术潮流并获得最佳的开发体验，单纯的官方 RuoYi-Vue 主分支（基于 Spring Boot 2 和 Vue 2）已不能满足我们的要求。

幸运的是，若依官方已经提供了一个集成了 Spring Boot 3 和 Vue 3 的现代化分支。我们将直接使用这个分支作为起点，它一步到位地解决了前后端的技术升级问题。

文件路径: https://gitee.com/y_project/RuoYi-Vue/tree/springboot3

这让我们能跳过所有繁琐的迁移和配置，直接开始享受现代化技术栈带来的开发便利。

1.2. 环境准备

请确保您的本地开发环境满足以下最低要求。版本不匹配是导致后续问题的最常见原因。

1.3. 运行后端项目

在上一节我们明确了目标版本后，现在，让我们正式开始克隆项目并启动后端服务。

1.3.1. 克隆项目源码 (直达 Spring Boot 3 分支)

我们将使用 Git 克隆包含前后端所有文件的指定分支。

在您的工作目录下，打开终端并执行以下命令：

1
2

# 克隆项目，并直接切换到 springboot3 分支
git clone -b springboot3 https://gitee.com/y_project/RuoYi-Vue.git ruoyi-modern-project

命令执行完毕后，您会得到一个名为 ruoyi-modern-project 的文件夹。请使用 IntelliJ IDEA 打开这个项目。

1.3.2. 初始化数据库

后端服务的运行依赖于预设的数据库表结构和数据。

1. 请先在您的 MySQL 中创建一个新的数据库，推荐命名为 ry-vue。
2. 找到项目根目录下的 sql 文件夹，将 quartz.sql 和 ry_2023xxxx.sql 这两个 SQL 文件，依次导入到您刚刚创建的 ry-vue 数据库中。
   

1.3.3. 修改配置文件

接下来，我们需要告诉项目如何连接到我们的数据库和 Redis。

• 修改数据库连接
  文件路径: ruoyi-admin/src/main/resources/application-druid.yml
  请根据您的实际情况，修改 master 节点下的 url, username, password。

• 修改 Redis 连接（可选）
  文件路径: ruoyi-admin/src/main/resources/application.yml
  请根据您的实际情况，修改 redis 节点下的 host, port, password。

1.3.4. 启动后端服务

所有准备工作就绪，让我们启动后端。

1. 在 IDEA 中，找到 ruoyi-admin 模块。
2. 文件路径: ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java
3. 右键点击该文件，选择 Run 'RuoYiApplication'。

如果控制台成功打印出若依的 LOGO 和启动成功的字样，恭喜，后端服务已成功运行！

1.4. 运行前端项目

后端大脑已经开始运转，现在我们来点亮前端的“眼睛”。

1.4.1. 定位前端项目

我们克隆的 ruoyi-modern-project 文件夹中，已经包含了前端项目，其目录名为 ruoyi-ui，但他是 vue2 版本的，我们期望使用一个技术栈较新的 vue3 版本，我们可以将整个 ruoyi-ui 文件夹删除，在我们的 ruoyi-modern-project 文件夹中克隆前端 Vue3 项目，我们将会得到 RuoYi-Vue3

这个文件夹，通过 vscode 或其他编译器打开确认版本号无误后进行后续操作

1.4.2. 安装依赖并启动

1. 使用终端进入前端项目目录：

   1	cd ./RuoYi-Vue3

2. 安装所有 Node.js 依赖

   1 2 3 4 5 6 7

   # 安装依赖 pnpm install # 注意，由于前端的变化，vue3 仓库已经距离 2025 是三年前的了，一些 js 库依赖 sortablejs，所以需要手动安装，否则无法启动！ pnpm install sortablejs # 启动 Vite 开发服务器： # 启动服务 pnpm dev

   1.4.3. 验证成功

当终端显示出本地访问地址时，表示前端服务已成功启动。

打开浏览器，访问 http://localhost:80 (或终端提示的其他端口)，输入默认账户/密码 admin/admin123 并登录。如果您能看到功能齐全的后台主界面，则代表整个环境已搭建成功！

1.5. 本章小结

在本章中，我们高效地完成了所有基础准备工作，为后续的学习扫清了障碍。

• 明确了技术选型：我们直接采用了官方提供的 Spring Boot 3 + Vue 3 现代化技术栈。
• 成功运行了项目：通过克隆代码、初始化数据库和修改配置，我们成功地在本地启动了前后端服务，并完成了首次登录。

现在，一个强大、现代化的开发框架已经在我们手中。在下一章，我们将立即体验它最激动人心的功能——代码生成器。

第二章. 功能体验：5 分钟生成一个模块

2.1. 需求分析与数据库准备

在软件开发的传统流程中，当我们接到一个新的功能需求时，通常需要经历漫长的设计、编码、联调过程。但使用若依，我们的工作模式将发生根本性的转变。若依的代码生成器是 “数据库驱动” 的，这意味着我们的首要任务，也是最关键的一步，是精确地定义好数据库的表结构。这张表就是我们未来整个模块的“DNA”，它决定了实体类的属性、后端接口的字段，乃至前端页面的表单项和表格列。

2.1.1. 明确我们的目标

我们的目标是创建一个功能完善的“课程管理”模块，它需要具备以下核心功能点：

• 列表展示：能够分页、排序、清晰地展示所有课程的核心信息。
• 条件查询：支持根据课程编码、课程名称（模糊查询）、课程学科（下拉选择）等条件筛选数据。
• 数据操作：支持新增、修改、删除（单个或批量）课程信息。
• 数据导出：能够一键将当前查询结果导出为 Excel 表格。

最终，我们期望在系统中看到如下的功能界面：

2.1.2. 数据库先行：代码生成的“设计图纸”

现在，让我们来绘制这张“设计图纸”。请复制下面的 SQL 脚本，它不仅定义了 tb_course 表的结构，还预置了一些测试数据，方便我们生成代码后立刻进行功能验证。

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

-- ----------------------------
-- Table structure for tb_course
-- ----------------------------
DROP TABLE IF EXISTS `tb_course`;
CREATE TABLE `tb_course`  (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '课程ID',
  `code` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '课程编码',
  `subject` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '课程学科',
  `name` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '课程名称',
  `price` int NULL DEFAULT NULL COMMENT '价格（元）',
  `applicable_person` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '适用人群',
  `info` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '课程介绍',
  `create_by` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT '' COMMENT '创建者',
  `create_time` datetime NULL DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT '' COMMENT '更新者',
  `update_time` datetime NULL DEFAULT NULL COMMENT '更新时间',
  `remark` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE = InnoDB AUTO_INCREMENT = 7 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_0900_ai_ci COMMENT = '课程管理表' ROW_FORMAT = Dynamic;

-- ----------------------------
-- Records of tb_course
-- ----------------------------
INSERT INTO `tb_course` VALUES (1, 'cp123456', 'JavaEE', 'JavaSE基础', 199, '小白学员', 'JavaSE基础入门课程', 'admin', NOW(), 'admin', NOW(), NULL);
INSERT INTO `tb_course` VALUES (2, 'cp123457', 'JavaEE', 'JavaWeb', 188, '初级开发者', 'JavaWeb核心技术', 'admin', NOW(), 'admin', NOW(), NULL);
INSERT INTO `tb_course` VALUES (3, 'cp123458', 'Python', 'Python入门', 555, '小白学员', 'Python语言基础', 'admin', NOW(), 'admin', NOW(), NULL);
INSERT INTO `tb_course` VALUES (4, 'cp123459', 'Python', 'PythonWeb', 88, '初级开发者', '使用Django开发Web应用', 'admin', NOW(), 'admin', NOW(), NULL);
INSERT INTO `tb_course` VALUES (5, 'cp123460', 'HarmonyOS', '鸿蒙入门', 99, '小白学员', '鸿蒙应用开发基础', 'admin', NOW(), 'admin', NOW(), NULL);
INSERT INTO `tb_course` VALUES (6, 'cp123461', 'HarmonyOS', '鸿蒙商城实战', 59, '初级开发者', '鸿蒙分布式电商项目实战', 'admin', NOW(), 'admin', NOW(), NULL);

2.1.3. 逐行剖析 SQL：理解“设计图纸”的每一个细节

这段 SQL 看似简单，但其中每一个字段的定义都蕴含着为代码生成器服务的深意。让我们来逐一解读：

• id bigint NOT NULL AUTO_INCREMENT COMMENT '课程ID': 这是标准的自增主键。bigint 保证了足够的存储空间，AUTO_INCREMENT 让数据库自动管理 ID 的递增。最重要的是 COMMENT '课程ID'，这个 字段注释 至关重要，代码生成器会读取它，并将其作为后端实体类 Course.java 中 id 属性的 /** 课程ID */ 注释，以及前端 index.vue 页面表格中该列的表头 label="课程ID"。

• code varchar(32) ... COMMENT '课程编码': 这是一个业务编码字段。varchar(32) 定义了其类型和长度。同样，COMMENT '课程编码' 会被生成器用于生成各层代码的注释和前端标签。

• subject varchar(32) ... COMMENT '课程学科': 这是我们的“课程学科”字段。后续在代码生成器的配置中，我们会将它与“数据字典”关联，使其在前端自动渲染为下拉选择框。

• name varchar(64) ... COMMENT '课程名称': 课程的名称。我们会在生成器中将其查询方式配置为“模糊查询 (LIKE)”，以便用户可以只输入部分名称进行搜索。

• create_by, create_time, update_by, update_time, remark: 这五个字段是若依的“公共字段”。代码生成器能智能识别它们。因为若依的后端实体类基类 BaseEntity.java 中已经包含了这些属性，所以生成器在生成 Course.java 时，不会重复定义这些字段，而是让 Course 类直接继承 BaseEntity 来获得它们。这使得我们的业务实体类非常干净，只包含纯粹的业务字段。

2.1.4. 执行与验证

1. 执行 SQL:
   请使用您熟悉的数据库管理工具（如 Navicat, DataGrip, 或 MySQL Workbench）连接到我们在第一章创建的 ry-vue 数据库。然后，打开一个新的查询窗口，将上述完整的 SQL 脚本粘贴进去，并执行。

2. 验证结果:
   执行成功后，请刷新您的数据库表列表。您应该能看到一张名为 tb_course 的新表。为了进一步确认，您可以执行一条查询语句 SELECT * FROM tb_course;，如果能看到我们预置的 6 条课程数据，则证明数据库准备工作已圆满完成。

至此，我们已经为代码生成器提供了最关键的“原料”。这张精确定义的 tb_course 表，就像一份详细的建筑蓝图，已经准备就绪。在下一个小节中，我们将把这份蓝图“喂”给若依的代码生成器，亲眼见证它如何在几秒钟内为我们构建起一座功能齐全的“代码大厦”。

2.2. 代码生成：从导入到配置全流程

这个环节就像是工厂里的“总装车间”。我们将把原材料（数据表）送上生产线（导入），通过一系列精密的仪器（编辑配置）进行加工，最终产出标准化的成品（代码压缩包）。请跟随以下步骤，细致地完成每一步操作。

2.2.1. 步骤一：导入数据表，将“蓝图”送入“工厂”

首先，我们需要让若依系统“读取”到我们新创建的 tb_course 表。

1. 导航至功能入口：请在您已经登录的若依系统后台界面中，点击左侧菜单栏，依次展开并点击 系统工具 -> 代码生成。

2. 执行导入操作：您会看到一个代码生成的主列表，目前可能还是空的。请点击页面右上角的 导入 按钮。
   

3. 选择目标数据表：点击“导入”后，系统会弹出一个名为“导入表”的窗口。这个窗口会实时扫描当前数据库，并列出所有 尚未被代码生成器管理 的数据表。在这里，您应该能清晰地看到我们刚刚创建的 tb_course 表。

4. 确认导入：勾选 tb_course 表名前的复选框，然后点击窗口右下角的 确定 按钮。

操作完成后，弹窗关闭，您会发现代码生成的主列表中已经出现了一条新的记录，正是我们的“课程管理表”。这标志着我们的“蓝图”已经成功进入了“总装车间”，等待我们进行下一步的精细化配置。

2.2.2. 步骤二：编辑配置，为“代码”注入“灵魂”

这是整个代码生成过程中最关键、最需要投入精力的一步。在这里，我们不仅仅是在操作界面，更是在 “设计”我们未来的应用程序。我们将告诉若依，每个数据库字段在前端应该以何种形式展现、是否需要校验、是否支持查询等等。

找到 tb_course 表所在行，点击其最右侧操作列中的 编辑 按钮。页面会跳转到生成配置详情页，这里分为三个核心选项卡。

A. 配置【基本信息】选项卡

这个选项卡定义了生成代码的元数据，大部分信息若依已经为我们智能填充好了。

• 表名称 (tb_course)、表描述 (课程管理表): 这两个信息直接从数据库表的 NAME 和 COMMENT 中读取，通常无需修改。
• 实体类名称 (Course): 若依会自动根据表名（去掉前缀 tb_ 并转为驼峰命名法）生成。这是我们后端 domain 层实体类的名字，非常重要，一般保持默认即可。
• 作者: 这里默认是 ruoyi。建议修改为您自己的名字或团队名称。这个值会出现在所有生成代码文件的头部注释 /** @author 你的名字 */ 中，是体现代码归属的重要标识。
• 备注: 可选填，会生成在类注释的额外说明中。

B. 配置【字段信息】选项卡

这里是代码生成的“心脏”，我们对每一行字段的配置，都将精确地反映在最终的前后端代码中，请按照下列图片中的勾选法，我们会在后面详细讲解

让我们逐列来理解这些配置项的含义：

• 字段描述: 来自数据库字段的 COMMENT，将成为前端页面表格项的 label 行

• 插入/编辑/列表/查询 (√)：这四列是最常用的配置。它们是布尔开关，决定了该字段是否会出现在对应的场景中。
• 插入: 勾选后，该字段会出现在“新增”弹窗的表单中。
  * 编辑: 勾选后，该字段会出现在“修改”弹窗的表单中。
  * 列表: 勾选后，该字段会出现在主页面的数据表格中。
  * 查询: 勾选后，该字段会出现在页面顶部的搜索表单中。

下面的表格将 完全模拟 您在上图界面中的操作过程。每一行都代表一个需要我们特别关注的字段，并清晰地展示了应如何配置，以及 “为什么这么配置”。

(注：未在表格中列出的字段，如 code、applicable_person 等，可保持代码生成器的默认勾选配置，即支持完整的插入、编辑、列表和查询功能。)

C. 配置【生成信息】选项卡

这里决定了生成的代码文件应该放在哪里，以及它们的命名规则。

• 生成模板: 若依内置了 crud (单表，增删改查) 和 tree (树形结构) 等模板。我们是标准的单表操作，保持默认的 crud 即可。
• 生成模块名: 非常重要。这个名字将作为后端代码的子包名和前端代码的目录名。我们将其设置为 course。最终生成的后端包会是 com.ruoyi.course，前端 API 和视图目录会是 api/course 和 views/course。
• 生成业务名: 非常重要。它决定了代码中核心类名的前缀。我们将其设置为 Course (首字母大写)。最终生成的类会是 CourseController.java, ICourseService.java, Course.java 等。
• 生成功能名: 用于代码注释和菜单名称。我们填写 课程管理。
• 上级菜单: 决定了新生成的菜单项在系统左侧菜单栏中的位置。我们暂时将其挂在 系统工具 目录下。
• 生成路径: 默认为一个临时目录。强烈建议保持默认。这是一种安全机制，避免因配置错误直接覆盖您项目中的已有代码。我们总是先生成到临时目录，检查无误后再手动复制到项目中。

完成以上所有配置后，点击页面最下方的 提交 按钮保存我们的配置。

2.2.3. 步骤三：预览与生成，收获“劳动”成果

回到代码生成主列表页面，我们的配置工作已经完成。

1. 预览 (可选但推荐)：点击 tb_course 表操作列中的 预览 按钮。系统会弹出一个窗口，里面以选项卡的形式展示了即将生成的 domain.java, controller.java, service.java, mapper.xml, vue/index.vue, js/api.js 等所有文件的完整代码。这是一个绝佳的“代码审查”机会，您可以快速检查：
   • Course.java 的字段和注释是否正确？
   • CourseController.java 的权限标识 (@PreAuthorize) 是否符合预期？
   • index.vue 的表单项和表格列是否与您的配置一致？预览能帮助您在生成代码前发现并修正配置错误，事半功倍。

2. 生成代码：确认预览无误后，回到主列表，勾选 tb_course 表前的复选框，然后点击页面顶部的 生成代码 按钮。

浏览器会自动下载一个名为 ruoyi.zip 的压缩文件。

至此，神奇的时刻已经发生！

这个小小的 ruoyi.zip 文件中，包含了我们刚刚通过一系列页面配置所“设计”出来的，一个功能完备、前后端分离、代码规范、权限严密的“课程管理”模块的全部源码。我们没有写一行业务代码，却已经完成了过去可能需要数天才能完成的工作。

这把新鲜出炉的“神兵利器”已经铸造完毕。在下一个小节中，我们将学习如何将其“开刃”——把这些代码文件精准地集成到我们的项目中，并激活它的全部功能。

2.3. 代码集成与功能激活

在上一节中，我们已经成功地将数据库表“设计图”通过若依的配置界面，转化为一个包含了完整前后端代码的 ruoyi.zip 压缩包。这就像我们订购了一套预制房屋的建材，所有墙体、门窗、电路都已按需生产完毕。现在，我们将进入“现场施工”阶段，把这些“建材”精准地拼装到我们项目的“地基”之上，并接通“水电”，让它真正“活”起来。

这个过程需要细致和精确，就像拼装一个精密的模型。每一步操作都对应着将一个代码“零件”安装到它在系统中的正确位置。我们将分三步走：安装后端“引擎”、安装前端“仪表盘”，最后安装连接两者的“控制电路”（菜单与权限）。

2.3.1. 第一步：解压与勘察，认识我们的“代码零件包”

首先，请在您的电脑上找到并解压刚刚下载的 ruoyi.zip 文件。解压后，您会看到一个结构清晰的文件夹，它就是我们接下来工作的“零件盒”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

ruoyi/
├── main
│   ├── java
│   │   └── com
│   │       └── ruoyi
│   │           └── course      # <-- 后端 Java 代码 (Controller, Service, Domain)
│   └── resources
│       └── mapper
│           └── course          # <-- 后端 MyBatis XML 文件
├── sql
│   └── menu.sql                # <-- 菜单与权限的 SQL 脚本
└── vue
    ├── api
    │   └── course              # <-- 前端 API 请求文件
    └── views
        └── course              # <-- 前端页面 Vue 组件

这个目录结构就是若依项目结构的微缩模型，清晰地告诉了我们每个“零件”应该被安装到哪里。

2.3.2. 第二步：后端代码集成，安装“引擎”与“传动系统”

我们需要将后端的 Java 类和 MyBatis 的 XML 映射文件，复制到我们正在运行的后端项目中。

1. 复制核心业务代码 (Java)：

   • 源路径 (零件盒): ruoyi/main/java/com/ruoyi/course
   • 目标路径 (项目地基): ruoyi-modern-project/ruoyi-admin/src/main/java/com/ruoyi/

   操作:
   请 完整地复制 源路径下的 course 文件夹。然后，在您的 IDE (如 IntelliJ IDEA) 的项目目录树中，找到并进入目标路径，粘贴 刚才复制的文件夹。

   

   验证:
   操作完成后，您的 ruoyi-admin 模块的项目结构中应该会立即出现一个新的包 com.ruoyi.course。您可以点开它，会看到 controller、domain、service 等子包，以及 CourseController.java 等我们熟悉的类文件。

2.3.3. 第三步：前端代码集成，安装“仪表盘”与“操作界面”

接下来，我们来安装用户能直接看到和交互的前端部分。

1. 复制 API 请求文件:

   • 源路径 (零件盒): ruoyi/vue/api/course
   • 目标路径 (项目地基): ruoyi-modern-project/ruoyi-ui/src/api/

   操作:
   复制源路径下的 course 文件夹，并将其粘贴到前端项目的 src/api/ 目录下。

   讲解:
   src/api 目录是前端项目统一管理所有后端接口请求的地方。我们刚刚复制进去的 course.js 文件，里面封装了 listCourse, addCourse 等函数，每一个函数都对应着对后端 CourseController 中一个接口的 AJAX 调用。

2. 复制页面视图文件:

   • 源路径 (零件盒): ruoyi/vue/views/course
   • 目标路径 (项目地基): ruoyi-modern-project/ruoyi-ui/src/views/

   操作:
   复制源路径下的 course 文件夹，并将其粘贴到前端项目的 src/views/ 目录下。

   讲解:
   src/views 目录存放着项目所有的页面组件。我们复制进去的 index.vue 文件，就是我们在 2.2 节中通过各种配置“设计”出来的“课程管理”页面的完整 Vue 组件代码。

2.3.4. 第四步：激活菜单与权限，接通“控制电路”

至此，我们的“硬件”——前后端代码文件——已经全部安装到位。但是，如果您现在刷新系统，会发现根本找不到“课程管理”的入口。这是因为系统还“不认识”这个新功能。

这就好比我们为电脑装了一块新显卡，但没有安装驱动程序。menu.sql 文件，就是我们这个新模块的“驱动程序”。它负责告诉若依的权限系统（RBAC）：

• 有一个新菜单：它的名字叫“课程管理”。
• 它的位置在哪里：它应该显示在“系统工具”菜单下面。
• 如何访问它：点击它时，应该加载前端的 /course 路由，对应的是 views/course/course/index.vue 这个组件。
• 谁能看到它：只有拥有 course:course:list 权限标识的角色，才能在菜单栏里看到它。
• 它内部有哪些操作权限：这个页面里有新增、修改、删除等操作，它们分别对应 course:course:add, course:course:edit, course:course:remove 等权限标识。

操作:

1. 找到 SQL 文件: 在解压后的 ruoyi/sql 目录中，找到 menu.sql 文件。
2. 执行 SQL: 使用您的数据库管理工具，连接到 ry-vue 数据库，打开一个新的查询窗口，将 menu.sql 文件的全部内容复制进去，并执行。
   

当这条 SQL 执行成功后，若依的 sys_menu 表中就写入了关于“课程管理”模块的所有元数据。系统现在已经完全“认识”了我们的新功能，并准备好了将其展示给拥有相应权限的用户。

我们的“施工”工作已经全部完成。所有“零件”各就各位，“电路”也已接通。在下一个，也是本章最后一个小节中，我们将按下“启动”按钮，亲眼见证我们从零开始、在几分钟内创造出的完整功能模块，是如何在系统中完美运行的。

2.4. 访问与功能验证

本节将对上一节集成的“课程管理”模块进行全面的功能验证。目标是确认所有自动生成的组件、接口及权限均已正确部署并按预期运行。我们将遵循标准的软件测试流程，对模块的 CRUD (Create, Retrieve, Update, Delete)、查询、分页及导出等核心功能进行系统性测试。

2.4.1. 系统环境重载

为确保应用程序能完全加载新集成的代码资源和数据库菜单配置，必须执行以下重启和刷新操作。

1. 重启后端服务：在 IntelliJ IDEA 中，终止当前运行的 RuoYiApplication 进程，然后重新执行该主类以启动应用。此步骤旨在让 Spring IoC 容器能够扫描并注册新增的 com.ruoyi.course 包下的所有组件（如 Controller, Service），并让 MyBatis 框架加载 CourseMapper.xml 配置文件。

2. 刷新前端应用：在浏览器中，执行强制刷新操作（Ctrl + R 或 Cmd + R）以重新加载若依的前端应用。此操作将触发前端路由和权限管理模块向后端重新请求菜单数据，从而加载我们在 sys_menu 表中新增的“课程管理”菜单项。在多数情况下，需要重新进行用户登录。

2.4.2. 模块入口验证

在完成环境重载和重新登录后，需要验证新模块的菜单入口是否已正确生成。

1. 定位菜单项：在系统界面的左侧导航菜单中，展开“系统工具”父菜单。
2. 确认菜单可见性：检查“系统工具”菜单下是否存在一个名为“课程管理”的子菜单项。该菜单项的存在，证明了 menu.sql 脚本已成功执行，并且当前登录的管理员角色拥有访问该菜单所需的 course:course:list 权限标识。

3. 访问模块页面：点击“课程管理”菜单项。主内容区应成功加载并渲染出课程管理模块的主界面。界面应包含顶部条件查询表单、中部数据表格（已加载并显示 tb_course 表中的 6 条初始数据）以及底部自分页组件。

2.4.3. 功能点逐项测试

接下来，对模块的核心功能进行单元测试。

1. 数据检索 (Retrieve) 功能测试：

   • 模糊查询：在“课程名称”输入框中输入查询字符串 Java，点击“搜索”。预期结果：数据表格应通过异步请求刷新，仅显示 name 字段包含 Java 的数据行。此测试验证了我们在代码生成器中为 name 字段配置的 LIKE 查询方式已在后端 CourseMapper.xml 中正确生成并执行。
   • 重置功能：点击“重置”按钮。预期结果：所有查询条件输入框应被清空，数据表格应恢复显示所有初始数据。

2. 数据创建 (Create) 功能测试：

   • 点击“新增”按钮，系统应弹出一个模态对话框（Dialog）。
   • 表单校验：检查对话框内的表单元素是否与代码生成器的配置一致。确认“课程介绍”字段渲染为 textarea 组件，“课程名称”和“价格”字段为必填项（有相应的视觉提示）。
   • 数据提交：在表单中输入一组有效的新课程数据，点击“确定”按钮提交。
   • 结果验证：对话框应关闭，并显示“新增成功”的全局提示。数据表格应自动刷新，并在最后一页（或当前页，取决于排序方式）显示新创建的记录。

3. 数据更新 (Update) 功能测试：

   • 在数据表格中，选中一条记录前的复选框。
   • 点击“修改”按钮，系统应弹出模态对话框，并自动将所选记录的数据填充到表单的对应字段中。
   • 数据修改与提交：修改表单中的任意字段值（例如，修改价格），然后点击“确定”提交。
   • 结果验证：系统应提示“修改成功”。数据表格中对应记录的已修改字段应更新为新值。

4. 数据删除 (Delete) 功能测试：

   • 单行删除：点击任意数据行右侧操作列中的“删除”按钮。在系统弹出的确认对话框中确认操作。预期结果：该数据行应从表格中移除。
   • 批量删除：在数据表格中，选中多条记录前的复选框。点击页面顶部的“删除”按钮并确认。预期结果：所有被选中的数据行应从表格中移除。

5. 数据导出 (Export) 功能测试：

   • （可选）在顶部设置任意查询条件。
   • 点击“导出”按钮。
   • 结果验证：浏览器应下载一个 .xlsx 格式的 Excel 文件。打开该文件，验证其内容是否与当前数据表格中显示的数据完全一致（包括经过筛选的数据）。

测试结论:
若以上所有功能点的预期结果均已达成，则可以确认：代码生成器已成功创建了一个功能完备、前后端逻辑正确、权限集成无误的业务模块。这验证了若依“快速开发平台”通过自动化代码生成来提升开发效率的核心价值。

第三章. 核心功能详解

在本章中，我们将像研究一本精密仪器的说明书一样，逐一拆解若依的核心部件：

1. 首先，我们将深入若依的“安全内核”——权限系统 (RBAC)，理解它是如何实现“正确的人，做正确的事”的。
2. 接着，我们将掌握若依的“数据中枢”——数据字典，学会如何用它来管理系统中的静态数据，并解决实际开发中的 UI 交互问题。
3. 最后，我们会快速导览 参数配置、日志管理 等其他常用功能，完善我们的知识体系。

3.1. 权限系统 (RBAC)

权限管理是任何企业级后台系统的基石。若依内置了一套功能强大且设计经典的权限模型——RBAC（Role-Based Access Control，基于角色的访问控制）。理解 RBAC，是理解若依乃至绝大多数后台系统安全设计的关键。

3.1.1. 理解 RBAC：用户、角色与权限的关系

RBAC 的核心思想非常简洁：不直接给用户分配权限，而是将权限赋予“角色”，再将“角色”赋予用户。

想象一下，在一个公司里，我们不会对新员工“张三”说：“你可以使用打印机、可以访问 A 系统、可以审批 B 流程……”。而是直接告诉他：“你的岗位是‘市场专员’”。而“市场专员”这个角色，已经被预先设定好了一揽子完成其工作所必需的权限。

这种模式带来了巨大的管理优势：

• 高效授权：当一个新员工入职时，我们只需给他分配一个或多个角色，他便立即拥有了这些角色的所有权限。
• 批量变更：当“市场专员”的职责发生变化，需要增加一项新权限时，我们只需修改“市场专员”这个角色本身，所有拥有该角色的员工权限便会自动更新。
• 职责清晰：角色本身就代表了一组业务职责，使得权限管理与组织的业务结构保持一致，易于理解和维护。

在若依系统中，这个模型由三个核心实体和两个关系实体构成：

• 核心实体:

  • 用户 (User): 系统中的操作个体，如 admin, ry。
  • 角色 (Role): 权限的集合，代表一种职责或岗位，如“超级管理员”、“普通用户”。
  • 菜单/权限 (Menu/Permission): 系统的可操作资源。在若依中，它被巧妙地统一到了“菜单管理”中。一个“菜单”项（如“课程管理”）代表了页面访问权限，而一个“按钮”项（如“课程新增”）代表了具体的操作权限。

• 关系实体:

  • 用户-角色关系: 定义了哪个用户拥有哪个角色（一个用户可以有多个角色）。
  • 角色-菜单关系: 定义了哪个角色拥有哪些菜单和按钮的权限（一个角色可以有多个权限）。

这五个实体之间的关系，在若依系统里被定义为了如下这五张表：

这张图清晰地揭示了它们在数据库层面是如何通过 sys_user_role 和 sys_role_menu 这两张中间表，建立起多对多的关系的。当一个用户登录时，系统会：

1. 根据用户 ID，在 sys_user_role 表中找到他所拥有的所有角色 ID。
2. 根据这些角色 ID，在 sys_role_menu 表中找到这些角色所拥有的所有菜单/权限 ID。
3. 系统将这些权限信息（通常是一组权限标识符，如 course:course:list）存入该用户的会话（或 Token）中。
4. 当用户访问一个页面或点击一个按钮时，后端（通过 Spring Security 的 @PreAuthorize 注解）和前端（通过自定义的 v-hasPermi 指令）会检查用户的会话中是否包含所需的权限标识符，从而决定是否放行。

3.1.2. 实战：创建“课研专员”角色并分配权限

理论知识是基础，现在让我们通过一个具体的业务场景，将理论付诸实践。

场景需求：我们需要在系统中创建一个新的角色——“课研专员”。这个角色的工作人员，其核心职责是管理课程信息，因此他们 只需要“课程管理”模块的全部权限，而不能访问系统中的其他任何功能（如用户管理、角色管理等）。

我们将分三步来完成这个任务：

第一步：创建新角色

1. 在若依后台，导航至 系统管理 -> 角色管理。
2. 点击左上角的 新增 按钮。
3. 在弹出的“添加角色”窗口中，填写以下信息：
   • 角色名称: 课研专员
   • 权限字符: course_researcher (这是一个全局唯一的 Key，后端权限校验时会用到)
   • 显示排序: 输入一个数字，如 3。
   • 状态: 保持“正常”。

第二步：为角色分配菜单权限

1. 在“菜单权限”的树形结构中，取消勾选 最顶层的“系统管理”、“系统监控”、“系统工具”等所有默认选中的权限。

2. 展开 系统工具 目录，找到并 只勾选“课程管理” 这一项。当您勾选父菜单“课程管理”时，其下属的所有按钮权限（查询、新增、修改、删除、导出）也会被自动勾选。
   

3. 点击 保存 按钮。

至此，“课研专员”这个角色已经被我们精确地赋予了它所需的所有、且仅有的权限。

第三步：创建新用户并关联角色

1. 导航至 系统管理 -> 用户管理。
2. 点击 新增 按钮。
3. 在“新增用户”页面，填写新用户的基本信息，例如：
   • 用户昵称: 小P
   • 用户名称: Prorise
   • 密码: 设置一个初始密码。
4. 在页面的下半部分，找到 角色 分配区域。取消勾选 默认的“普通用户”角色，然后 只勾选我们刚刚创建的“课研专员”。
5. 点击 确定 保存用户。

第四步：验证

所有配置已完成。现在，请退出当前的 admin 账户，使用我们刚刚创建的 Prorise 账户登录系统。

登录成功后，观察左侧的菜单栏。您会发现，原本庞大的菜单树消失了，只剩下了一个“系统工具”目录，且该目录下只有一个可点击的“课程管理”菜单。尝试访问其他被隐藏的 URL，系统会提示权限不足。进入“课程管理”页面，所有的新增、修改、删除按钮均可正常使用。

实验结论：我们成功地通过 RBAC 模型，创建了一个职责明确、权限最小化的新角色，并将其赋予了新用户。这个过程没有修改任何代码，完全通过后台界面配置完成。这充分展示了若依权限系统的灵活性与强大功能。

3.2. 数据字典：让你的页面“活”起来

数据字典是企业级应用中一个看似简单但至关重要的功能。它负责集中管理系统中相对稳定、但又可能需要调整的“静态数据”或“枚举值”。

3.2.1. 什么是数据字典及其应用场景

想象一下，在一个系统中，有多少地方需要用到“状态”这个概念？

• 用户有“正常”、“停用”两种状态。
• 订单有“待支付”、“已支付”、“已发货”、“已完成”、“已取消”等多种状态。
• 通知公告有“通知”、“公告”两种类型。

如果我们在代码的每个角落都硬编码这些值（比如 if (status == 0) 代表正常，if (status == 1) 代表停用），会带来一场灾难：

• 可读性差：代码中充满了“魔法数字”（Magic Numbers），0 和 1 本身不具备任何业务含义，极难理解。
• 维护困难：如果有一天，需要增加一种“锁定”状态 2，你需要大海捞针般地找出系统中所有与用户状态相关的代码，进行修改，极易遗漏。
• 不一致性：前端页面、后端逻辑、数据库存储，三者对状态的定义可能产生偏差，导致难以追踪的 BUG。

数据字典正是为了解决这些问题而生。

它提供了一个统一的地方，让我们用业务人员能理解的语言，来定义这些静态数据。例如，我们可以创建一个名为 sys_user_status 的字典类型，在里面定义：

这样，在整个系统中：

• 前端：可以调用接口获取这个字典，自动生成下拉框或单选框，用户看到的是“正常”、“停用”这样的友好文本。
• 后端：在接收或返回数据时，处理的是 0、1 这样规范的值，同时也可以方便地将 0 转换为“正常”用于日志或展示。
• 数据库：存储的是简洁的 0、1，节省空间且便于索引。

当需要增加“锁定”状态时，我们只需在数据字典管理界面新增一条记录 {"锁定", "2"}，整个系统（如果设计得当）无需修改一行代码，就能自动适应这种变化。

若依的数据字典功能主要由两部分构成：

• 字典类型: 对字典进行分组，相当于一个“文件夹”。例如 sys_user_status (用户状态), sys_notice_type (公告类型)。每个字典类型都有一个全局唯一的 类型名称 (Dict Type)。
• 字典数据: 隶属于某个字典类型下的具体键值对。例如 sys_user_status 下的 {"正常", "0"} 和 {"停用", "1"}。

它们在数据库中对应两张核心表：sys_dict_type (字典类型表) 和 sys_dict_data (字典数据表)，通过 dict_type 字段进行关联。

3.2.2. 实战：为“课程学科”创建并应用数据字典

现在，让我们运用数据字典的知识，来完成第二章未竟的事业。我们的目标是，将“课程管理”模块中“课程学科”的查询条件和新增/修改表单，都改造为下拉选择框。

这个过程将完美地形成一个“学习 -> 配置 -> 应用 -> 验证”的闭环，让您深刻体验若依“配置驱动开发”的魅力。

第一步：创建字典类型

1. 在若依后台，导航至 系统管理 -> 字典管理。

2. 点击左上角的 新增 按钮。

3. 在弹出的“添加字典类型”窗口中，填写以下信息：

   • 字典名称: 课程学科 (这是给人看的，方便理解)
   • 字典类型: course_subject (非常重要！这是给程序用的唯一标识符，必须是英文且唯一)
   • 状态: 保持“正常”。
   • 备注: 可选填，如“用于定义课程的所有学科分类”。

4. 点击 确定 保存。

第二步：添加字典数据

字典类型这个“文件夹”已经建好，现在我们往里面添加具体的“文件”。

1. 在字典管理列表页，找到我们刚创建的“字典类型”这一行，点击其高亮的蓝色标签
2. 页面会跳转到“字典数据”管理界面。点击左上角的 新增 按钮。
3. 在“添加字典数据”窗口中，填写第一条数据：
   • 字典类型: 自动带入 course_subject
   • 数据标签: JavaEE (这是显示在下拉框中的文本)
   • 数据键值: 0 (这是提交到后端并存入数据库的值)
   • 显示排序: 1（用于下拉框选择项的排序顺序）
   • 状态: 正常
4. 点击 确定 保存。
5. 重复操作：请参照上一步，继续添加 Python 和 HarmonyOS 这两个学科。确保它们的“数据键值”也是对应的英文。

全部添加完成后，您应该能在 course_subject 的字典数据列表中看到三条记录。

第三步：将数据字典应用到代码生成器

现在，我们的数据字典已经准备就绪。是时候回到第二章我们留下“伏笔”的地方，将这块“拼图”拼上了。

1. 导航回到 系统工具 -> 代码生成。
2. 找到 tb_course (课程管理表) 这一行，点击 编辑。
3. 在编辑页面，切换到 字段信息 选项卡。
4. 找到 subject (课程学科) 这一行，定位到最右侧的 字典类型 这一列。
5. 点击该列的下拉框，您现在应该能在列表中找到我们刚刚创建的 course_subject！选中它。
   
6. 点击页面底部的 提交 按钮保存配置。

第四步：重新生成并集成代码

我们的“设计图纸”已经更新，现在需要让“工厂”按照新的图纸重新生产“零件”。

1. 在代码生成主列表，重新勾选 tb_course 表。

2. 再次点击 生成代码 按钮，下载一个新的 ruoyi.zip 文件。

3. 解压这个新的压缩包。注意，这次我们不需要关心后端的 Java 代码或 SQL 文件，因为数据字典的应用主要体现在前端。

4. 覆盖前端代码：

   • 源路径: 新解压的 ruoyi/vue/views/course/index.vue
   • 目标路径: ruoyi-modern-project/ruoyi-ui/src/views/course/index.vue
   • 操作: 直接用新的 index.vue 文件，覆盖 掉项目中原有的同名文件。

第五步：修正数据不匹配问题

在验证成果之前，我们需要解决一个关键问题：数据库中现有数据与数据字典的值不匹配。

回顾一下，在第二章初始化数据时，我们插入的课程数据中 subject 字段的值是 'JavaEE'、'Python' 等字符串。但在刚才创建数据字典时，我们将 “数据键值” 设置为了 0、1、2 这样的数字。

这会导致一个问题：当您打开 “课程管理” 页面时，现有的课程记录在 “课程学科” 列会显示为纯数字，因为系统无法将数据库中的 'JavaEE' 字符串匹配到字典值 0。

为什么会有这个问题？

这是一个典型的 “历史数据兼容性” 问题。在实际项目中非常常见：

• 设计初期：我们直接在数据库中存储了业务含义明确的字符串 'JavaEE'，这样做简单直观。
• 引入数据字典后：为了规范化和便于维护，我们改用数字编码 0、1、2 来存储，前端通过字典将其转换为友好的中文标签展示给用户。

解决方案有两种：

方案一：修改数据字典的键值（推荐用于学习）

如果您的系统刚刚起步，数据量还很少，最简单的做法是调整数据字典，让它的 “数据键值” 与数据库现有数据保持一致。

1. 返回 系统管理 -> 字典管理。
2. 点击 course_subject 字典类型，进入字典数据列表。
3. 逐一编辑三条字典数据，将它们的 数据键值 修改为：
   • JavaEE 的数据键值改为 JavaEE （而不是 0）
   • Python 的数据键值改为 Python （而不是 1）
   • HarmonyOS 的数据键值改为 HarmonyOS （而不是 2）
4. 保存修改。

这样，数据字典的键值就与数据库中 subject 字段的实际存储值完全一致了，页面可以正常匹配显示。

方案二：修改数据库中的历史数据（推荐用于生产）

如果您希望数据库存储更规范的数字编码（这在大型系统中更常见），则需要更新数据库中的历史数据。

在 Navicat 或其他数据库工具中执行以下 SQL 语句：

1
2
3

UPDATE tb_course SET subject = '0' WHERE subject = 'JavaEE';
UPDATE tb_course SET subject = '1' WHERE subject = 'Python';
UPDATE tb_course SET subject = '2' WHERE subject = 'HarmonyOS';

执行后，数据库中的 subject 字段值就变成了 0、1、2，与我们最初创建的数据字典键值完全对应。

本教程采用方案二，因为它操作更简单，我们的测试数据很少，更适合初学者。在实际项目中，您可以根据具体情况灵活选择。

第六步：修复前端样式问题

覆盖完代码后，您可能会发现 “课程学科” 下拉框显示异常：它可能只显示为一个小方块，无法正常展开选择。这是因为代码生成器生成的 el-select 组件默认没有设置宽度，导致组件收缩。

我们需要手动为下拉框添加宽度样式。

打开项目中的 ruoyi-modern-project/RuoYi-Vue3/src/views/course/Course/index.vue 文件：

位置一：查询表单中的下拉框

找到第 12-21 行左右的查询表单部分，将：

1
2

<el-form-item label="课程学科" prop="subject">
  <el-select v-model="queryParams.subject" placeholder="请选择课程学科" clearable>

修改为（在 el-select 标签中添加 style="width: 240px"）：

1
2

<el-form-item label="课程学科" prop="subject">
  <el-select v-model="queryParams.subject" placeholder="请选择课程学科" clearable style="width: 240px">

位置二：新增/编辑对话框中的下拉框

找到第 133-141 行左右的对话框表单部分，将：

1
2

<el-form-item label="课程学科" prop="subject">
  <el-select v-model="form.subject" placeholder="请选择课程学科">

修改为（添加 style="width: 100%"）：

1
2

<el-form-item label="课程学科" prop="subject">
  <el-select v-model="form.subject" placeholder="请选择课程学科" style="width: 100%">

为什么要设置不同的宽度？

• 查询表单是 内联布局 (inline="true")，各个表单项横向排列，设置固定宽度 240px 可以保持页面紧凑美观。
• 对话框表单是 垂直布局，表单项纵向堆叠，设置 100% 宽度可以让下拉框填充整个表单项区域，与其他输入框保持视觉一致。

保存文件后，下拉框就能正常显示了。

第七步：验证成果

回到您的浏览器，强制刷新“课程管理”页面（可能需要重新登录）。

现在，请观察页面顶部的搜索栏和点击“新增”或“修改”按钮弹出的表单。您会惊喜地发现，原本的“课程学科”文本输入框，已经 神奇地变成了功能完善的下拉选择框！点击它，会清晰地列出我们在数据字典中配置的“JavaEE”、“Python”和“HarmonyOS”三个选项。

实验结论：我们成功地通过数据字典，以一种零编码、纯配置的方式，优化了一个重要的前端交互。这个完整的闭环流程充分证明了数据字典在解耦前后端数据、提升开发效率和系统可维护性方面的巨大价值。现在，您已经完全掌握了若依的这一核心功能。

3.3. 参数设置：系统的动态“开关”

在任何一个正式的软件项目中，我们都会遇到一类特殊的配置项：它们不像数据库地址那样恒定不变，但又不能直接硬编码在代码里，因为业务人员或运维人员可能需要根据实际情况随时调整。

参数设置 功能，正是为了解决这一痛点而设计的。它本质上是一个 存储在数据库中的、全局的键值对（Key-Value）配置中心。通过后台界面，我们可以方便地对这些参数进行动态维护。

使用该功能的核心优势在于：

• 避免硬编码：将易变的业务逻辑值（如“密码最大重试次数”、“是否开启某项活动”）从代码中剥离，提高了代码的可维护性。
• 运行时动态生效：修改参数后，通常只需刷新缓存即可在整个系统中生效，无需重新编译代码或重启服务，这对于生产环境的运维至关重要。
• 配置集中化：所有动态参数都在一个统一的界面进行管理，一目了然。

3.3.1. 实战案例：动态关闭登录验证码

业务场景: 在项目开发和测试阶段，开发人员需要频繁地登录、退出系统进行调试。默认开启的登录验证码虽然增强了安全性，但在这个阶段却大大降低了调试效率。我们的需求是：在不修改任何代码的情况下，为开发环境动态地关闭登录验证码功能。

实现步骤:

1. 导航至参数设置
   在若依后台，依次点击 系统管理 -> 参数设置。您会看到一个列表，其中包含了系统预设的多个参数。
   
2. 定位目标参数
   在参数列表中，找到 参数键名 为 sys.account.captchaEnabled 的记录。从键名我们可以直观地理解，这个参数就是用来控制“账户验证码是否启用”的。
3. 修改参数值
   点击该行右侧操作列的 修改 按钮。在弹出的“修改参数”窗口中，将 参数键值 从 true 修改为 false。

1. 清除缓存以使配置生效
   点击 确定 保存修改。此时，配置已经更新到了数据库中，但正在运行的系统为了性能，读取的是 Redis 缓存中的旧配置。因此，我们需要执行关键的最后一步：点击页面右上角的 “刷新缓存” 按钮。这个操作会通知系统从数据库重新加载所有配置项到 Redis 中。

2. 验证结果
   现在，请退出当前 admin 账户。当您返回到登录页面时，会发现原先的验证码输入框和图片已经消失了，可以直接输入用户名和密码进行登录。

   

通过这个简单的案例，我们以一种零代码、纯配置的方式，动态地改变了系统的核心行为，这正是“参数设置”功能的强大之处。

3.4. 日志管理：系统操作的全程记录仪

日志是系统安全、问题排查和行为审计的生命线。若依提供了两个开箱即用的日志管理模块，它们就像是安装在系统内部的“黑匣子”和“监控摄像头”，忠实地记录着发生的一切。

3.4.1. 操作日志：行为审计与问题追溯

是什么？
操作日志精确记录了用户在系统中所有 对数据产生变更或执行重要查询 的关键操作。

背后原理:
该功能是通过 Spring AOP（面向切面编程） 和一个自定义的 @Log 注解 实现的。当一个 Controller 方法被 @Log 注解标记后，AOP 切面会自动拦截该方法的调用。在方法执行前后，切面会收集诸如 操作用户、IP 地址、请求 URL、调用方法、传入参数、操作耗时、是否成功 等信息，并将其异步地保存到数据库的 sys_oper_log 表中。

实战联动：追踪“课程管理”的操作记录

1. 执行操作: 请您现在导航至 系统工具 -> 课程管理 模块。执行一次 新增 操作，成功添加一条新的课程记录。然后，再执行一次 删除 操作，将这条新记录删除。
2. 查看日志: 操作完成后，立刻导航至 系统监控 -> 操作日志。
3. 分析结果: 在日志列表的顶部，您会看到两条最新的记录：
   • 一条记录的 业务类型 是 “新增”，请求方式 是 POST。点击“详细”按钮，您甚至可以看到当时提交的完整 JSON 数据。
   • 另一条记录的 业务类型 是 “删除”，请求方式 是 DELETE。

这个联动的过程清晰地展示了操作日志的价值：它为每一次关键操作都留下了不可否认的证据，无论是用于事后排查问题（“是谁误删了数据？”），还是进行安全审计，都至关重要。

3.4.2. 登录日志：守护系统安全的第一道防线

是什么？
登录日志专门、独立地记录每一次用户登录系统的尝试，无论成功与否。

核心价值:
它是系统安全审计的关键环节。通过分析登录日志，管理员可以：

• 发现异常登录: 例如，在短时间内，同一个账户从多个不同的地理位置 IP 尝试登录，这极有可能是账户被盗或被攻击的迹象。
• 监控失败尝试: 如果一个账户连续多次登录失败，系统可以触发告警或自动锁定该账户，防止暴力破解。

如何使用:
导航至 系统监控 -> 登录日志。这里详细列出了所有登录尝试的账号、状态（成功/失败）、IP 地址、登录地点、浏览器和操作系统信息。

3.5. 通知公告：系统的“广播站”

是什么？
这是一个简单但非常实用的内容发布功能，允许管理员向系统内的用户发布结构化的信息。

核心功能:

• 富文本编辑: 创建公告时，支持使用富文本编辑器，可以方便地设置文本格式、插入图片、超链接等。
• 公告分类: 公告可以被分为不同的类型，如“通知”和“公告”。这个分类本身也是由 数据字典 (sys_notice_type) 维护的。

实战案例：发布一条版本更新通知

1. 导航: 进入 系统管理 -> 通知公告。
2. 新增公告: 点击“新增”按钮。
3. 填写内容:
   • 公告标题: 系统 V3.8.7 版本更新通知
   • 公告类型: 选择 通知
   • 公告内容: 在富文本编辑器中输入更新详情。

目前 ruoyi 普通版只有内置对于公告的 CRUD，对于页面来说他不会有任何变化，如果希望自己集成公告推送的话可以参考如下这篇文章：

[Ruoyi 若依通知公告功能实现（轮询信息铃铛）_若依消息通知-CSDN 博客](https://blog.csdn.net/TinpeaV/article/details/137146115?spm = 1001.2014.3001.5501)

这个功能虽然简单，但在需要向全体用户传达重要信息的场景（如系统维护、版本更新、节假日通知）下，非常高效。

3.6. 菜单管理：构建系统的导航骨架与权限节点

在 3.1 节讲解 RBAC 模型时，我们已经初步接触了“菜单”作为“权限”载体的概念。然而，那只是从角色分配的角度去理解。本节，我们将 完全聚焦于“菜单管理”功能本身，以系统构建者和架构师的视角，深入学习如何通过它来 手动 规划、构建和维护整个应用的导航体系，并为每一个可操作的“点”精确地定义权限。

这项技能至关重要，因为在任何实际的二次开发中，无论是添加一个全新的业务模块，还是想调整现有功能的布局，亦或是将一个大页面拆分为多个子页面，“菜单管理”都是您必须操作的第一站。

3.6.1.深度解析菜单、目录与按钮

若依的“菜单管理”是将 前端视图（Component）、前端路由（Route） 和 后端权限（Permission） 进行统一声明和绑定的核心枢纽。其设计由三种不同类型的“菜单”构成，每种类型都有其精确的角色和核心配置。

A. 目录 (Directory)

“目录”扮演着纯粹的 “组织容器” 的角色，用于组织一组相关的菜单，形成清晰的导航层级。

B. 菜单 (Menu)

“菜单”是用户能与之交互、通往具体功能页面的 “真正入口”。

C. 按钮 (Button)

“按钮”是一种 “隐藏的权限节点”，专门用于定义页面内部的具体操作权限。

3.6.2. 实战案例：手动创建并重组“课程管理”模块

业务场景: 将“课程管理”模块从“系统工具”中移除，并放置到一个全新的、名为 “教学管理” 的顶级模块下。

• 第一步：创建新的顶级“目录” - 教学管理

  1. 导航: 系统管理 -> 菜单管理，点击 新增。
  2. 配置: 参照下表完成目录的关键信息配置。

• 第二步：创建“课程管理”页面“菜单”

  1. 清理: 先删除原“系统工具”下的“课程管理”相关菜单。
  2. 新增: 再次点击 新增。
  3. 配置: 参照下表完成菜单的关键信息配置。

• 第三步：为新菜单添加“按钮”权限

  1. 新增: 再次点击 新增。
  2. 配置: 参照下表，为“新增”操作创建按钮权限。

3. 重复操作: 参照上表，继续添加 修改 (course:course:edit)、删除 (course:course:remove) 等其他按钮权限。

• 第四步：验证成果

  1. 操作: 点击右上角头像 -> 清除缓存，然后强制刷新浏览器页面。
  2. 观察: 左侧菜单栏出现新的“教学管理”顶级目录，展开后可点击“课程管理”并正常访问。

通过这个手动配置的过程，您已经掌握了如何运用“三位一体”的模型，自由地构建和调整若依系统的功能布局与权限体系。

3.7. 部门管理：构建企业的组织架构树

在完成了对菜单和权限的精细化定义后，我们转向企业管理的另一个核心维度——组织架构。“部门管理”功能正是若依框架中用于构建和维护这一结构的基础模块。

3.7.1. 是什么：超越通讯录的组织核心

“部门管理”远不止是一个简单的“公司通讯录”或部门列表。它是一个以 树形结构 来定义企业内部组织层级的核心功能，为实现复杂的、基于组织汇报关系的管理需求提供了数据基础。

核心价值

部门管理本身只是一个组织结构的定义，但它的真正价值在于 与其他模块的联动，从而实现基于组织架构的数据权限控制和业务流程流转：

数据权限的背后原理

当一个角色被赋予了例如“本部门数据权限”后，若依的后端会通过 AOP 切面 在执行数据库查询时进行拦截。切面会获取当前登录用户的部门 ID，并 自动向正在执行的 SQL 语句动态拼接上 WHERE 条件（例如，AND u.dept_id = 103），从而在数据库层面就完成了数据的过滤，保证了数据权限的安全性与高效性。

他的最重要的用途是在 用户管理 页面提供筛选功能，可以通过筛选去查看不同部门的用户情况，

第四章. 系统监控：项目的健康仪表盘（非重要）

4.1. 在线用户：实时会话管理与安全控制

是什么？
“在线用户”功能提供了一个实时的会话监控界面，它展示了当前所有通过验证并活跃在系统中的用户会话列表。

核心价值:

• 实时监控: 管理员可以清晰地看到每个在线用户的 登录账号、所属部门、登录 IP、登录地点、浏览器类型 以及 操作系统。
• 安全强制下线: 提供了“强退”功能。当发现异常或可疑会话时（例如，某员工已离职但其账号仍在异地登录），管理员可以一键强制该用户下线，使其 Token 失效，从而立即终止其访问权限。

实战场景：处理异常登录会话

1. 模拟场景: 请您使用另一个浏览器（或浏览器的隐私模式），再次登录 admin 账户。现在，您的 admin 账户就拥有了两个独立的在线会话。
2. 导航与观察: 在第一个浏览器中，导航至 系统监控 -> 在线用户。您会在列表中看到两条 admin 用户的登录记录，它们的“会话编号”不同，可能登录 IP 也不同（如果使用了代理）。
3. 执行强退: 找到您在第二个浏览器中登录的那条会话记录，点击其右侧操作列的 强退 按钮。
4. 验证结果: 回到第二个浏览器，尝试点击任意菜单或刷新页面。您会发现系统会立即提示“登录状态已过期，请重新登录”，并跳转到登录页。这证明该会话已被成功终止。
   

4.2. 服务监控：洞悉服务器与 JVM 状态

是什么？
服务监控是一个集成的服务器运行时信息展示面板，它利用了 oshi 这个库来实时获取服务器底层的硬件和 JVM 的各项性能指标。

核心指标解读:

• CPU: 展示服务器 CPU 的核心数、系统使用率、用户使用率和当前空闲率。CPU 使用率持续过高 是系统性能瓶颈最直接的信号。
• 内存: 显示总物理内存、已用内存和剩余内存。内存使用持续接近上限 可能预示着内存泄漏或需要增加硬件资源。
• 服务器信息: 包括服务器名称、操作系统、IP 地址等。
• Java 虚拟机信息: 这是排查 Java 应用问题的关键区域。
  • 内存: 重点关注 “堆内存” 的使用情况（如 Max, Committed, Used）。如果 Used 内存持续增长而不回落，即使在应用空闲时也是如此，这通常是 内存泄漏（Memory Leak） 的典型特征。
  • 线程: 显示当前 JVM 的总线程数、守护线程数等。过多的线程数会消耗大量内存和 CPU 资源。

如何使用:
该页面提供的信息主要用于性能监控和问题诊断。当用户反馈系统卡顿或响应缓慢时，服务监控页面是运维人员首先需要查看的地方，以快速判断问题是出在 CPU、内存还是应用本身。

4.3. 缓存监控：深入 Redis 的世界

是什么？
缓存监控提供了一个对若依所使用的 Redis 缓存实例的详细信息的图形化展示界面。

核心价值:

• 基本信息: 展示 Redis 的版本、运行模式（单机/集群）、端口、运行时间等。
• 命令统计: 以图表形式展示 Redis 自启动以来执行过的各种命令（如 GET, SET, KEYS）的次数。这有助于分析应用的缓存使用模式。
• 内存信息: 显示 Redis 已使用的内存、内存峰值、内存碎片率等关键指标。已用内存持续增长 可能意味着存在缓存键没有设置过期时间（TTL）的问题。
• 键值统计: 展示当前 Redis 实例中存储的键（Key）的总数量，以及每个数据库（db0, db1, …）的键数量和过期键数量。

实战场景：检查登录 Token 缓存

1. 导航: 进入 系统监控 -> 缓存列表。
2. 观察键值统计: 在“键值统计”部分，您会看到 db0 中存在一定数量的 keys。这些键主要就是若依用来存储用户登录信息（LoginUser）的缓存，键的格式通常是 login_tokens:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。
3. 验证过期机制: 登录一个用户，然后观察 keys 数量增加。等待超过 Token 的有效期（默认为 30 分钟）后再次观察，理论上对应的 login_tokens: 键应该会被 Redis 自动清除。

4.4. 数据监控：你的 SQL 性能优化利器

是什么？
数据监控实际上是阿里巴巴著名的数据库连接池项目 Druid 自带的监控后台。若依巧妙地将其内嵌到了自己的管理界面中。

核心功能:

• 数据源信息: 显示数据库连接池的详细状态，如活动连接数、空闲连接数、最大连接数等。如果 活动连接数持续接近最大值，说明数据库连接可能成为瓶颈。
• SQL 监控: 这是最有价值的功能。它会记录并分析应用执行过的每一条 SQL 语句的性能。
  • 执行最长: 按执行耗时排序，可以快速定位到系统中性能最差的“慢 SQL”。
  • 执行次数最多: 按执行次数排序，有助于找到最频繁被调用的 SQL，这些 SQL 即使单次执行不慢，高频调用也可能造成性能问题。
  • 错误次数最多: 快速定位到执行出错的 SQL。
• URL 监控 / Spring 监控: 从不同维度分析应用的接口性能。

实战场景：定位慢查询

1. 导航与登录: 进入 系统监控 -> 数据监控。首次访问需要登录，默认账号密码是 ruoyi / 123456（可在 application.yml 中修改）。
2. 访问 SQL 监控: 在 Druid 后台，点击左侧的 SQL 监控。
3. 执行操作: 回到若依主界面，多次访问“课程管理”页面并执行几次查询操作。
4. 分析 SQL: 刷新 Druid 的“SQL 监控”页面。您会在列表中看到类似 SELECT count(0) FROM tb_course WHERE ... 和 SELECT ... FROM tb_course WHERE ... LIMIT ... 的 SQL 语句。点击任意一条 SQL，可以查看其详细的执行计划、耗时分布等信息。如果某条 SQL 执行时间过长，这里就是您开始进行数据库优化的起点。

第五章. 架构解构：浅析若依的“五脏六腑”

5.1. 后端架构：多模块的职责与协同

5.1.1.浅析设计哲学

我们初次用 IDE 打开若依的后端项目时，普遍会产生一个困惑：为什么不把所有代码都放在一个项目里？ruoyi-admin、ruoyi-common、ruoyi-system 等如此多的模块，它们各自的作用是什么？

这个问题的答案，根植于现代软件工程的核心设计原则——“分层架构”。对于一个企业级的、功能复杂的应用而言，将所有代码堆砌在一起会迅速导致项目变得难以维护、难以理解、难以扩展。若依的多模块（Multi-Module）架构正是为了解决这一难题而设计的。

我们将这种设计哲学带来的核心优势归纳为以下四点：

• 高内聚、低耦合
  “内聚”指模块内部的各个元素（类、方法）联系的紧密程度，“耦合”则指模块与模块之间的依赖程度。一个优秀的架构追求高内聚、低耦合。在若依中，ruoyi-system 模块只包含用户、角色、菜单等核心系统功能的代码（高内聚），而它与 ruoyi-quartz（定时任务）模块之间没有直接的依赖关系（低耦合）。这使得我们在修改系统管理功能时，完全不必担心会影响到定时任务的逻辑。

• 职责分离
  每个模块都有其清晰、单一的职责。ruoyi-framework 只负责框架层面的配置与支撑（如安全、数据源），ruoyi-common 只提供全局通用的工具与实体。这种清晰的边界划分，使得我们遇到问题时，能够快速定位到应该检查哪个模块，极大地提升了开发和排错效率。

• 可复用性
  模块化设计天然地促进了代码复用。例如，ruoyi-common 模块作为一个通用的工具包，它不依赖任何具体的业务。我们可以轻易地将其打包，并应用到公司内部的任何其他 Java 项目中，而无需进行任何修改。

• 按需裁剪
  并非所有项目都需要若依的全部功能。例如，如果我们的项目不需要代码生成或定时任务，我们可以直接在主模块 ruoyi-admin 的 pom.xml 中移除对 ruoyi-generator 和 ruoyi-quartz 的依赖。这样，这两个模块的功能就不会被打包到最终的可执行文件中，使得我们的应用更加轻量。

5.1.2. 核心模块地图：职责与定位

为了让大家对若依的后端结构形成一个清晰的“模块地图”，我们用表格的形式，为每个核心模块定义其精确的“角色卡”。当您看到某个模块名时，大脑中应能立刻浮现出它的核心职责。

5.1.3. 依赖关系解密：Maven 如何协同工作

我们已经理解了每个模块的独立职责，现在需要探究它们是如何通过 Maven 这一构建工具，被有机地组织在一起协同工作的。

首先，我们通过中这一章依赖关系图，直观地感受一下这种组织结构。

这张图清晰地展示了一个“思维导图”式的分层结构。ruoyi-admin 在最顶层，依赖所有其他模块；ruoyi-common 在最底层，被所有模块依赖。这一切都由 pom.xml 文件精确定义。

我们将这个过程分为两步来理解：版本管理 与 依赖声明。

• 第一步：父工程的“版本管理中心” - <dependencyManagement>
  在多模块项目中，最大的挑战之一是保证所有模块使用的第三方依赖版本是一致的。如果 ruoyi-system 使用了 fastjson-2.0.50，而 ruoyi-framework 却使用了 fastjson-2.0.58，就可能引发难以预料的兼容性问题。为了解决这个问题，若依在最顶层的父工程 pom.xml 中使用了 <dependencyManagement> 标签。它的作用就像一个“版本管理中心”，它只 声明 依赖的版本，但 不实际引入。

  文件路径: [项目根目录]/pom.xml

  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 42 43 44 45 46

  <!-- 依赖声明 --> <dependencyManagement> <dependencies> <!-- SpringBoot的依赖配置--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-dependencies</artifactId> <version>3.5.4</version> <type>pom</type> <scope>import</scope> </dependency> <!-- 阿里数据库连接池 --> <dependency> <groupId>com.alibaba</groupId> <artifactId>druid-spring-boot-3-starter</artifactId> <version>${druid.version}</version> </dependency> <!-- ... 其他第三方依赖的版本声明 ... --> <!-- 核心模块--> <dependency> <groupId>com.ruoyi</groupId> <artifactId>ruoyi-framework</artifactId> <version>${ruoyi.version}</version> </dependency> <!-- 系统模块--> <dependency> <groupId>com.ruoyi</groupId> <artifactId>ruoyi-system</artifactId> <version>${ruoyi.version}</version> </dependency> <!-- 通用工具--> <dependency> <groupId>com.ruoyi</groupId> <artifactId>ruoyi-common</artifactId> <version>${ruoyi.version}</version> </dependency> </dependencies> </dependencyManagement>

在这里，所有依赖（包括若依自身的模块）的版本都被统一管理。子模块在引入这些依赖时，将无需再指定版本号，Maven 会自动从父工程的“版本仲裁中心”获取。

• 第二步：子模块的“依赖声明” - <dependencies>
  当父工程定义好版本后，子模块就可以按需、清晰地声明自己需要哪些模块和工具了。我们以 ruoyi-admin 为例，它是整个应用的“组装车间”。

  文件路径: ruoyi-admin/pom.xml

  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

  <dependencies> <!-- spring-boot-devtools --> <dependency> <groupId> org.springframework.boot </groupId> <artifactId> spring-boot-devtools </artifactId> <optional> true </optional> <!-- 表示依赖不会传递 --> </dependency> <!-- spring-doc --> <dependency> <groupId> org.springdoc </groupId> <artifactId> springdoc-openapi-starter-webmvc-ui </artifactId> </dependency> <!-- Mysql驱动包 --> <dependency> <groupId> com.mysql </groupId> <artifactId> mysql-connector-j </artifactId> </dependency> <!-- 核心模块--> <dependency> <groupId> com.ruoyi </groupId> <artifactId> ruoyi-framework </artifactId> </dependency> <!-- 定时任务--> <dependency> <groupId> com.ruoyi </groupId> <artifactId> ruoyi-quartz </artifactId> </dependency> <!-- 代码生成--> <dependency> <groupId> com.ruoyi </groupId> <artifactId> ruoyi-generator </artifactId> </dependency> </dependencies>

  我们注意到，ruoyi-admin 在引入 ruoyi-framework、ruoyi-quartz 等模块时，只提供了 groupId 和 artifactId，完全没有 <version> 标签。这正是 <dependencyManagement> 发挥作用的结果。这种做法极大地简化了子模块的 pom.xml，并从根本上保证了整个项目的版本一致性。

5.1.4. ruoyi-common 深度剖析：通用能力的基石

我们首先将目光投向整个项目架构的最底层——ruoyi-common 模块。如果说 ruoyi-admin 是应用的“大脑”，那么 ruoyi-common 就是为整个身体提供基础营养和工具的“循环系统”。它被所有其他模块依赖，其核心定位是：提供独立于任何具体业务的、全局通用的工具类、核心实体定义与常量。

我们不必要深入分析这些提供好的工具类，而是深入其最核心的 core 包，通过“渐进式构建”的方式，来理解若依是如何通过它来解决开发中的普遍痛点的。

• core 包：核心抽象与封装
  此包是 ruoyi-common 的心脏。我们首先聚焦于 controller.BaseController，因为它是我们二次开发中接触最频繁、感受最直接的类。

  痛点场景: 设想一下，如果没有 BaseController，我们为“课程管理”编写一个分页查询方法，可能需要这样做：

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

  // 一个没有继承 BaseController 的、重复繁琐的 Controller 示例 @RestController public class CourseController { @GetMapping("/list") public Map<String, Object> list(HttpServletRequest request) { // 1. 手动从 request 获取分页参数 int pageNum = Integer.parseInt(request.getParameter("pageNum")); int pageSize = Integer.parseInt(request.getParameter("pageSize")); // 2. 手动启动分页 PageHelper.startPage(pageNum, pageSize); List<Course> list = courseService.selectCourseList(); PageInfo<Course> pageInfo = new PageInfo<>(list); // 3. 手动封装成前端需要的格式 Map<String, Object> result = new HashMap<>(); result.put("code", 200); result.put("msg", "查询成功"); result.put("rows", list); result.put("total", pageInfo.getTotal()); return result; } }

  我们能看到大量的“样板代码”：手动解析参数、手动封装返回结果。每个需要分页的查询方法都这么写，无疑是一场灾难。若依的 BaseController 正是为了根除这些痛点而设计的。现在，我们来逐步拆解它的核心能力。

  能力一：无感分页 startPage()
  首先，BaseController 承诺开发者无需再关心分页参数的获取。

  1 2 3 4 5 6 7 8 9

  // BaseController.java 的部分代码 /** * 设置请求分页数据 */ protected void startPage() { // 内部调用了 PageUtils 工具类，封装了从请求中获取参数的细节 PageUtils.startPage(); }

  • 逐行讲解: 这一行代码的背后，PageUtils.startPage() 会自动从 HttpServletRequest 中查找 pageNum 和 pageSize 等参数，并调用 MyBatis PageHelper 插件的 PageHelper.startPage() 方法。
  • 核心原理: PageHelper 的核心是利用 ThreadLocal 变量。当 startPage() 被调用时，分页参数会被存入当前线程的 ThreadLocal 中。随后，当这个线程执行 MyBatis 查询时，PageHelper 的拦截器会从 ThreadLocal 中取出分页参数，并自动地、动态地改写即将执行的 SQL 语句，为其加上 LIMIT 子句。这正是“无感分页”的魔力所在。

  能力二：标准表格数据封装 getDataTable()
  解决了分页，BaseController 接着解决了响应封装的痛点。

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

  // BaseController.java 的部分代码 /** * 响应请求分页数据 */ @SuppressWarnings({ "rawtypes", "unchecked" }) protected TableDataInfo getDataTable(List<?> list) { TableDataInfo rspData = new TableDataInfo(); rspData.setCode(HttpStatus.SUCCESS); rspData.setMsg("查询成功"); rspData.setRows(list); // 关键之处：从分页结果中获取总记录数 rspData.setTotal(new PageInfo(list).getTotal()); return rspData; }

  • 逐行讲解: 这个方法接收一个 List（这正是 PageHelper 分页查询后返回的、只包含当前页数据的列表）。它创建了一个 TableDataInfo 对象，并设置了标准的状态码和消息。最关键的一行是 rspData.setTotal(new PageInfo(list).getTotal())，PageHelper 在执行分页查询后，会将总记录数也存放在一个 Page 对象中，new PageInfo(list) 正是用于从中提取出这个总记录数。

• 实战价值: 通过 startPage() + getDataTable() 的组合，我们将之前那个繁琐的 Controller 方法，简化为了优雅的三行代码，这在 5.4 节 会有更详细的实战。

  能力三：统一操作结果响应 toAjax()
  对于增、删、改操作，我们通常关心的是“操作是否成功”。BaseController 为此提供了极致的便利。

  1 2 3 4 5 6 7 8 9 10 11

  // BaseController.java 的部分代码 /** * 响应返回结果 * * @param rows 影响行数 * @return 操作结果 */ protected AjaxResult toAjax(int rows) { return rows > 0 ? AjaxResult.success() : AjaxResult.error(); }

  • 逐行讲解: Service 层的增删改方法通常返回一个 int 型的受影响行数。在 Controller 中，我们只需将这个 int 值传入 toAjax() 方法。这个方法通过一个简单的三元表达式，就将一个纯粹的技术性返回值（受影响行数），转换成了一个对前后端都有明确业务含义的 AjaxResult 对象（成功或失败）。这种封装，让我们的 Controller 代码不仅简洁，而且表意更加清晰。

通过对 BaseController 核心能力的“渐进式”剖析，我们已经深入理解了 ruoyi-common 的设计精髓。除了 BaseController，core.domain 包下的 AjaxResult（统一响应契约）、BaseEntity（通用字段基类），以及 exception（统一异常处理）、utils（静态工具库）和 annotation（AOP 注解）等包，共同构成了这个强大而可靠的项目基石。

5.1.5. ruoyi-framework 剖析：应用的骨架与安全中枢

如果说 ruoyi-common 是项目的“循环系统”，那么 ruoyi-framework 就是支撑整个应用的“底层骨架”与“安全系统”。它不包含任何具体业务逻辑，其核心职责是整合并配置 Spring Boot、Spring Security 等核心框架，为上层业务（如 ruoyi-system）提供一个稳定、安全、可依赖的运行环境。

我们将聚焦于其最重要的两个部分：config（框架配置）与 security（安全实现），来理解这个“骨架”是如何搭建起来的。

• config 包：框架级配置中心
  此包是若依对所有第三方框架进行集中配置的地方。我们重点剖析其心脏——SecurityConfig.java。

  痛点场景: 在一个没有框架封装的 Spring Security 项目中，我们需要编写大量冗长的 XML 或 Java 配置来定义每一个 URL 的访问权限、指定登录页面、配置 session 策略、处理 CSRF 防护等等。这个过程极其繁琐且容易出错。SecurityConfig.java 的目的，就是将这些复杂的配置，用一种清晰、结构化的方式组织起来。

  我们来“渐进式”地解读 SecurityConfig.java 的核心配置流程。

  第一步：开启方法级安全注解

  1 2 3 4 5 6 7

  // SecurityConfig.java 的起始部分 @EnableMethodSecurity(prePostEnabled = true, securedEnabled = true) @Configuration public class SecurityConfig { // ... }

• 逐行讲解: @EnableMethodSecurity(prePostEnabled = true) 是整个若依权限体系的“总开关”。正是这个注解，激活了 Spring Security 对 @PreAuthorize 注解（我们在第三章使用过的）的解析能力。一旦开启，Spring AOP 就会为所有标记了 @PreAuthorize 的方法创建一个代理，在方法执行前，检查当前用户的权限是否满足注解中定义的表达式（如 @ss.hasPermi('course:course:list')）。

  第二步：构建核心过滤器链 filterChain()
  这是安全配置的核心，它像一个“安检流水线”，定义了所有 HTTP 请求需要经过哪些安全检查站。

  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

  a // SecurityConfig.java 的核心方法 @Bean protected SecurityFilterChain filterChain(HttpSecurity httpSecurity) throws Exception { return httpSecurity // CSRF 禁用，因为我们是前后端分离，通过 token 认证，不依赖 session 和 cookie .csrf(csrf -> csrf.disable()) // ... 其他基础配置 ... // 基于 token，所以不需要 session，设置为无状态 .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) // 配置 URL 的访问权限 .authorizeHttpRequests((requests) -> { // 允许匿名访问的路径，通常由配置文件读取 permitAllUrl.getUrls().forEach(url -> requests.requestMatchers(url).permitAll()); // 硬编码的匿名访问路径，如登录、注册、获取验证码 requests.requestMatchers("/login", "/register", "/captchaImage").permitAll() // 除上面外的所有请求，全部需要经过身份认证 .anyRequest().authenticated(); }) // ... 添加自定义过滤器 ... .build(); }

  • 逐行讲解:
    • .csrf(csrf -> csrf.disable()): 在前后端分离的架构中，认证信息通过 Authorization 头中的 Token 传递，不依赖于浏览器的 Cookie-Session 机制，因此传统的 CSRF（跨站请求伪造）攻击方式不再适用，可以安全地禁用它。
    • .sessionManagement(...STATELESS): 明确告诉 Spring Security，我们的应用是“无状态”的，服务端不会创建或维护任何 HttpSession，每次请求都将独立认证。这是构建可伸缩、高性能服务的关键。
      • .authorizeHttpRequests(...): 这是 URL 权限配置的核心。若依采用“白名单”策略：先通过 permitAll() 方法，明确定义哪些路径（如登录页、静态资源）无需认证即可访问；然后通过 .anyRequest().authenticated()，规定 除此之外的所有其他请求 都必须经过身份认证。

• security 包：安全机制的具体实现
  SecurityConfig 搭建了骨架，而 security 包则为这个骨架填充了“血肉”。我们重点关注 filter.JwtAuthenticationTokenFilter，它是若依 Token 认证机制的“心脏”。

  痛点场景: SecurityConfig 只规定了“哪些请求需要认证”，但并没有说明“如何进行认证”。JwtAuthenticationTokenFilter 的职责，就是在每个需要认证的请求到达时，执行具体的 Token 校验和用户身份构建工作。

  doFilterInternal() 方法的执行流程:

  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

  // JwtAuthenticationTokenFilter.java 的核心方法 @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { // 1. 从请求中获取 LoginUser 对象（TokenService 内部会解析请求头中的 Token） LoginUser loginUser = tokenService.getLoginUser(request); // 2. 判断用户是否存在，且当前上下文中没有认证信息 if (StringUtils.isNotNull(loginUser) && StringUtils.isNull(SecurityUtils.getAuthentication())) { // 3. 验证 Token 有效性（例如，检查是否过期） tokenService.verifyToken(loginUser); // 4. 构建一个代表当前用户的认证成功的令牌（AuthenticationToken） UsernamePasswordAuthenticationToken authenticationToken = new UsernamePasswordAuthenticationToken(loginUser, null, loginUser.getAuthorities()); authenticationToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request)); // 5. 将这个令牌存入 SecurityContextHolder，完成认证 // 后续的 Spring Security 组件（如 AOP 注解）就可以从这里获取到当前用户信息了 SecurityContextHolder.getContext().setAuthentication(authenticationToken); } // 6. 放行请求，让它继续走向 Controller chain.doFilter(request, response); }

  • 核心原理: 这个过滤器继承自 OncePerRequestFilter，确保在一次请求中只执行一次。它的核心逻辑是：
    1. 调用 TokenService 从请求的 Authorization 头中解析出 JWT。
    2. 如果解析成功并获取到 LoginUser（代表用户已登录且 Token 有效），并且当前 SecurityContextHolder 中是空的（说明这是本次请求的第一次认证）。
    3. 它会创建一个 UsernamePasswordAuthenticationToken 对象，这个对象是 Spring Security 内部用来表示“一个已认证用户”的标准凭证。
    4. 最后，它将这个凭证放入 SecurityContextHolder 这个线程绑定的“全局容器”中。一旦 SecurityContextHolder 中有了认证信息，后续的所有安全检查（比如 @PreAuthorize 注解）就都可以从中获取到当前用户的身份和权限，从而做出正确的决策。

通过对 ruoyi-framework 的剖析，我们理解了若依是如何利用 Spring Security 构建起一个强大的、基于 Token 的、无状态的安全体系的。这套体系既保证了应用的安全性，又为二次开发提供了清晰的扩展点。

5.1.6. ruoyi-system 剖析：内置核心业务的“示范样本”

在理解了底层的工具与框架模块后，我们现在聚焦于真正承载 业务逻辑 的 ruoyi-system 模块。我们必须明确其定位：它并 不是 一个框架或工具模块，而是若依 内置核心业务 的实现模块。它本身就是一个标准的、自包含的业务模块范例，是我们在进行二次开发时最好的“活教材”和“最佳实践参考”。

ruoyi-system 的代码组织结构

痛点场景: 当我们准备进行二次开发，想要添加一个新的业务模块（例如“订单管理”）时，最常问的问题是：“我的代码应该如何组织？domain、service、mapper 应该怎么写？”

ruoyi-system 模块通过其清晰的目录结构，给出了这个问题的标准答案。

1
2
3
4
5
6
7
8
9
10
11
12
13

. 📂 ruoyi-system
└── 📂 src/
   ├── 📂 main/
   │   ├── 📂 java/
   │   │   └── .../system/
   │   │       ├── 📂 domain/  // 业务实体定义层
   │   │       ├── 📂 mapper/  // 数据访问接口层
   │   │       └── 📂 service/  // 业务逻辑核心层
   │   │           └── 📂 impl/ // 业务逻辑实现
   │   └── 📂 resources/
   │       └── 📂 mapper/
   │           └── 📂 system/  // MyBatis XML 文件
   ...

这是一种经典且高效的三层架构实现：

1. domain 层：业务实体的定义

   • 职责: 此目录下的 Java 类（如 SysUser.java, SysRole.java）是业务领域模型的实体映射。它们是纯粹的数据载体（POJO），负责定义业务对象的属性，与数据库表结构一一对应。

2. mapper 层：数据访问的接口与实现

   • 职责: 此层是与数据库打交道的 唯一 入口，实现了数据访问与上层业务逻辑的彻底隔离。
     • mapper/ 目录下的 Java 接口（如 SysUserMapper.java）定义了所有数据库操作的方法签名。
     • resources/mapper/system/ 目录下的 XML 文件（如 SysUserMapper.xml）则通过 MyBatis 的 SQL 标签，编写了这些接口方法对应的具体 SQL 语句。

3. service 层：业务逻辑的核心

   • 职责: 如果说 mapper 层执行的是“原子操作”（单次数据库交互），那么 service 层就是负责编排这些原子操作，来完成一个完整、复杂的业务功能的“指挥官”。
     • service/ 目录下的接口（如 ISysUserService.java）定义了业务层需要对外提供的能力契约。
     • service/impl/ 目录下的实现类（如 SysUserServiceImpl.java）则是业务规则、事务管理、缓存处理、权限校验等复杂逻辑的真正所在地。

为了具体地理解 Service 层是如何“指挥”和“编排”的，我们深入到 SysUserServiceImpl.java 中，通过其 insertUser 方法，来观察一个“新增用户”功能的完整实现过程。

痛点场景: 一个看似简单的“新增用户”功能，背后其实隐藏着多个业务步骤和规则：不仅要插入用户基本信息，还要建立用户与岗位、用户与角色的关联关系，并且这一切操作必须保证 事务性——要么全部成功，要么全部失败。

SysUserServiceImpl.java 中的 insertUser 方法完美地展示了如何处理这种复杂场景。

第一步：事务管理与方法签名

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// SysUserServiceImpl.java 的部分代码
@Service
public class SysUserServiceImpl implements ISysUserService
{
    // ... 注入多个 Mapper ...
    @Autowired
    private SysUserMapper userMapper;
    @Autowired
    private SysUserRoleMapper userRoleMapper;
    @Autowired
    private SysUserPostMapper userPostMapper;

    /**
     * 新增保存用户信息
     * 
     * @param user 用户信息
     * @return 结果
     */
    @Override
    @Transactional // <- 核心注解：声明此方法为一个事务
    public int insertUser(SysUser user)
    {
        // ... 方法体 ...
    }

• 逐行讲解: @Transactional 注解是 Spring 提供的声明式事务管理。一旦标记在此方法上，Spring AOP 会为它创建一个代理。在方法开始执行前，代理会自动开启一个数据库事务；如果方法成功执行完毕，事务会自动提交；如果方法在执行过程中抛出任何运行时异常，事务会自动回滚。这确保了“新增用户”操作的原子性。

第二步：编排多个 Mapper 完成核心业务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// insertUser 方法的核心逻辑
@Override
@Transactional
public int insertUser(SysUser user)
{
    // 第 1 步：调用 userMapper，插入用户基本信息到 sys_user 表
    int rows = userMapper.insertUser(user);
    
    // 第 2 步：调用内部方法，处理用户与岗位的关联关系
    insertUserPost(user);
    
    // 第 3 步：调用内部方法，处理用户与角色的关联关系
    insertUserRole(user);
    
    return rows;
}

• 逐行讲解: 这里清晰地展示了 Service 层的“编排”职责。它没有自己编写任何 SQL，而是像指挥官一样，依次调用三个不同的 Mapper（或封装了 Mapper 调用的内部方法）来协同完成任务：
  1. userMapper.insertUser(user): 完成最基础的用户信息持久化。
  2. insertUserPost(user): 内部会调用 userPostMapper，将用户 ID 和岗位 ID 批量插入到 sys_user_post 关联表中。
  3. insertUserRole(user): 内部会调用 userRoleMapper，将用户 ID 和角色 ID 批量插入到 sys_user_role 关联表中。

这三个步骤被 @Transactional 注解紧密地包裹在一个事务中，共同构成了一个不可分割的业务单元。

通过对 ruoyi-system 模块的结构与核心代码的深度剖析，我们不仅理解了若依内置功能的实现方式，更重要的是，我们掌握了一套可以在自己二次开发中直接应用的、标准的、健壮的业务分层与代码组织范式。

5.1.7. ruoyi-admin 剖析：应用的入口与配置中心

我们终于来到了项目架构的最顶层——ruoyi-admin 模块。如果说其他模块是各司其职的“零部件”，那么 ruoyi-admin 就是将所有零部件最终组装起来的“总装车间”和“主控制台”。它扮演着两个至关重要的角色：应用启动入口 和 全局配置中心。

1. 应用启动入口
   这是 ruoyi-admin 最核心的职责。应用的“点火”操作，正是在这个模块中完成的。

   文件路径: ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

   package com.ruoyi; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration; /** * 启动程序 * * @author ruoyi */ @SpringBootApplication(exclude = { DataSourceAutoConfiguration.class }) public class RuoYiApplication { public static void main(String[] args) { SpringApplication.run(RuoYiApplication.class, args); // ... 打印启动成功 banner ... } }

2. Controller 聚合器与业务暴露层
   正如 ruoyi-admin 的目录结构所示，它内部的 web/controller 目录聚合了来自不同模块的 Controller，是所有 HTTP 请求的统一入口。

   • system 包下的 Controller（如 SysUserController）负责暴露 ruoyi-system 模块的业务接口。
   • monitor 包下的 Controller（如 ServerController）负责暴露系统监控相关的接口。
   • 我们自己生成的 course 包下的 Controller，也自然地归属在这里。

ruoyi-admin 的配置中心体系

ruoyi-admin 的 src/main/resources 目录，是整个应用的 主配置中心，存放了所有与应用运行相关的配置文件。

• application.yml：主配置文件
  这是应用的核心配置文件，采用 YAML 格式，层级清晰。它定义了应用的基础行为。我们重点解读几个核心配置：

  在传统 Spring 项目中，我们需要编写大量 XML 来配置端口、上下文路径、Redis 连接等。application.yml 通过“约定优于配置”的思想，极大地简化了这些工作。

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

  # 开发环境配置 server: # 服务器的HTTP端口，默认为8080 port: 8080 servlet: # 应用的访问路径 context-path: / # Spring配置 spring: # redis 配置 redis: # 地址 host: localhost # 端口，默认为6379 port: 6379

  这种声明式的配置方式直观易懂。Spring Boot 在启动时会自动读取这些配置，并应用到相应的组件中。例如，server.port: 8080 会直接配置内嵌的 Tomcat 服务器监听 8080 端口。

• application-{profile}.yml：环境分离的艺术
  我们注意到还有一个 application-druid.yml 文件。这是 Spring Boot Profiles（环境配置） 功能的体现。

  在 application.yml 中有这样一行配置：

  1 2 3

  spring: profiles: active: druid

  • 核心原理: 这一行配置告诉 Spring Boot：“在加载主配置文件 application.yml 之后，请继续加载名为 application-druid.yml 的配置文件”。application-druid.yml 中的配置项会 覆盖 主配置文件中的同名项。
  • 实战价值: 这种机制在多环境部署（如开发 dev、测试 test、生产 prod）时至关重要。我们可以创建 application-dev.yml, application-prod.yml 等文件，在其中定义不同环境下的数据库地址、Redis 地址等。部署时，只需通过启动参数（如 -Dspring.profiles.active=prod）来切换环境，而无需修改任何代码或配置文件本身。

通过对 ruoyi-admin 模块的剖析，我们理解了它作为“总装车间”和“主控制台”的核心地位。它不仅是应用的启动入口，更是所有模块 Controller 的聚合点和所有配置文件的管理中心，将整个多模块项目有机地融为一体。

5.2. 前端架构：项目结构与核心文件导览

5.2.1. 工程化基石：.env 环境配置与 package.json 依赖蓝图

在深入若依前端的源码之前，我们必须先理解其工程化的两大基石：用于管理多环境配置的 .env 文件体系，以及定义项目依赖与脚本的 package.json。它们共同决定了项目的构建行为和运行环境。

.env 环境配置：构建不同环境的“配置文件”

痛点场景: 在软件开发中，开发、测试、生产环境的 API 地址、应用标题等配置通常是不同的。如果将这些配置硬编码在代码中，每次部署都需要手动修改，极其繁琐且容易出错。

若依采用了 Vite 支持的 .env 文件体系来优雅地解决此问题。在项目根目录下，我们可以看到三个核心的 .env 文件：

• .env.development: 开发环境配置文件

  1 2 3 4 5 6 7 8

  # 页面标题 VITE_APP_TITLE = 若依管理系统 # 开发环境配置 VITE_APP_ENV = 'development' # API 请求基础路径(用于代理) VITE_APP_BASE_API = '/dev-api'

• .env.production: 生产环境配置文件

  1 2 3 4 5 6 7 8

  # 页面标题 VITE_APP_TITLE = 若依管理系统 # 生产环境配置 VITE_APP_ENV = 'production' # API 请求基础路径 VITE_APP_BASE_API = '/prod-api'

• .env.staging: 预发布（测试）环境配置文件

  1 2 3 4 5 6 7 8

  # 页面标题 VITE_APP_TITLE = 若依管理系统 # 预发布环境配置 VITE_APP_ENV = 'staging' # API 请求基础路径 VITE_APP_BASE_API = '/stage-api'

核心工作机制:
这个体系的核心在于 package.json 中的 scripts 命令与 Vite 的构建模式（mode）相结合。

1
2
3
4
5
6

// package.json
"scripts": {
  "dev": "vite", // 默认 mode 为 'development'
  "build:prod": "vite build --mode production", // 显式指定 mode 为 'production'
  "build:stage": "vite build --mode staging", // 显式指定 mode 为 'staging'
},

• 工作流剖析:
  1. 当我们执行 pnpm dev 时，Vite 会自动加载 .env.development 文件。
  2. 当我们执行 pnpm build:prod 时，--mode production 参数会告诉 Vite 去加载 .env.production 文件。
  3. Vite 会将这些文件中以 VITE_ 开头的变量，注入到一个名为 import.meta.env 的全局环境变量对象中。
  4. 在项目的任何地方（如 request.js 中），我们都可以通过 import.meta.env.VITE_APP_BASE_API 来获取当前环境对应的 API 基础路径。

通过这种方式，若依实现了配置与代码的完全分离，使得一次构建、多环境部署成为可能。

package.json：项目的“依赖蓝图”与“脚本中心”

package.json 文件是前端项目的“心脏”，它详细描述了项目的构成。我们将其核心内容归纳为两部分：依赖蓝图和脚本中心。

• 依赖蓝图 (dependencies & devDependencies)
  若依 Vue3 版精心选择了一系列高质量的第三方库来构建其功能。我们将核心依赖按其作用进行分类归纳：

• 脚本中心 (scripts)
  scripts 字段定义了项目的标准工作流命令。

  1 2 3 4 5 6

  "scripts": { "dev": "vite", "build:prod": "vite build --mode production", "build:stage": "vite build --mode staging", "preview": "vite preview" },

  • dev: 启动开发服务器，用于日常开发和调试。
  • build:prod: 执行生产环境打包。此命令会读取 .env.production，并对代码进行压缩、混淆、Tree-shaking 等优化，生成用于线上部署的静态文件。
  • build:stage: 执行预发布环境打包，读取 .env.staging。
  • preview: 在本地预览打包后的生产环境产物，用于部署前的最后检查。

通过对 .env 文件体系和 package.json 的深度剖析，我们理解了若依前端项目是如何管理多环境配置，以及如何组织和构建其庞大的依赖体系的。这为我们后续深入源码打下了坚实的基础。

5.2.2. vite.config.js 深度剖析：项目的“构建总管”

在理解了 .env 和 package.json 如何定义项目的环境与依赖后，我们现在聚焦于驱动这一切运转的“引擎室”——vite.config.js。此文件是 Vite 的主配置文件，负责项目的开发服务器、打包构建、插件集成等所有核心行为。

如果说 package.json 定义了“用什么工具”，那么 vite.config.js 则详细规定了“如何使用这些工具”。它是 Vite 的主配置文件，负责开发服务器、项目打包、插件集成等所有行为。

文件路径: [项目根目录]/vite.config.js

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

import { defineConfig, loadEnv } from 'vite'
import path from 'path'
import createVitePlugins from './vite/plugins'

// https://vitejs.dev/config/
export default defineConfig(({ mode, command }) => {
  const env = loadEnv(mode, process.cwd())
  const { VITE_APP_ENV } = env
  return {
    // ...
    plugins: createVitePlugins(env, command === 'build'),
    resolve: {
      alias: {
        // 设置别名
        '@': path.resolve(__dirname, './src')
      },
    },
    server: {
      port: 80,
      host: true,
      open: true,
      proxy: {
        // https://cn.vitejs.dev/config/#server-proxy
        '/dev-api': {
          target: 'http://localhost:8080',
          changeOrigin: true,
          rewrite: (p) => p.replace(/^\/dev-api/, '')
        },
      }
    },
    // ...
  }
})

渐进式解读

plugins: Vite 的核心优势之一在于其插件化的生态系统。若依将所有 Vite 插件的配置都收敛到了 vite/plugins 目录中，并通过 createVitePlugins 函数统一引入。例如，vite/plugins/svg-icon.js 插件负责将 src/assets/icons/svg 目录下的所有 SVG 图标文件，自动处理成可在 Vue 组件中直接使用的图标组件。这种插件化机制使得 vite.config.js 保持了高度的整洁。

resolve.alias: 这是提升开发效率的关键配置。'@': path.resolve(__dirname, './src') 这一行定义了一个路径别名，意味着在项目的任何地方，我们都可以使用 @ 来代替冗长的相对路径（如 ../../..），直接指向 src 目录。这使得代码中的模块导入语句更加清晰和易于维护。

server.proxy: 这是解决开发环境跨域问题的核心。

首先，我们必须理解其解决的痛点：前端开发服务器运行在 80 端口，而后端 API 在 8080 端口，这构成了浏览器安全策略中的“跨域”，直接访问会被阻止。

若依的解决方案如下：

1
2
3
4
5

'/dev-api': {
  target: 'http://localhost:8080',
  changeOrigin: true,
  rewrite: (p) => p.replace(/^\/dev-api/, '')
}

这段配置的含义是：

• 拦截规则
  Vite 开发服务器会监听所有由前端发起的请求。如果请求的 URL 以 /dev-api 开头，则触发此代理规则。

• 目标服务器
  Vite 会将这个被拦截的请求转发给 target 指定的地址，即 http://localhost:8080。

• changeOrigin: true
  在转发时，将请求头中的 Host 字段从当前的前端地址（如 localhost:80）修改为目标服务器的地址。这是确保后端能正确处理请求的关键。

• rewrite
  在将请求真正发送给后端之前，使用 rewrite 函数重写 URL，将 /dev-api 前缀去掉。例如，前端请求 /dev-api/system/user/list，最终到达后端的将是 /system/user/list。

通过对这两个核心文件的剖析，我们理解了若依前端项目是如何通过 package.json 管理依赖，并通过 vite.config.js 进行高效、灵活的工程化配置，为快速开发奠定了坚实的基础。

5.2.3. 项目目录结构与核心文件导览

在理解了若依前端的工程化基础设施后，我们现在需要从整体上把握项目的目录组织架构。一个清晰的目录结构，不仅能让开发者快速定位代码位置，更体现了项目的设计思想和分层理念。

痛点场景: 面对一个拥有数百个文件的前端项目，如果没有清晰的目录规范，开发者往往会陷入 “找不到代码在哪”、“不知道该把新功能写在哪” 的困境。若依通过精心设计的目录结构，将不同职责的代码严格分离，实现了高内聚、低耦合的架构目标。

5.2.3.1. 项目目录树：清晰的分层架构

若依 Vue3 版采用了标准的 Vue 3 + Vite 项目结构，在 src/ 目录下按功能模块进行了精细化分层。以下是核心目录结构的可视化展示：

5.2.3.2. 核心目录职责解析

若依的目录设计遵循了 按职责分层、按业务分模块 的原则。我们将各目录的核心职责归纳如下：

设计亮点：

• API 层与视图层分离：api/ 和 views/ 严格分离，即使切换 UI 框架，API 层代码也无需修改。
• 组件分级管理：全局组件放 components/，页面专属组件放在对应的 views/ 子目录下。
• 工具函数模块化：utils/ 按功能拆分成多个文件，避免单一文件过于庞大。

5.2.3.3. 核心文件用途浅析

除了目录结构，若依还有几个 位于 src/ 根目录的核心文件，它们是整个应用的 “枢纽”，在系统启动和运行过程中扮演着关键角色。

main.js - 应用的 “启动引擎”

文件路径: src/main.js

这是整个 Vue 应用的入口文件，负责创建 Vue 实例并完成初始化工作。其核心职责包括：

1. 创建 Vue 应用实例

   1	const app = createApp(App)

2. 注册全局插件与组件

   1 2 3

   app.use(router) // 注册路由 app.use(store) // 注册 Pinia 状态管理 app.use(ElementPlus) // 注册 Element Plus UI 库

3. 挂载全局方法到 Vue 实例

   1 2	app.config.globalProperties.useDict = useDict // 字典工具 app.config.globalProperties.download = download // 下载工具

4. 注册全局组件（高频使用的组件）

   1 2	app.component('Pagination', Pagination) // 分页组件 app.component('DictTag', DictTag) // 字典标签

5. 加载权限控制

   1	import './permission' // 导入权限控制逻辑，启动路由守卫

通过 main.js 的统一初始化，确保了整个应用在启动时就完成了所有必要的配置和注册工作。

permission.js - 权限控制的 “守门员”

文件路径: src/permission.js

此文件实现了全局的路由守卫（Route Guard），是若依权限体系的核心。它在 每次路由跳转前 都会执行检查，决定用户是否有权访问目标页面。

核心工作流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

router.beforeEach((to, from, next) => {
  if (getToken()) {
    // 已登录
    if (useUserStore().roles.length === 0) {
      // 首次登录，拉取用户信息和权限
      useUserStore().getInfo().then(() => {
        // 根据权限动态生成路由
        usePermissionStore().generateRoutes().then(accessRoutes => {
          // 将可访问的路由动态添加到路由表
          accessRoutes.forEach(route => router.addRoute(route))
          next({ ...to, replace: true })
        })
      })
    } else {
      next()  // 已有权限信息，直接放行
    }
  } else {
    // 未登录，重定向到登录页
    next(`/login?redirect=${to.fullPath}`)
  }
})

解决的核心问题：

• 未登录用户访问受保护页面时，自动跳转登录页
• 已登录用户首次访问时，动态加载其有权限的路由
• 实现了基于角色和权限的精细化访问控制

router/index.js - 路由配置中心

文件路径: src/router/index.js

此文件是前端路由的定义中心，采用了 静态路由 + 动态路由 的混合模式。

两类路由：

1. constantRoutes（静态路由）：无需权限即可访问的公共路由

   1 2 3 4 5

   export const constantRoutes = [ { path: '/login', component: () => import('@/views/login') }, { path: '/404', component: () => import('@/views/error/404') }, { path: '/index', component: () => import('@/views/index') } ]

2. dynamicRoutes（动态路由）：需要根据用户权限动态加载的路由

   1 2 3 4 5 6 7 8

   export const dynamicRoutes = [ { path: '/system/user-auth', permissions: ['system:user:edit'], // 需要特定权限 component: Layout, children: [...] } ]

核心特性：

• 使用 createWebHistory() 启用 HTML5 History 模式（无 # 号）
• 路由配置中的 meta 字段携带了页面标题、图标、权限等元数据
• 通过 hidden: true 控制路由是否在侧边栏菜单中显示

utils/request.js - HTTP 通信的 “总管”

文件路径: src/utils/request.js

这是若依对 Axios 进行的二次封装，统一管理所有 HTTP 请求和响应的处理逻辑。

核心功能：

1. 请求拦截器（Request Interceptor）

   • 自动在请求头中添加 Authorization: Bearer [token]，实现身份认证
   • 防止重复提交（通过缓存机制判断短时间内的重复请求）

2. 响应拦截器（Response Interceptor）

   • 统一处理后端返回的状态码（如 401 未授权、500 服务器错误）
   • 根据不同的错误码，自动弹出相应的提示信息
   • Token 过期时自动弹窗提示用户重新登录

3. 全局配置

   1 2 3 4

   const service = axios.create({ baseURL: import.meta.env.VITE_APP_BASE_API, // 从环境变量读取 API 基础路径 timeout: 10000 // 请求超时时间 })

设计优势：所有页面的 API 调用都通过这个封装的 request 实例，确保了请求处理逻辑的一致性，避免了在每个 API 文件中重复编写认证、错误处理等代码。

store/index.js - 状态管理入口

文件路径: src/store/index.js

若依 Vue3 版使用了 Pinia（Vue 3 官方推荐的状态管理库）替代 Vuex。此文件仅包含 Pinia 实例的创建：

1
2

const store = createPinia()
export default store

真正的状态管理逻辑被拆分到了 store/modules/ 目录下的各个模块中：

• user.js：管理用户登录状态、Token、角色权限等
• permission.js：管理动态路由和菜单
• settings.js：管理系统设置（如侧边栏主题、是否显示标签页等）
• tagsView.js：管理多标签页的打开/关闭状态

这种模块化的拆分方式，使得状态管理的职责更加清晰，易于维护。

App.vue - 根组件

文件路径: src/App.vue

这是 Vue 应用的根组件，结构极其简洁：

1
2
3

<template>
  <router-view />
</template>

它的职责仅仅是渲染路由匹配到的组件。真正的布局结构（侧边栏、顶栏等）由 layout/index.vue 负责。

在 <script setup> 中，它完成了主题样式的初始化：

1
2
3

onMounted(() => {
  handleThemeStyle(useSettingsStore().theme)  // 根据用户设置应用主题
})

settings.js - 系统全局配置

文件路径: src/settings.js

此文件定义了系统的默认配置项，如：

1
2
3
4
5
6
7
8

export default {
  title: import.meta.env.VITE_APP_TITLE,  // 系统标题
  sideTheme: 'theme-dark',                // 侧边栏主题（深色/浅色）
  tagsView: true,                         // 是否显示标签页
  fixedHeader: false,                     // 是否固定顶部导航栏
  sidebarLogo: true,                      // 是否显示侧边栏 Logo
  dynamicTitle: false                     // 是否启用动态标题
}

这些配置会被 store/modules/settings.js 读取并存入状态管理，用户在 “系统设置” 页面修改这些选项时，实际上是在更新 Store 中的状态。

5.3. 数据库设计：表结构与数据模型深度解析

在深入理解了若依的前端架构后，我们现在将目光转向系统的 “地基”——数据库表设计。一个优秀的表结构设计，不仅决定了系统的数据存储效率，更直接影响着业务逻辑的实现复杂度和系统的可扩展性。

痛点场景: 在企业级应用开发中，权限管理、日志记录、定时任务等功能几乎是标配需求。如果没有成熟的数据库表设计方案，开发者往往会陷入 “表结构设计不合理导致查询性能低下”、“权限控制逻辑复杂度爆炸”、“表关系混乱导致数据一致性问题” 等困境。

若依通过精心设计的 19 张核心业务表 + 11 张 Quartz 调度表，构建了一套完整、规范、可扩展的数据模型体系。我们将按功能模块对这些表进行分类剖析。

5.3.1. 核心权限管理表群：RBAC 模型的五表联动

若依采用了业界成熟的 RBAC（基于角色的访问控制） 模型，通过 5 张核心表实现了 “用户-角色-权限” 的灵活映射关系。

5.3.1.1. RBAC 模型概述

RBAC 核心思想：不直接给用户分配权限，而是先将用户归入不同的角色，再给角色分配权限。这种间接授权的方式，极大地降低了权限管理的复杂度。

若依的 RBAC 实现包含以下核心表：

表关系图示：

1
2
3
4
5
6
7
8
9

sys_user (用户)
    |
    | N:1 (通过 sys_user_role)
    ↓
sys_role (角色)
    |
    | 1:N (通过 sys_role_menu)
    ↓
sys_menu (菜单权限)

5.3.1.2. 用户信息表 (sys_user)

表定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

create table sys_user (
  user_id           bigint(20)      not null auto_increment    comment '用户ID',
  dept_id           bigint(20)      default null               comment '部门ID',
  user_name         varchar(30)     not null                   comment '用户账号',
  nick_name         varchar(30)     not null                   comment '用户昵称',
  email             varchar(50)     default ''                 comment '用户邮箱',
  phonenumber       varchar(11)     default ''                 comment '手机号码',
  sex               char(1)         default '0'                comment '用户性别（0男 1女 2未知）',
  avatar            varchar(100)    default ''                 comment '头像地址',
  password          varchar(100)    default ''                 comment '密码',
  status            char(1)         default '0'                comment '账号状态（0正常 1停用）',
  del_flag          char(1)         default '0'                comment '删除标志（0存在 2删除）',
  login_ip          varchar(128)    default ''                 comment '最后登录IP',
  login_date        datetime                                   comment '最后登录时间',
  pwd_update_date   datetime                                   comment '密码最后更新时间',
  create_time       datetime                                   comment '创建时间',
  update_time       datetime                                   comment '更新时间',
  remark            varchar(500)    default null               comment '备注',
  primary key (user_id)
) comment = '用户信息表';

核心字段解析：

设计亮点：

1. 逻辑删除机制：使用 del_flag 实现软删除，保留用户历史数据用于审计。
2. 密码安全策略：pwd_update_date 字段支持密码过期提醒，强化安全性。
3. 部门关联：通过 dept_id 外键，将用户与组织架构绑定，支持数据权限控制。

5.3.1.3. 角色信息表 (sys_role)

表定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

create table sys_role (
  role_id              bigint(20)      not null auto_increment    comment '角色ID',
  role_name            varchar(30)     not null                   comment '角色名称',
  role_key             varchar(100)    not null                   comment '角色权限字符串',
  role_sort            int(4)          not null                   comment '显示顺序',
  data_scope           char(1)         default '1'                comment '数据范围（1全部 2自定义 3本部门 4本部门及以下）',
  menu_check_strictly  tinyint(1)      default 1                  comment '菜单树选择项是否关联显示',
  dept_check_strictly  tinyint(1)      default 1                  comment '部门树选择项是否关联显示',
  status               char(1)         not null                   comment '角色状态（0正常 1停用）',
  del_flag             char(1)         default '0'                comment '删除标志（0存在 2删除）',
  create_time          datetime                                   comment '创建时间',
  remark               varchar(500)    default null               comment '备注',
  primary key (role_id)
) comment = '角色信息表';

核心字段解析：

数据权限范围详解（data_scope）：

设计亮点：
data_scope 字段是若依权限体系的 核心创新点，它将数据权限控制从代码逻辑中抽离出来，通过配置即可实现灵活的数据隔离。例如，在查询用户列表时，SQL 会根据当前用户的角色 data_scope 自动拼接不同的 WHERE 条件。

5.3.1.4. 菜单权限表 (sys_menu)

表定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

create table sys_menu (
  menu_id           bigint(20)      not null auto_increment    comment '菜单ID',
  menu_name         varchar(50)     not null                   comment '菜单名称',
  parent_id         bigint(20)      default 0                  comment '父菜单ID',
  order_num         int(4)          default 0                  comment '显示顺序',
  path              varchar(200)    default ''                 comment '路由地址',
  component         varchar(255)    default null               comment '组件路径',
  query             varchar(255)    default null               comment '路由参数',
  is_frame          int(1)          default 1                  comment '是否为外链（0是 1否）',
  is_cache          int(1)          default 0                  comment '是否缓存（0缓存 1不缓存）',
  menu_type         char(1)         default ''                 comment '菜单类型（M目录 C菜单 F按钮）',
  visible           char(1)         default '0'                comment '显示状态（0显示 1隐藏）',
  status            char(1)         default '0'                comment '菜单状态（0正常 1停用）',
  perms             varchar(100)    default null               comment '权限标识',
  icon              varchar(100)    default '#'                comment '菜单图标',
  create_time       datetime                                   comment '创建时间',
  primary key (menu_id)
) comment = '菜单权限表';

核心字段解析：

菜单类型（menu_type）详解：

设计亮点：

1. 三级权限粒度：目录、菜单、按钮三层控制，实现了从页面到按钮的全链路权限管理。
2. 权限标识规范：perms 字段采用 模块:功能:操作 的命名规范（如 system:user:add），语义清晰且易于维护。
3. 前后端一体化：path 和 component 字段存储了前端路由信息，后端直接返回给前端用于动态路由生成。

5.3.1.5. 关联表：用户-角色-菜单的桥梁

sys_user_role - 用户角色关联表：

1
2
3
4
5

create table sys_user_role (
  user_id   bigint(20) not null comment '用户ID',
  role_id   bigint(20) not null comment '角色ID',
  primary key(user_id, role_id)
) comment = '用户和角色关联表';

sys_role_menu - 角色菜单关联表：

1
2
3
4
5

create table sys_role_menu (
  role_id   bigint(20) not null comment '角色ID',
  menu_id   bigint(20) not null comment '菜单ID',
  primary key(role_id, menu_id)
) comment = '角色和菜单关联表';

设计亮点：

• 多对多关系：通过中间表实现用户与角色、角色与菜单的多对多映射。
• 联合主键：(user_id, role_id) 作为主键，天然避免重复数据，无需额外的唯一索引。
• 查询性能：两字段联合主键会自动创建索引，极大提升关联查询性能。

权限判断流程：

1
2
3
4
5
6
7
8

1. 查询用户ID = 1 的所有角色
   SELECT role_id FROM sys_user_role WHERE user_id = 1

2. 根据角色ID查询所有菜单权限
   SELECT menu_id FROM sys_role_menu WHERE role_id IN (...)

3. 根据菜单ID查询具体的权限标识
   SELECT perms FROM sys_menu WHERE menu_id IN (...)

5.3.2. 组织架构表群：部门、岗位的树形管理

除了用户角色权限，若依还设计了完整的组织架构管理体系。

5.3.2.1. 部门表 (sys_dept)

表定义：

1
2
3
4
5
6
7
8
9
10
11
12

create table sys_dept (
  dept_id           bigint(20)      not null auto_increment    comment '部门id',
  parent_id         bigint(20)      default 0                  comment '父部门id',
  ancestors         varchar(50)     default ''                 comment '祖级列表',
  dept_name         varchar(30)     default ''                 comment '部门名称',
  order_num         int(4)          default 0                  comment '显示顺序',
  leader            varchar(20)     default null               comment '负责人',
  phone             varchar(11)     default null               comment '联系电话',
  status            char(1)         default '0'                comment '部门状态（0正常 1停用）',
  del_flag          char(1)         default '0'                comment '删除标志（0存在 2删除）',
  primary key (dept_id)
) comment = '部门表';

核心字段解析：

ancestors 字段的设计巧思：

痛点：传统的树形结构查询，若要获取某个部门的所有上级部门，需要递归查询，性能极差。

解决方案：ancestors 字段存储了从根节点到当前节点的完整路径。

示例数据：

1
2
3
4

部门ID  | 部门名称    | parent_id | ancestors
100     | 若依科技    | 0         | 0
101     | 深圳总公司  | 100       | 0,100
103     | 研发部门    | 101       | 0,100,101

应用场景：

1. 查询所有上级部门：直接解析 ancestors 字符串即可，无需递归。
2. 查询所有下级部门：WHERE ancestors LIKE '%,103,%' 即可找到所有子孙部门。

5.3.2.2. 岗位表 (sys_post)

表定义：

1
2
3
4
5
6
7
8

create table sys_post (
  post_id       bigint(20)      not null auto_increment    comment '岗位ID',
  post_code     varchar(64)     not null                   comment '岗位编码',
  post_name     varchar(50)     not null                   comment '岗位名称',
  post_sort     int(4)          not null                   comment '显示顺序',
  status        char(1)         not null                   comment '状态（0正常 1停用）',
  primary key (post_id)
) comment = '岗位信息表';

用户与岗位关联表 (sys_user_post)：

1
2
3
4
5

create table sys_user_post (
  user_id   bigint(20) not null comment '用户ID',
  post_id   bigint(20) not null comment '岗位ID',
  primary key (user_id, post_id)
) comment = '用户与岗位关联表';

设计思想：

• 部门与岗位分离：部门代表组织层级（如 “研发部”），岗位代表职责类型（如 “项目经理”）。
• 一个用户可以属于一个部门，但可以兼任多个岗位。

5.3.3. 系统功能表群：日志、字典、配置

5.3.3.1. 操作日志表 (sys_oper_log)

表定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

create table sys_oper_log (
  oper_id           bigint(20)      not null auto_increment    comment '日志主键',
  title             varchar(50)     default ''                 comment '模块标题',
  business_type     int(2)          default 0                  comment '业务类型（0其它 1新增 2修改 3删除）',
  method                                                                                                                                                                                                                                                                                                                                                                                                                                                         varchar(200)    default ''                 comment '方法名称',
  request_method    varchar(10)     default ''                 comment '请求方式',
  oper_name         varchar(50)     default ''                 comment '操作人员',
  oper_url          varchar(255)    default ''                 comment '请求URL',
  oper_ip           varchar(128)    default ''                 comment '主机地址',
  oper_param        varchar(2000)   default ''                 comment '请求参数',
  json_result       varchar(2000)   default ''                 comment '返回参数',
  status            int(1)          default 0                  comment '操作状态（0正常 1异常）',
  error_msg         varchar(2000)   default ''                 comment '错误消息',
  oper_time         datetime                                   comment '操作时间',
  cost_time         bigint(20)      default 0                  comment '消耗时间',
  primary key (oper_id),
  key idx_sys_oper_log_bt (business_type),
  key idx_sys_oper_log_s  (status),
  key idx_sys_oper_log_ot (oper_time)
) comment = '操作日志记录';

设计亮点：

1. 复合索引优化：在 business_type、status、oper_time 上建立索引，支持多维度日志查询。
2. 性能追踪：cost_time 字段记录接口响应时间，用于性能分析。
3. 完整的请求链路：记录了方法名、URL、参数、返回值，方便问题追踪。

5.3.3.2. 字典表双表设计

sys_dict_type - 字典类型表：

1
2
3
4
5
6
7
8

create table sys_dict_type (
  dict_id          bigint(20)      not null auto_increment    comment '字典主键',
  dict_name        varchar(100)    default ''                 comment '字典名称',
  dict_type        varchar(100)    default ''                 comment '字典类型',
  status           char(1)         default '0'                comment '状态（0正常 1停用）',
  primary key (dict_id),
  unique (dict_type)
) comment = '字典类型表';

sys_dict_data - 字典数据表：

1
2
3
4
5
6
7
8
9
10
11

create table sys_dict_data (
  dict_code        bigint(20)      not null auto_increment    comment '字典编码',
  dict_type        varchar(100)    default ''                 comment '字典类型',
  dict_label       varchar(100)    default ''                 comment '字典标签',
  dict_value       varchar(100)    default ''                 comment '字典键值',
  dict_sort        int(4)          default 0                  comment '字典排序',
  css_class        varchar(100)    default null               comment '样式属性',
  list_class       varchar(100)    default null               comment '表格回显样式',
  status           char(1)         default '0'                comment '状态（0正常 1停用）',
  primary key (dict_code)
) comment = '字典数据表';

双表设计的优势：

应用示例：

1
2
3
4
5

-- 查询 "用户性别" 字典的所有选项
SELECT dict_label, dict_value 
FROM sys_dict_data 
WHERE dict_type = 'sys_user_sex' AND status = '0'
ORDER BY dict_sort;

5.3.4. Quartz 定时任务表群：企业级调度框架

若依集成了 Quartz 框架实现定时任务调度，Quartz 通过 11 张表管理任务的完整生命周期。

5.3.4.1. Quartz 核心表概览

5.3.4.2. 任务详情表 (QRTZ_JOB_DETAILS)

表定义：

1
2
3
4
5
6
7
8
9
10

create table QRTZ_JOB_DETAILS (
    sched_name           varchar(120)    not null            comment '调度名称',
    job_name             varchar(200)    not null            comment '任务名称',
    job_group            varchar(200)    not null            comment '任务组名',
    job_class_name       varchar(250)    not null            comment '执行任务类名称',
    is_durable           varchar(1)      not null            comment '是否持久化',
    is_nonconcurrent     varchar(1)      not null            comment '是否并发',
    job_data             blob            null                comment '存放持久化job对象',
    primary key (sched_name, job_name, job_group)
) comment = '任务详细信息表';