SpringBoot多模塊依賴沖突排查與架構優(yōu)化實戰(zhàn)
前言：在SpringBoot多模塊項目開發(fā)中，依賴沖突、版本不一致、模塊依賴設計不合理是最常見的“攔路虎”。本文結合實際項目場景，記錄從依賴版本沖突（tomcat、spring-security）到模塊架構優(yōu)化的完整排查、解決過程，總結企業(yè)級多模塊最佳實踐，幫助更多開發(fā)者避坑，提升項目可維護性。
本文核心解決場景：父模塊+通用模塊A+業(yè)務模塊BCD的多模塊結構中，依賴版本沖突、非公共依賴污染無關模塊、模塊依賴設計不合理等問題，全程貼合實際開發(fā)場景，提供可直接復用的解決方案。
一、項目初始結構（問題場景）
先明確項目初始結構，也是問題的起源，方便大家對號入座：
父項目（parent） ├── A模塊（通用模塊）：包含service、dao、工具類，引入mybatis-plus、redis、spring-boot-starter-security等 ├── B模塊（業(yè)務模塊）：依賴A模塊，需要security功能 ├── C模塊（業(yè)務模塊）：依賴A模塊，不需要security功能 └── D模塊（業(yè)務模塊）：依賴A模塊，不需要security功能
初始問題匯總：
1. 父模塊在dependencies中直接引入tomcat-embed-core、spring-boot-starter-web（帶排除），導致子模塊出現(xiàn)tomcat版本沖突（父模塊10.1.54，A模塊傳遞10.1.42）；
2. A模塊引入spring-boot-starter-security，需升級spring-security-web至6.5.10，但父模塊鎖定后不生效，A/B模塊版本不一致；
3. A模塊引入的security依賴，傳遞給不需要的C/D模塊，造成依賴冗余；
4. 父模塊未遵循“只管理版本，不引入依賴”的原則，導致依賴傳遞混亂。
二、核心問題排查與解決方案（按優(yōu)先級）
以下解決方案按“先解決緊急沖突，再優(yōu)化架構”的順序，每一步都貼合實際操作，可直接復制配置使用。
問題1：tomcat-embed-core版本沖突（父模塊10.1.54，子模塊10.1.42）
1.1 問題根源
父模塊在dependencies中直接引入tomcat-embed-core:10.1.54，同時父模塊還引入了spring-boot-starter-web（排除了tomcat）；A模塊引入spring-boot-starter-web，自帶tomcat-embed-core:10.1.42（SpringBoot 3.3.13默認版本）；BCD模塊依賴A模塊，導致傳遞引入10.1.42，與父模塊的10.1.54沖突。
關鍵原因：父模塊直接在dependencies中引入依賴，優(yōu)先級低于SpringBoot自帶的版本管理；且未通過dependencyManagement統(tǒng)一鎖定版本。
1.2 解決方案（父模塊優(yōu)化）
核心原則：父模塊只通過dependencyManagement管理版本，不直接在dependencies中引入任何依賴。
<properties>
<spring-boot.version>3.3.13</spring-boot.version>
<tomcat.version>10.1.54</tomcat.version> <!-- 統(tǒng)一tomcat版本 -->
</properties>
<dependencyManagement>
<dependencies>
<!-- Spring Boot 官方依賴管理 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- 強制鎖定tomcat版本，覆蓋SpringBoot默認版本 -->
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-core</artifactId>
<version>${tomcat.version}</version>
</dependency>
</dependencies>
</dependencyManagement>
<!-- 父模塊dependencies標簽為空，不引入任何依賴 -->
<dependencies>
</dependencies>后續(xù)操作：刪除父模塊中所有直接引入的依賴（tomcat-embed-core、spring-boot-starter-web），A模塊正常引入spring-boot-starter-web即可，無需排除tomcat，會自動繼承父模塊鎖定的10.1.54版本。
問題2：spring-security-web版本升級不生效（需升級至6.5.10）
2.1 問題根源
A模塊引入spring-boot-starter-security，父模塊通過dependencyManagement鎖定spring-security.version=6.5.10，但版本不生效，A/B模塊仍顯示6.3.10（SpringBoot 3.3.13默認版本）。
關鍵原因：spring-security-bom的導入順序在spring-boot-dependencies之后，Maven規(guī)則“先導入的bom優(yōu)先級更高”，導致SpringBoot自帶的版本覆蓋了我們鎖定的版本。
2.2 解決方案（調(diào)整父模塊bom導入順序）
<properties>
<spring-boot.version>3.3.13</spring-boot.version>
<tomcat.version>10.1.54</tomcat.version>
<spring-security.version>6.5.10</spring-security.version> <!-- 統(tǒng)一security版本 -->
</properties>
<dependencyManagement>
<dependencies>
<!-- 重點：spring-security-bom放前面，優(yōu)先級高于SpringBoot自帶版本 -->
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-bom</artifactId>
<version>${spring-security.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- Spring Boot 官方依賴放后面 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- tomcat版本鎖定 -->
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-core</artifactId>
<version>${tomcat.version}</version>
</dependency>
</dependencies>
</dependencyManagement>驗證方法：在A/B模塊目錄執(zhí)行命令 mvn dependency:tree -Dincludes=org.springframework.security:spring-security-web，輸出結果中版本為6.5.10即生效。
注意：無需在A模塊做任何排除操作，保持spring-boot-starter-security的正常引入即可。
問題3：非公共依賴（security）污染無關模塊（C/D）
3.1 問題根源
A模塊作為通用模塊，引入了只有B模塊需要的spring-boot-starter-security，導致依賴A的C/D模塊也被動引入了security，造成冗余和不必要的依賴污染。
關鍵原因：模塊依賴設計不合理，將“非公共依賴”放入了通用模塊A中。
3.2 解決方案（模塊化拆分，按需依賴）
核心原則：通用模塊A只放“所有子模塊（BCD）都需要”的依賴，非公共依賴由需要的模塊自己引入。
- 第一步：清理A模塊，移除spring-boot-starter-security依賴（A模塊只保留mybatis-plus、redis、dao、service等公共依賴）；
- 第二步：B模塊自己引入spring-boot-starter-security（因為只有B需要）；
- 第三步：C/D模塊只依賴A模塊，不引入任何多余依賴。
具體配置：
<!-- A模塊pom.xml（清理后） -->
<dependencies>
<!-- 公共依賴：BCD都需要 -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
</dependency>
<!-- 其他公共service、dao相關依賴 -->
</dependencies>
<!-- B模塊pom.xml（自己引入security） -->
<dependencies>
<!-- 依賴通用模塊A -->
<dependency>
<groupId>xxx</groupId>
<artifactId>A</artifactId>
</dependency>
<!-- 自己需要的security，不傳遞給C/D -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
</dependencies>
<!-- C/D模塊pom.xml（只依賴A） -->
<dependencies>
<dependency>
<groupId>xxx</groupId>
<artifactId>A</artifactId>
</dependency>
</dependencies>效果：B模塊有security功能，C/D模塊無security依賴，徹底解決依賴污染，無需任何排除操作。
三、最終優(yōu)化后的標準架構（企業(yè)級最佳實踐）
優(yōu)化后結構，徹底解決所有問題，兼顧復用性和可維護性：
父項目（parent）
├── 核心職責：只通過dependencyManagement管理所有依賴版本，dependencies為空
├── A模塊（core-service，通用模塊）
│ ├── 核心職責：提供公共數(shù)據(jù)層、服務層能力，所有子模塊都需要
│ ├── 依賴：mybatis-plus、redis、數(shù)據(jù)庫驅(qū)動、公共entity/dao/service/工具類
│ └── 不包含：web、security等非公共依賴
├── B模塊（業(yè)務模塊）
│ ├── 依賴：A模塊 + 自身需要的security等依賴
│ └── 核心職責：業(yè)務邏輯實現(xiàn)（需要security）
├── C模塊（業(yè)務模塊）
│ ├── 依賴：只依賴A模塊
│ └── 核心職責：業(yè)務邏輯實現(xiàn)（不需要security）
└── D模塊（業(yè)務模塊）
├── 依賴：只依賴A模塊
└── 核心職責：業(yè)務邏輯實現(xiàn)（不需要security）四、關鍵注意點（避坑核心）
結合本次排查，總結10個高頻避坑點，覆蓋依賴管理和模塊設計：
- 父模塊核心原則：只管理版本，不引入依賴，所有依賴通過dependencyManagement鎖定，dependencies標簽為空，避免子模塊被動繼承不必要的依賴；
- bom導入順序：自定義版本的bom（如spring-security-bom）必須放在spring-boot-dependencies前面，否則會被SpringBoot默認版本覆蓋；
- 通用模塊A的定位：只放“所有子模塊都需要”的依賴，非公共依賴（如security、web）絕對不放入；
- 版本統(tǒng)一：所有核心依賴（tomcat、security、mybatis-plus等）在父模塊properties中定義變量，統(tǒng)一管理，避免硬編碼；
- 依賴傳遞：子模塊依賴通用模塊時，會自動繼承其所有依賴，因此通用模塊必須“干凈”，不引入非公共依賴；
- 避免排除濫用：排除（exclusion）只用于臨時救急，長期解決方案是“按需依賴”，拆分模塊，而非大量使用排除；
- 版本驗證：修改依賴后，用
mvn dependency:tree命令驗證版本是否正確，避免隱性沖突； - SpringBoot與組件版本兼容性：SpringBoot 3.3.13默認對應spring-security 6.3.x，升級至6.5.x需確認API兼容性（本次實踐無問題）；
- 模塊命名規(guī)范：通用模塊建議命名為core-service、common-core等，明確其定位，避免混淆；
- 長期維護：定期清理無用依賴，保持模塊“瘦身”，避免依賴冗余導致的沖突和性能問題。
五、總結
SpringBoot多模塊項目的核心痛點的是“依賴沖突”和“模塊設計不合理”，本次實踐通過“父模塊版本統(tǒng)一管理+通用模塊瘦身+按需依賴”，徹底解決了tomcat、spring-security版本沖突，以及非公共依賴污染問題。
核心思路：模塊化設計的本質(zhì)是“職責清晰、按需依賴”，父模塊管版本，通用模塊管公共能力，業(yè)務模塊管自身需求，這樣既能保證代碼復用，又能避免依賴混亂，提升項目可維護性。
本文所有配置均經(jīng)過實際項目驗證，可直接復制使用，若遇到類似問題，可對照排查，也歡迎在評論區(qū)交流補充。
以上就是SpringBoot多模塊依賴沖突排查與架構優(yōu)化實戰(zhàn)的詳細內(nèi)容，更多關于SpringBoot多模塊依賴沖突排查與優(yōu)化的資料請關注腳本之家其它相關文章！
相關文章
這篇文章主要介紹了springEL表達式詳解及應用，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-08-08
項目中經(jīng)常會使用到導出功能,有導出Word,有導出Excel的,下面這篇文章主要給大家介紹了關于JAVA中excel導出一對多合并具體實現(xiàn)的相關資料,需要的朋友可以參考下2023-09-09
該文章介紹了將Idea項目上傳至Gitee的步驟,包括創(chuàng)建本地倉庫、添加到緩沖區(qū)、提交到本地倉庫、推送至遠程倉庫等以及從Gitee拉取項目的方法,整個過程涉及到創(chuàng)建遠程倉庫、項目上傳、更新項目等和提交等內(nèi)容2026-04-04
Mockito+PowerMock+Junit單元測試用途解析
本文介紹單元測試在開發(fā)和DevOps中的規(guī)范要求,詳解Mockito和PowerMock的使用,包括解耦依賴、模擬行為、驗證調(diào)用及參數(shù)匹配,同時說明SpringBoot測試注解（如@MockBean）的用法,并提及IDEA插件Squaretest的自動化測試生成功能,感興趣的朋友一起看看吧2025-06-06
本文主要介紹了MyBatis中TypeHandler基本用法與示例,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友們下面隨著小編來一起學習學習吧2025-11-11
針對應用中異步調(diào)用，能不能像同步調(diào)用一樣立刻獲取到命令的執(zhí)行結果，如何實現(xiàn)異步轉(zhuǎn)同步？不要擔心，本文就來為大家詳細講講Java中異步轉(zhuǎn)同步的六種方法，感興趣的可以了解一下2022-06-06
Springboot搭建JVM監(jiān)控(Springboot + Prometheus +&n
在應用開發(fā)時,監(jiān)控報警必不可少,本文主要介紹了Springboot搭建JVM監(jiān)控(Springboot + Prometheus + Grafana),具有一定的參考價值,感興趣的可以了解一下2024-05-05
springboot整合mybatis-plus實現(xiàn)多表分頁查詢的示例代碼
這篇文章主要介紹了springboot整合mybatis-plus實現(xiàn)多表分頁查詢的示例代碼，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2021-03-03
這篇文章主要介紹了java中如何使用HttpClient調(diào)用接口，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-10-10
這篇文章主要介紹了Java枚舉類接口實例原理解析,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2020-01-01