Spring Boot多模块打包进阶：剖析spring-boot-maven-plugin的依赖陷阱与双包策略

1. Spring Boot多模块项目中的依赖陷阱在Spring Boot多模块项目中我们经常会遇到一个令人头疼的问题当基础模块被打包后其他依赖它的模块在编译或运行时却报Class Not Found或Package does not exist错误。这个问题看似简单实则隐藏着Spring Boot打包机制的一个重要特性。1.1 spring-boot-maven-plugin的repackage机制spring-boot-maven-plugin的核心功能之一就是repackage。当你在模块中配置了这个插件它会在Maven的package阶段之后执行将项目打包成一个可执行的fat jar。这个fat jar的特殊之处在于它将所有依赖的jar包解压后重新打包到BOOT-INF/lib目录下将项目自身的类文件放在BOOT-INF/classes目录下使用自定义的类加载器来加载这些资源这种结构虽然让jar包可以直接通过java -jar运行但却导致了一个严重问题这个jar包无法作为依赖被其他项目正常引用。因为标准的Java类加载器无法识别BOOT-INF目录下的类文件。1.2 问题重现场景假设我们有一个典型的多模块项目结构parent-project ├── common-module (基础模块) ├── service-module (业务模块依赖common-module) └── web-module (Web模块依赖service-module)当common-module的pom.xml中配置了spring-boot-maven-plugin但没有特殊处理时build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build执行mvn clean install后service-module在编译时会报错提示找不到common-module中的类。即使编译通过运行时也会抛出ClassNotFoundException。2. 双包策略可执行jar与可依赖jar的解决方案2.1 classifier属性的妙用Maven的classifier属性允许我们为同一个artifact生成不同版本的输出。Spring Boot官方文档(84.5节)建议对于既需要作为依赖又被其他模块引用的项目可以使用classifier来区分两种打包结果。具体配置如下build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration classifierexec/classifier /configuration /plugin /plugins /build这样配置后Maven会生成两个jar文件your-module-1.0.jar- 普通的可依赖jaryour-module-1.0-exec.jar- 可执行的fat jar2.2 双包策略的工作原理这种配置之所以能解决问题是因为它改变了Maven的生命周期行为在package阶段Maven首先生成标准的jar包可依赖然后spring-boot-maven-plugin执行repackage目标将标准jar作为源生成带exec分类器的可执行jar安装到本地仓库或部署到远程仓库时两个jar都会被发布其他模块引用时默认使用不带分类器的标准jar2.3 实际项目中的配置建议在多模块项目中我建议采用以下配置策略在父pom.xml中定义spring-boot-maven-plugin的基本配置但不要启用repackagebuild pluginManagement plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId version${spring-boot.version}/version /plugin /plugins /pluginManagement /build在需要生成可执行jar的模块通常是启动模块中显式配置exec分类器build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration classifierexec/classifier /configuration /plugin /plugins /build对于纯工具类模块被其他模块依赖完全不配置spring-boot-maven-plugin3. 常见问题与进阶配置3.1 JDK版本问题在使用spring-boot-maven-plugin时必须明确指定JDK版本否则可能遇到Lambda表达式相关的编译错误。建议在pom.xml中添加properties java.version11/java.version maven.compiler.source${java.version}/maven.compiler.source maven.compiler.target${java.version}/maven.compiler.target /properties3.2 BOOT-INF目录导致的资源访问问题当你的代码需要访问jar包内的资源文件时可能会因为BOOT-INF目录结构而失败。例如// 传统方式可能失效 InputStream is getClass().getResourceAsStream(/config.properties); // 需要改为 InputStream is getClass().getResourceAsStream(/BOOT-INF/classes/config.properties);对于Spring Boot应用更推荐使用ResourceLoader来加载资源Autowired ResourceLoader resourceLoader; Resource resource resourceLoader.getResource(classpath:config.properties);3.3 多模块项目中的依赖管理对于复杂的多模块项目建议在父pom中使用dependencyManagement统一管理依赖版本dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version${spring-boot.version}/version typepom/type scopeimport/scope /dependency !-- 其他公共依赖 -- /dependencies /dependencyManagement然后在子模块中声明依赖时不需要指定版本dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies4. 最佳实践与经验分享在实际项目中我总结了以下几点经验模块划分原则将可复用的工具类、DTO、公共配置等放在基础模块将业务逻辑放在服务模块将Web相关代码放在Web模块。打包策略只有包含main方法的启动模块才需要配置exec分类器基础模块不应该使用spring-boot-maven-pluginWeb模块通常是生成可执行jar的最佳位置调试技巧使用mvn dependency:tree检查依赖关系使用mvn help:effective-pom查看最终生效的POM配置在IDE中确保正确识别了模块间的依赖关系持续集成在CI/CD流水线中先单独构建基础模块使用-pl和-am参数控制构建顺序例如mvn clean install -pl common-module mvn clean install -pl web-module -am版本管理使用CI流水线自动更新版本号对于SNAPSHOT版本频繁部署到本地仓库对于正式版本确保所有模块版本一致通过合理配置spring-boot-maven-plugin的classifier属性我们完美解决了多模块项目中的依赖问题。这种双包策略既保留了Spring Boot的便捷性又不牺牲Maven多模块项目的灵活性。在实际开发中根据项目复杂度选择合适的模块划分和打包策略可以显著提高开发效率和项目可维护性。