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.8Maven 3.6IDE推荐IntelliJ IDEA在父pom.xml中定义模块结构modules moduleruoyi-admin/module moduleruoyi-common/module moduleruoyi-system/module moduleruoyi-order/module /modules每个子模块的pom.xml需要声明父项目parent groupIdcom.ruoyi/groupId artifactIdruoyi/artifactId version1.0.0/version /parent2.2 解决Controller扫描问题当新增ruoyi-order模块后常见的问题是admin模块无法扫描到order模块的Controller。解决方案分两步添加模块依赖 在ruoyi-admin的pom.xml中添加dependency groupIdcom.ruoyi/groupId artifactIdruoyi-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/**/*.xml3. 深度配置与优化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 groupIdcom.ruoyi/groupId artifactIdruoyi-common/artifactId /dependency /dependencies实现订单服务Service public class OrderServiceImpl implements OrderService { Autowired private OrderMapper orderMapper; public PageInfoOrderVO listOrders(OrderQuery query) { PageHelper.startPage(query.getPageNum(), query.getPageSize()); ListOrderVO 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 nameORDER classch.qos.logback.core.rolling.RollingFileAppender filelogs/order/order.log/file filter classch.qos.logback.classic.filter.ThresholdFilter levelINFO/level /filter /appender logger namecom.ruoyi.order levelDEBUG additivityfalse appender-ref refORDER/ /logger
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.8Maven 3.6IDE推荐IntelliJ IDEA在父pom.xml中定义模块结构modules moduleruoyi-admin/module moduleruoyi-common/module moduleruoyi-system/module moduleruoyi-order/module /modules每个子模块的pom.xml需要声明父项目parent groupIdcom.ruoyi/groupId artifactIdruoyi/artifactId version1.0.0/version /parent2.2 解决Controller扫描问题当新增ruoyi-order模块后常见的问题是admin模块无法扫描到order模块的Controller。解决方案分两步添加模块依赖 在ruoyi-admin的pom.xml中添加dependency groupIdcom.ruoyi/groupId artifactIdruoyi-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/**/*.xml3. 深度配置与优化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 groupIdcom.ruoyi/groupId artifactIdruoyi-common/artifactId /dependency /dependencies实现订单服务Service public class OrderServiceImpl implements OrderService { Autowired private OrderMapper orderMapper; public PageInfoOrderVO listOrders(OrderQuery query) { PageHelper.startPage(query.getPageNum(), query.getPageSize()); ListOrderVO 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 nameORDER classch.qos.logback.core.rolling.RollingFileAppender filelogs/order/order.log/file filter classch.qos.logback.classic.filter.ThresholdFilter levelINFO/level /filter /appender logger namecom.ruoyi.order levelDEBUG additivityfalse appender-ref refORDER/ /logger
