Ruoyi框架避坑指南：从零开始配置多模块项目的完整流程
Ruoyi多模块项目实战：从架构设计到避坑全攻略
若依（Ruoyi）作为国内流行的快速开发框架，其多模块设计理念能显著提升企业级项目的可维护性。但许多开发者在初次接触时，常因配置不当陷入各种"坑"中。本文将从一个真实电商后台项目出发，带你完整走通多模块配置全流程。
1. 多模块项目架构设计原则
在开始配置之前，我们需要理解Ruoyi多模块设计的核心理念。典型的多模块结构通常包含：
- ruoyi-admin：主启动模块（含SpringBoot启动类）
- ruoyi-common：通用工具类模块
- ruoyi-system：系统核心模块
- ruoyi-quartz：定时任务模块
- 自定义业务模块：如示例中的
ruoyi-order
关键设计原则：
- 模块依赖单向流动：下层模块不能依赖上层模块，例如common模块不应依赖admin模块
- 包命名一致性：所有模块的基础包名应保持相同前缀（如
com.ruoyi） - 资源文件隔离：每个模块的配置文件应存放在各自模块的
resources目录下
提示：建议使用Maven的dependencyManagement统一管理依赖版本，避免不同模块间版本冲突
2. 多模块配置完整流程
2.1 环境准备与基础配置
首先确保开发环境满足：
- JDK 1.8+
- Maven 3.6+
- IDE（推荐IntelliJ IDEA）
在父pom.xml中定义模块结构：
<modules> <module>ruoyi-admin</module> <module>ruoyi-common</module> <module>ruoyi-system</module> <module>ruoyi-order</module> </modules>每个子模块的pom.xml需要声明父项目：
<parent> <groupId>com.ruoyi</groupId> <artifactId>ruoyi</artifactId> <version>1.0.0</version> </parent>2.2 解决Controller扫描问题
当新增ruoyi-order模块后，常见的问题是admin模块无法扫描到order模块的Controller。解决方案分两步：
添加模块依赖： 在ruoyi-admin的pom.xml中添加：
<dependency> <groupId>com.ruoyi</groupId> <artifactId>ruoyi-order</artifactId> <version>${project.version}</version> </dependency>配置扫描路径： 修改ruoyi-admin的启动类：
@SpringBootApplication(scanBasePackages = { "com.ruoyi.admin", "com.ruoyi.order" }) public class RuoYiApplication { public static void main(String[] args) { SpringApplication.run(RuoYiApplication.class, args); } }
2.3 解决Mapper扫描问题
多模块下Mapper接口扫描不到是另一个常见问题。正确的配置方式：
在启动类添加Mapper扫描注解：
@MapperScan({ "com.ruoyi.system.mapper", "com.ruoyi.order.mapper" })确保MyBatis配置正确： 在application.yml中添加：
mybatis: typeAliasesPackage: com.ruoyi.*.domain mapperLocations: classpath*:mapper/**/*.xml
3. 深度配置与优化
3.1 统一异常处理配置
多模块项目需要统一的异常处理机制。推荐做法：
在common模块定义基础异常类：
public class BusinessException extends RuntimeException { private final ErrorCode errorCode; // 构造方法省略 }在admin模块配置全局异常处理器：
@RestControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(BusinessException.class) public AjaxResult handleBusinessException(BusinessException e) { return AjaxResult.error(e.getErrorCode()); } }
3.2 多模块事务管理
跨模块服务调用时的事务管理需要特别注意：
- 使用
@Transactional注解确保事务传播 - 避免在Controller层开启事务
- 复杂事务考虑使用分布式事务解决方案
示例代码：
@Service public class OrderServiceImpl implements OrderService { @Transactional(rollbackFor = Exception.class) public void createOrder(OrderDTO orderDTO) { // 调用库存模块 // 调用支付模块 // 本地订单操作 } }4. 实战案例：电商订单模块集成
以电商系统中的订单模块为例，展示完整集成流程：
创建订单模块：
ruoyi-order ├── src/main/java │ └── com.ruoyi.order │ ├── config │ ├── controller │ ├── domain │ ├── mapper │ └── service └── src/main/resources └── mapper配置模块依赖： 在ruoyi-order的pom.xml中添加必要依赖：
<dependencies> <dependency> <groupId>com.ruoyi</groupId> <artifactId>ruoyi-common</artifactId> </dependency> </dependencies>实现订单服务：
@Service public class OrderServiceImpl implements OrderService { @Autowired private OrderMapper orderMapper; public PageInfo<OrderVO> listOrders(OrderQuery query) { PageHelper.startPage(query.getPageNum(), query.getPageSize()); List<OrderVO> orders = orderMapper.selectOrderList(query); return new PageInfo<>(orders); } }前端对接： 在ruoyi-ui中新增订单管理菜单，调用后端接口：
export function listOrder(query) { return request({ url: '/order/list', method: 'get', params: query }) }
5. 性能优化与最佳实践
5.1 模块化缓存策略
不同模块应采用独立的缓存命名空间：
@CacheConfig(cacheNames = "order") @Service public class OrderServiceImpl implements OrderService { @Cacheable(key = "#orderId") public OrderVO getOrderById(Long orderId) { // 查询逻辑 } }5.2 接口文档整合
使用Swagger整合多模块API文档：
在common模块配置Swagger基础：
@Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.ruoyi")) .paths(PathSelectors.any()) .build(); }各模块添加接口注解：
@Api(tags = "订单管理") @RestController @RequestMapping("/order") public class OrderController { @ApiOperation("查询订单列表") @GetMapping("/list") public TableDataInfo list(OrderQuery query) { // 实现逻辑 } }
5.3 日志隔离配置
为每个模块配置独立的日志文件：
# logback-spring.xml <appender name="ORDER" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>logs/order/order.log</file> <filter class="ch.qos.logback.classic.filter.ThresholdFilter"> <level>INFO</level> </filter> </appender> <logger name="com.ruoyi.order" level="DEBUG" additivity="false"> <appender-ref ref="ORDER"/> </logger>