文步蘅1. 为什么要在若依框架中创建新模块？
若依（RuoYi）作为国内流行的开源企业级开发框架，其模块化设计允许开发者根据业务需求灵活扩展。在实际项目中，我们经常会遇到以下典型场景：
- 业务功能迭代需要新增独立功能单元（如支付中心、消息中心）
- 现有模块过于臃肿需要拆分（如用户模块拆分为账户中心+权限中心）
- 需要集成第三方服务（如OSS文件服务、短信网关）
- 微服务架构下新增业务微服务
以我参与的某供应链系统为例，当需要增加物流轨迹追踪功能时，直接在原有模块中堆砌代码会导致：
- 业务边界模糊（物流代码与订单代码混杂）
- 多人协作冲突（修改同一模块的类文件）
- 部署效率降低（每次都要全量打包）
通过新建logistics模块，我们实现了：
- 独立数据库表设计（t_logistics_trace）
- 专属API前缀（/logistics/**）
- 单独权限控制（logistics:track:query）
- 独立依赖管理（只需引入地图SDK）
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 模块创建前的技术准备
2.1 环境配置检查
在开始前，请确认以下环境（以Spring Boot版为例）：
bash复制# JDK版本
java -version # 要求1.8+
# Maven配置
mvn -v # 3.5+
# IDE插件
- Lombok插件（必须）
- MyBatisX（推荐）
2.2 框架结构理解
典型若依项目结构：
code复制ruoyi-admin # 主启动模块
ruoyi-common # 公共库
ruoyi-system # 系统模块（示例）
ruoyi-quartz # 定时任务（示例）
新建模块需要保持：
- 命名规范：
ruoyi-模块名（全小写） - 依赖关系：必须依赖
ruoyi-common - 包路径：
com.ruoyi.模块名
3. 手把手创建新模块
3.1 使用Maven Archetype创建
在项目根目录执行：
bash复制mvn archetype:generate \
-DgroupId=com.ruoyi \
-DartifactId=ruoyi-custom \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=false
然后修改生成的pom.xml：
xml复制<!-- 添加父依赖 -->
<parent>
<groupId>com.ruoyi</groupId>
<artifactId>ruoyi</artifactId>
<version>${project.version}</version>
</parent>
<!-- 添加common依赖 -->
<dependencies>
<dependency>
<groupId>com.ruoyi</groupId>
<artifactId>ruoyi-common</artifactId>
</dependency>
</dependencies>
3.2 手动创建目录结构
推荐结构：
code复制ruoyi-custom
├── src/main/java
│ └── com/ruoyi/custom
│ ├── config # 配置类
│ ├── controller # 控制器
│ ├── domain # 实体类
│ ├── mapper # MyBatis映射
│ ├── service # 服务层
│ └── utils # 工具类
├── src/main/resources
│ ├── mapper # XML文件
│ └── application.yml # 模块配置
└── pom.xml
关键配置示例（application.yml）：
yaml复制# 自定义配置前缀
custom:
file-path: /data/upload
max-size: 10MB
3.3 注册模块到主应用
在ruoyi-admin中注册：
- 添加依赖：
xml复制<dependency>
<groupId>com.ruoyi</groupId>
<artifactId>ruoyi-custom</artifactId>
</dependency>
- 确保组件扫描：
java复制@SpringBootApplication
@ComponentScan({"com.ruoyi","com.ruoyi.custom"})
public class RuoYiApplication {
//...
}
4. 高级配置与集成
4.1 数据库多数据源配置
当需要独立数据库时：
java复制// 1. 配置数据源
@Configuration
@MapperScan(basePackages = "com.ruoyi.custom.mapper", sqlSessionTemplateRef = "customSqlSessionTemplate")
public class CustomDataSourceConfig {
@Bean
@ConfigurationProperties(prefix = "spring.datasource.custom")
public DataSource customDataSource() {
return DataSourceBuilder.create().build();
}
// 配置事务、SqlSessionFactory等...
}
4.2 权限控制集成
在ruoyi-custom中新增权限标识：
- 定义权限字符串：
java复制public class CustomPermission {
public static final String ORDER_VIEW = "custom:order:view";
//...
}
- 在Controller使用：
java复制@PreAuthorize("@ss.hasPermi('custom:order:view')")
@GetMapping("/orders")
public R list() {
//...
}
4.3 定时任务集成
创建自定义任务类：
java复制@Component("customTask")
public class CustomTask {
public void cleanTempFiles(String param) {
// 实现逻辑...
}
}
然后在管理页面配置：
code复制调用目标字符串：customTask.cleanTempFiles('7d')
5. 常见问题解决方案
5.1 模块热加载失效
现象：修改代码后需要重启才能生效
解决方案：
- 检查IDE的Build->Compiler->Build project automatically
- 添加spring-boot-devtools依赖
- 修改application.yml：
yaml复制spring:
devtools:
restart:
enabled: true
additional-paths: src/main/java
5.2 跨模块依赖冲突
典型报错：NoSuchBeanDefinitionException
处理步骤：
- 检查包扫描范围
- 使用@Lazy延迟加载
- 明确指定bean名称：
java复制@Autowired
@Qualifier("customService")
private IService service;
5.3 接口404问题
排查路径：
- 确认
ruoyi-admin的application.yml：
yaml复制spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
- 检查Controller注解：
java复制@RestController
@RequestMapping("/custom/order") // 必须包含模块前缀
public class OrderController {
//...
}
6. 性能优化实践
6.1 模块懒加载配置
在启动类添加：
java复制@SpringBootApplication
@Lazy
public class CustomApplication {
public static void main(String[] args) {
SpringApplication.run(CustomApplication.class, args);
}
}
6.2 独立Redis数据库
避免key冲突：
yaml复制spring:
redis:
database: 1 # 默认0，新模块建议用1-15
6.3 日志分离配置
在logback-spring.xml中添加：
xml复制<appender name="CUSTOM_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>logs/custom.log</file>
<!-- 其他配置 -->
</appender>
<logger name="com.ruoyi.custom" level="DEBUG" additivity="false">
<appender-ref ref="CUSTOM_FILE"/>
</logger>
7. 模块打包与部署
7.1 独立打包配置
在pom.xml中添加：
xml复制<build>
<finalName>ruoyi-custom-${project.version}</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<classifier>exec</classifier>
</configuration>
</plugin>
</plugins>
</build>
打包命令：
bash复制mvn clean package -pl ruoyi-custom -am
7.2 Docker化部署
示例Dockerfile：
dockerfile复制FROM openjdk:8-jdk-alpine
VOLUME /tmp
COPY target/ruoyi-custom-*.jar app.jar
ENTRYPOINT ["java","-jar","/app.jar"]
构建命令：
bash复制docker build -t ruoyi-custom:v1 .
8. 模块演进建议
8.1 微服务化改造
当模块复杂度增加时：
- 抽取为独立Spring Cloud服务
- 通过Nacos注册中心发现
- 使用OpenFeign进行服务调用
改造示例：
java复制@FeignClient(name = "ruoyi-custom", path = "/custom")
public interface CustomServiceClient {
@GetMapping("/orders/{id}")
R<Order> getOrder(@PathVariable Long id);
}
8.2 前端代码组织
若依Vue版集成建议：
- 在
src/views下新建模块目录 - API请求统一前缀：
js复制// api/custom.js
import request from '@/utils/request'
export function listOrders(params) {
return request({
url: '/custom/orders',
method: 'get',
params
})
}
8.3 监控集成
接入Spring Boot Admin：
- 添加依赖：
xml复制<dependency>
<groupId>de.codecentric</groupId>
<artifactId>spring-boot-admin-starter-client</artifactId>
</dependency>
- 配置监控端点：
yaml复制management:
endpoints:
web:
exposure:
include: "*"
endpoint:
health:
show-details: always