保姆级教程：从零到一，在若依微服务框架(RuoYi-Cloud)中手把手教你新建一个功能模块

保姆级教程：从零到一，在若依微服务框架(RuoYi-Cloud)中手把手教你新建一个功能模块

在微服务架构盛行的当下，若依(RuoYi-Cloud)作为国内流行的开源框架，凭借其完善的权限体系和模块化设计，成为许多企业快速搭建后台管理系统的首选。但对于刚接触该框架的开发者而言，如何在现有项目中新增一个完整功能模块，往往面临诸多实操困惑——从基础结构搭建到前后端联调，每个环节都可能隐藏着意想不到的"坑"。

本教程将从一个真实电商后台的"促销管理"模块出发，带你完整走通模块创建全流程。不同于官方文档的概览式说明，这里会重点揭示那些只有踩过坑才知道的细节：比如Nacos配置的命名约定、代码生成器的字段映射技巧、以及菜单权限配置的隐藏逻辑。无论你是Java后端开发者还是需要全栈协作的工程师，都能获得即插即用的实战经验。

1. 环境准备与项目结构认知

在开始创建新模块前，确保本地开发环境已具备以下基础组件：

• JDK 1.8+（推荐Amazon Corretto 11）
• Maven 3.6+（配置阿里云镜像加速）
• Nacos 1.4.2+（若依默认依赖版本）
• Redis 5.0+（会话管理必需）
• MySQL 5.7+（建议8.0以上版本）

若依微服务版采用标准的多模块Maven结构，核心模块包括：

ruoyi ├── ruoyi-admin # 网关聚合层 ├── ruoyi-common # 通用工具包 ├── ruoyi-system # 系统基础模块 ├── ruoyi-auth # 认证中心 └── ruoyi-modules # 业务模块目录（新建模块位置）

关键提示：所有新增业务模块都应放置在ruoyi-modules目录下，保持与系统模块的平级关系。错误地将模块放在其他目录会导致依赖解析失败。

2. 新建模块基础骨架

以创建ruoyi-promotion（促销模块）为例，在ruoyi-modules目录下执行以下操作：

2.1 创建Maven模块

1. 右键ruoyi-modules→ New → Module
2. 选择Maven原型，输入：
   • GroupId: com.ruoyi
   • ArtifactId: ruoyi-promotion
   • Version: 与父POM保持一致（如3.8.0）

生成的pom.xml需添加必要依赖：

<dependencies> <!-- 若依基础依赖 --> <dependency> <groupId>com.ruoyi</groupId> <artifactId>ruoyi-common-core</artifactId> </dependency> <!-- MyBatis-Plus --> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> </dependency> <!-- 数据权限注解 --> <dependency> <groupId>com.ruoyi</groupId> <artifactId>ruoyi-common-datascope</artifactId> </dependency> </dependencies>

2.2 初始化包结构

按照若依规范创建标准分层结构：

src/main/java/com/ruoyi/promotion ├── config # 配置类 ├── controller # 控制层 ├── domain # 实体类 ├── mapper # 数据层 ├── service # 服务层 └── vo # 视图对象

常见错误：忘记在启动类添加@EnableCustomConfig注解，导致模块配置无法加载。正确的启动类示例：

@SpringBootApplication @EnableCustomConfig public class RuoYiPromotionApplication { public static void main(String[] args) { SpringApplication.run(RuoYiPromotionApplication.class, args); } }

3. Nacos服务注册与配置

3.1 服务注册配置

在bootstrap.yml中配置服务基本信息：

spring: application: name: ruoyi-promotion cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: ${NACOS_NAMESPACE:dev} config: file-extension: yaml shared-configs: -># 数据源配置（分库时必需） spring: datasource: druid: url: jdbc:mysql://localhost:3306/ry_promotion?useSSL=false username: root password: 123456 # MyBatis-Plus配置 mybatis-plus: mapper-locations: classpath*:mapper/**/*Mapper.xml type-aliases-package: com.ruoyi.promotion.domain

避坑指南：若使用独立数据库，必须在Nacos中配置spring.datasource.druid开头的完整数据源信息。仅配置url会导致连接池初始化失败。

4. 代码生成与业务开发

4.1 逆向工程使用

1. 在ruoyi-admin的代码生成页面配置：

   • 表名: pmt_coupon（示例优惠券表）
   • 模块名: promotion
   • 包路径: com.ruoyi.promotion
   • 业务名: coupon

2. 生成后获得标准CRUD代码，需重点检查：

   • domain中字段类型是否正确映射
   • mapper.xml是否包含基础ResultMap
   • 控制器是否添加@DataScope注解

4.2 自定义业务逻辑开发

以创建优惠券为例，扩展生成的Service：

public class CouponServiceImpl extends ServiceImpl<CouponMapper, Coupon> implements ICouponService { @Override @Transactional(rollbackFor = Exception.class) public boolean createCoupon(CouponVO vo) { // 校验库存 if (vo.getTotalCount() <= 0) { throw new ServiceException("发放数量必须大于0"); } // 转换实体 Coupon coupon = new Coupon(); BeanUtils.copyProperties(vo, coupon); coupon.setRemainCount(vo.getTotalCount()); // 持久化 return save(coupon); } }

配套的VO类示例：

@Data public class CouponVO { @NotBlank(message = "名称不能为空") private String name; @Min(value = 1, message = "至少满1元可用") private BigDecimal minAmount; @Future(message = "必须是将来的时间") private LocalDateTime expireTime; }

5. 前端集成与菜单配置

5.1 Vue组件对接

1. 将生成的api和views文件夹复制到ruoyi-ui/src/views/promotion
2. 修改API路径匹配后端：

// promotion/coupon.js import request from '@/utils/request' export function listCoupon(query) { return request({ url: '/promotion/coupon/list', method: 'get', params: query }) }

5.2 动态路由注册

在ruoyi-admin后台配置菜单：

1. 系统管理 → 菜单管理 → 新增

2. 填写菜单信息：

   • 菜单名称：优惠券管理
   • 路由地址：/promotion/coupon
   • 组件路径：promotion/coupon/index
   • 权限标识：promotion:coupon:list

3. 分配权限给对应角色

联调技巧：前端常因路由路径大小写不匹配导致404，确保Vue组件中的name属性与后端@RequestMapping的值完全一致。例如前端/promotion/coupon对应后端@RequestMapping("/promotion/coupon")。

6. 调试与问题排查

当模块无法正常工作时，按以下顺序检查：

1. 服务注册验证：

   curl -X GET 'http://localhost:8848/nacos/v1/ns/instance/list?serviceName=ruoyi-promotion'

   应返回包含IP和端口的实例信息

2. 接口调试工具链：

   • 使用knife4j访问http://localhost:8080/doc.html
   • Postman测试时注意携带Authorization头

3. 常见错误解决方案：

   现象	可能原因	修复方案
   404 Not Found	路由未注册	检查Nacos和网关路由表
   403 Forbidden	权限标识缺失	检查@PreAuthorize注解
   500 Internal Error	数据源未配置	验证Nacos中的数据库连接

在完成所有步骤后，建议执行端到端测试：

1. 通过前端创建测试数据
2. 检查数据库记录是否持久化
3. 验证列表查询是否返回新数据
4. 测试权限控制是否生效

开发过程中若遇到持久化异常，可开启SQL日志辅助排查：

# application-dev.yaml logging: level: com.ruoyi.promotion.mapper: debug