第二章. 功能体验：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 文件。打开该文件，验证其内容是否与当前数据表格中显示的数据完全一致（包括经过筛选的数据）。

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