RuoYi-Vue-Plus：Maven 多模块打包原理与依赖链说明

本文基于 RuoYi-Vue-Plus 仓库实际结构详细说明 Maven 多模块工程的打包逻辑、模块间依赖关系重点对照ruoyi-common、ruoyi-modules含ruoyi-wms、ruoyi-admin三大核心模块帮助开发者理解“多模块协同打包”的本质规避打包依赖异常问题。一、Maven 多模块 Spring Boot整体打包原理RuoYi-Vue-Plus 采用 Maven 多模块架构核心设计是“聚合编排 依赖联动”最终通过 Spring Boot 插件生成可执行包整体逻辑可拆解为以下5个关键要点。1. 根工程仅做聚合编排不产出业务 JAR根目录下的pom.xml是整个工程的“总入口”核心配置如下节选关键内容modules moduleruoyi-admin/module moduleruoyi-common/module moduleruoyi-extend/module moduleruoyi-modules/module /modules packagingpom/packaging核心说明packaging 为 pom根项目本身不编写任何业务代码也不会打成可运行的 JAR 包仅作为「聚合工程」和「父工程」负责统一管理子模块、统一依赖版本通过dependencyManagement、触发全量构建。modules 标签明确声明工程包含的所有子模块相当于“告诉 Maven 哪些模块需要参与构建”。在根目录执行mvn package时Maven 会自动识别这些模块按规则顺序构建。关键结论根目录是“总构建入口”所有子模块的编译、打包都由根工程触发可运行的最终产物Fat JAR仅存在于子模块中本项目中为ruoyi-admin。2. 子模块独立打包依赖联动反应堆顺序除根工程外所有业务相关子模块如ruoyi-common-*、ruoyi-wms、ruoyi-system的packaging均为jar核心特性如下每个子模块独立编译、打包在自身target/目录下生成对应xxx.jar仅包含本模块的 class 文件、资源文件。模块间的依赖的通过「Maven 坐标」实现即模块 A 若需使用模块 B 的功能只需在 A 的pom.xml中通过dependency引入 B 的坐标无需复制 B 的源码。构建顺序由「Maven 反应堆Reactor」自动计算被依赖的模块会优先构建依赖方后构建。例如ruoyi-admin依赖ruoyi-wms则ruoyi-wms会先于ruoyi-admin完成编译、打包。核心优势在根目录执行构建时无需提前对每个子模块单独执行mvn install无需将子模块 JAR 安装到本地仓库Maven 会直接使用本次反应堆构建的本地模块版本避免版本冲突。本质总结“多模块一起打包”就是 Maven 按「依赖先后顺序」逐个构建所有子模块最终构建入口模块ruoyi-admin的过程。3. 可执行 Fat JAR 的生成Spring Boot 插件的核心作用很多开发者会疑惑“多个模块都生成了 JAR为什么最终只需要部署一个ruoyi-admin.jar” 关键在于ruoyi-admin中配置的spring-boot-maven-plugin插件其repackage目标是核心。分两步理解打包过程第一步Maven 默认打包maven-jar-plugin所有子模块包括ruoyi-admin在执行package时默认会通过maven-jar-plugin生成“普通 JAR”该 JAR 仅包含当前模块的 class 和资源不会将依赖的其他模块如ruoyi-wms、ruoyi-common-core的 JAR 合并进来。第二步Spring Boot 插件重打包repackageruoyi-admin的pom.xml中配置了spring-boot-maven-plugin其repackage目标会在“普通 JAR”的基础上重新打包生成「Fat JAR可执行 JAR」其典型内部结构如下BOOT-INF/lib/存放所有依赖的 JAR 包包括各业务模块ruoyi-wms、ruoyi-system等、Spring 框架及其他第三方依赖如 MyBatis、Sa-Token。BOOT-INF/classes/存放ruoyi-admin自身的 class 文件和资源文件如配置文件、静态资源。Spring Boot 启动器JarLauncher负责在执行java -jar时按约定加载BOOT-INF/lib/中的依赖和BOOT-INF/classes/中的自身代码实现项目启动。关键结论开发时各模块在目录和工程上相互独立部署时只需分发ruoyi-admin生成的 Fat JAR即可包含所有所需的依赖模块和第三方库无需单独部署其他子模块。4. 整体架构心智图文字版用层级结构清晰展示多模块关系与打包流程pom (packagingpom)├─ 核心作用声明 modules聚合子模块 dependencyManagement统一版本├─ 子模块分类│ ├─ 公共模块ruoyi-commonpackagingpom│ │ └─ 子模块ruoyi-common-core、ruoyi-common-web 等 → 各自打成 xxx.jar工具/公共能力库│ ├─ 业务模块ruoyi-modulespackagingpom│ │ └─ 子模块ruoyi-wms、ruoyi-system、ruoyi-demo 等 → 各自打成 xxx.jar业务逻辑库│ └─ 入口模块ruoyi-adminpackagingjar│ ├─ 依赖公共模块 业务模块 第三方依赖│ └─ 插件spring-boot-maven-plugin repackage → 生成 Fat JAR可执行└─ 构建流程根目录执行 mvn package → 反应堆按依赖顺序构建所有子模块 → 最终生成 ruoyi-admin.jar5. 常见操作与背后行为避坑重点以下是开发中最常用的3种操作明确其背后的 Maven 行为避免出现依赖缺失、打包失败等问题操作命令背后行为说明注意事项在根工程执行mvn clean package1. 清理所有子模块的target目录2. 按反应堆顺序被依赖模块优先编译、打包所有子模块3. 最后对ruoyi-admin执行 repackage生成 Fat JAR。推荐使用可确保所有模块同步更新避免依赖版本不一致。仅在ruoyi-admin中执行mvn packageMaven 会直接构建ruoyi-admin但会去本地仓库或本次反应堆中查找其依赖的模块如ruoyi-wms。若依赖模块未提前构建未在本地仓库也未参与本次反应堆会报“依赖缺失”错误。java -jar ruoyi-admin\target\ruoyi-admin.jarJVM 仅加载该 Fat JAR 文件由 Spring Boot 的 JarLauncher 负责加载内部BOOT-INF/lib中的依赖和BOOT-INF/classes中的代码。无需再单独启动其他子模块也无需读取其他模块的target目录该 JAR 是独立可运行的。6. 补充说明常见疑问解答为何根目录不打一个总 JAR根工程的packaging为pom无业务主类main方法且 Spring Boot 启动插件配置在ruoyi-admin中根工程无法生成可执行 JAR。ruoyi-admin某模块未出现在 的依赖中该模块的 JAR 不会被打包到ruoyi-admin的BOOT-INF/lib中项目运行时无法使用该模块的代码若需使用需在ruoyi-admin的pom.xml中添加依赖。与微服务多 JAR 的区别本项目是「单体/模块化单体」架构所有业务模块最终聚合到一个ruoyi-adminFat JAR 中部署简单微服务架构则是“一服务一可执行 JAR”各服务独立部署、相互调用。二、ruoyi-modules子模块列表与目录对照ruoyi-modules是业务模块的聚合工程其pom.xml中声明了所有业务子模块与磁盘目录一一对应便于开发者定位各业务模块的位置。1. 模块声明pom.xml 节选modules moduleruoyi-demo/module moduleruoyi-generator/module moduleruoyi-job/module moduleruoyi-system/module moduleruoyi-workflow/module moduleruoyi-wms/module /modules2. 模块与目录对应关系Maven 模块名称磁盘目录路径相对根工程模块功能说明简要ruoyi-demoruoyi-modules/ruoyi-demo示例模块提供基础开发示例可参考其结构开发新业务模块。ruoyi-generatorruoyi-modules/ruoyi-generator代码生成器模块用于生成实体类、Mapper、Service 等基础代码。ruoyi-jobruoyi-modules/ruoyi-job定时任务模块负责定时任务的配置、调度与执行。ruoyi-systemruoyi-modules/ruoyi-system系统核心模块包含用户、角色、权限、字典等基础系统功能。ruoyi-workflowruoyi-modules/ruoyi-workflow工作流模块负责流程定义、流转、审批等相关功能。ruoyi-wmsruoyi-modules/ruoyi-wms仓储管理模块包含仓储相关业务逻辑如库存、入库、出库等。3. 模块关系说明以上6个模块在 Maven 中为「平级兄弟关系」同属ruoyi-modules聚合工程目录上互不包含、相互独立。模块之间是否存在依赖不取决于目录结构而取决于各自pom.xml中dependency标签的声明例如ruoyi-wms可根据业务需求依赖ruoyi-system也可独立存在。三、从 common → wms → admin 的依赖链WMS 视角以ruoyi-wms仓储模块为核心详细拆解其依赖的公共模块、以及与入口模块ruoyi-admin的依赖关系明确“WMS 模块如何被打包到最终可执行 JAR 中”。1.ruoyi-wms直接依赖的ruoyi-common-*模块摘自ruoyi-modules/ruoyi-wms/pom.xml节选核心依赖第三方依赖省略ruoyi-common-core核心工具类、常量、异常处理等基础能力。ruoyi-common-webWeb 相关基础配置如拦截器、全局响应、请求参数校验等。ruoyi-common-log日志相关工具与配置用于业务日志记录。ruoyi-common-mybatisMyBatis 相关基础配置如分页、插件、BaseMapper 等。ruoyi-common-excelExcel 导入导出相关工具类。ruoyi-common-idempotent接口幂等性相关工具与配置避免重复提交。ruoyi-common-tenant多租户相关基础配置支持多租户隔离。说明以上依赖均为「直接依赖」即ruoyi-wms在pom.xml中显式声明的依赖除此之外还会通过这些依赖传递引入其他第三方依赖如 Sa-Token、Lombok 等。2. 依赖关系简图Mermaid 可视化清晰展示ruoyi-wms与 common 模块、admin 模块的依赖关联以及 admin 模块的其他依赖图例说明关键区分实线连接表示「显式直接依赖」即被依赖方在依赖方的pom.xml中显式声明打包时被依赖方的 JAR 会被包含到依赖方的依赖中最终进入ruoyi-admin的BOOT-INF/lib。虚线连接表示「admin 额外依赖」即ruoyi-admin除了依赖ruoyi-wms还依赖其他业务模块如ruoyi-system这些模块与ruoyi-wms是平级关系ruoyi-wms不依赖它们。ruoyi-wms 与 ruoyi-system 的关系两者均为ruoyi-modules下的平级业务模块ruoyi-wms的 POM 中未默认依赖ruoyi-system若业务上需要调用系统模块如用户、权限可在ruoyi-wms的 POM 中添加ruoyi-system的依赖。3. 依赖链与代码目录对照结合目录结构明确各层级模块的作用与位置便于开发者快速定位代码层级分类核心作用典型模块典型目录路径公共能力层提供所有业务模块共用的工具、配置、基础能力避免重复开发。ruoyi-common-core、ruoyi-common-web 等ruoyi-common/ruoyi-common-core业务逻辑层实现具体业务功能各模块独立可按需扩展。ruoyi-wms仓储、ruoyi-system系统等ruoyi-modules/ruoyi-wms启动入口层聚合所有依赖生成可执行 Fat JAR负责项目启动。ruoyi-adminruoyi-admin产物路径ruoyi-admin/target/ruoyi-admin.jar四、ruoyi-common聚合下的子模块说明ruoyi-common是公共模块的聚合工程其pom.xml中声明了所有公共子模块除了ruoyi-wms直接依赖的7个模块外还有其他公共模块。核心说明本文仅列出ruoyi-wms直接依赖的ruoyi-common-*模块完整的公共模块列表请以仓库内ruoyi-common/pom.xml中的modules声明为准避免与源码漂移不重复粘贴。若日后在ruoyi-wms的pom.xml中新增ruoyi-common-xxx依赖则本文第三部分的“依赖关系简图”中会新增一条ruoyi-common-xxx → ruoyi-wms的实线连接打包时该模块也会被包含到ruoyi-admin的 Fat JAR 中。五、文档维护说明本文内容与项目源码强关联若项目进行模块调整、依赖变更需同步更新本文对应内容确保文档与源码一致。1. 依赖的 POM 文件路径根工程pom.xml公共模块聚合ruoyi-common/pom.xml业务模块聚合ruoyi-modules/pom.xml仓储模块ruoyi-modules/ruoyi-wms/pom.xml入口模块ruoyi-admin/pom.xml2. 维护要求新增/删除子模块如在ruoyi-modules中新增业务模块同步更新本文第二部分的模块列表与目录对照。变更模块依赖如ruoyi-wms新增/删除ruoyi-common依赖同步更新本文第三部分的依赖列表与 Mermaid 简图。调整打包配置如修改spring-boot-maven-plugin配置同步更新本文第一部分的打包原理说明。