前言：在SpringBoot多模塊項目開發(fā)中，依賴沖突、版本不一致、模塊依賴設(shè)計不合理是最常見的“攔路虎”。本文結(jié)合實際項目場景，記錄從依賴版本沖突（tomcat、spring-security）到模塊架構(gòu)優(yōu)化的完整排查、解決過程，總結(jié)企業(yè)級多模塊最佳實踐，幫助更多開發(fā)者避坑，提升項目可維護性。

本文核心解決場景：父模塊+通用模塊A+業(yè)務(wù)模塊BCD的多模塊結(jié)構(gòu)中，依賴版本沖突、非公共依賴污染無關(guān)模塊、模塊依賴設(shè)計不合理等問題，全程貼合實際開發(fā)場景，提供可直接復(fù)用的解決方案。

一、項目初始結(jié)構(gòu)（問題場景）

先明確項目初始結(jié)構(gòu)，也是問題的起源，方便大家對號入座：

父項目（parent）
├── A模塊（通用模塊）：包含service、dao、工具類，引入mybatis-plus、redis、spring-boot-starter-security等
├── B模塊（業(yè)務(wù)模塊）：依賴A模塊，需要security功能
├── C模塊（業(yè)務(wù)模塊）：依賴A模塊，不需要security功能
└── D模塊（業(yè)務(wù)模塊）：依賴A模塊，不需要security功能

初始問題匯總：

1. 父模塊在dependencies中直接引入tomcat-embed-core、spring-boot-starter-web（帶排除），導(dǎo)致子模塊出現(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. 父模塊未遵循“只管理版本，不引入依賴”的原則，導(dǎo)致依賴傳遞混亂。

二、核心問題排查與解決方案（按優(yōu)先級）

以下解決方案按“先解決緊急沖突，再優(yōu)化架構(gòu)”的順序，每一步都貼合實際操作，可直接復(fù)制配置使用。

問題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默認(rèn)版本）；BCD模塊依賴A模塊，導(dǎo)致傳遞引入10.1.42，與父模塊的10.1.54沖突。

關(guān)鍵原因：父模塊直接在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默認(rèn)版本 -->
        <dependency>
            <groupId>org.apache.tomcat.embed</groupId>
            <artifactId>tomcat-embed-core</artifactId>
            <version>${tomcat.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>
<!-- 父模塊dependencies標(biāo)簽為空，不引入任何依賴 -->
<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默認(rèn)版本）。

關(guān)鍵原因：spring-security-bom的導(dǎo)入順序在spring-boot-dependencies之后，Maven規(guī)則“先導(dǎo)入的bom優(yōu)先級更高”，導(dǎo)致SpringBoot自帶的版本覆蓋了我們鎖定的版本。

2.2 解決方案（調(diào)整父模塊bom導(dǎo)入順序）

<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，輸出結(jié)果中版本為6.5.10即生效。

注意：無需在A模塊做任何排除操作，保持spring-boot-starter-security的正常引入即可。

問題3：非公共依賴（security）污染無關(guān)模塊（C/D）

3.1 問題根源

A模塊作為通用模塊，引入了只有B模塊需要的spring-boot-starter-security，導(dǎo)致依賴A的C/D模塊也被動引入了security，造成冗余和不必要的依賴污染。

關(guān)鍵原因：模塊依賴設(shè)計不合理，將“非公共依賴”放入了通用模塊A中。

3.2 解決方案（模塊化拆分，按需依賴）

核心原則：通用模塊A只放“所有子模塊（BCD）都需要”的依賴，非公共依賴由需要的模塊自己引入。

1. 第一步：清理A模塊，移除spring-boot-starter-security依賴（A模塊只保留mybatis-plus、redis、dao、service等公共依賴）；
2. 第二步：B模塊自己引入spring-boot-starter-security（因為只有B需要）；
3. 第三步：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相關(guān)依賴 -->
</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)化后的標(biāo)準(zhǔn)架構(gòu)（企業(yè)級最佳實踐）

優(yōu)化后結(jié)構(gòu)，徹底解決所有問題，兼顧復(fù)用性和可維護性：

父項目（parent）
├── 核心職責(zé)：只通過dependencyManagement管理所有依賴版本，dependencies為空
├── A模塊（core-service，通用模塊）
│   ├── 核心職責(zé)：提供公共數(shù)據(jù)層、服務(wù)層能力，所有子模塊都需要
│   ├── 依賴：mybatis-plus、redis、數(shù)據(jù)庫驅(qū)動、公共entity/dao/service/工具類
│   └── 不包含：web、security等非公共依賴
├── B模塊（業(yè)務(wù)模塊）
│   ├── 依賴：A模塊 + 自身需要的security等依賴
│   └── 核心職責(zé)：業(yè)務(wù)邏輯實現(xiàn)（需要security）
├── C模塊（業(yè)務(wù)模塊）
│   ├── 依賴：只依賴A模塊
│   └── 核心職責(zé)：業(yè)務(wù)邏輯實現(xiàn)（不需要security）
└── D模塊（業(yè)務(wù)模塊）
    ├── 依賴：只依賴A模塊
    └── 核心職責(zé)：業(yè)務(wù)邏輯實現(xiàn)（不需要security）

四、關(guān)鍵注意點（避坑核心）

結(jié)合本次排查，總結(jié)10個高頻避坑點，覆蓋依賴管理和模塊設(shè)計：

1. 父模塊核心原則：只管理版本，不引入依賴，所有依賴通過dependencyManagement鎖定，dependencies標(biāo)簽為空，避免子模塊被動繼承不必要的依賴；
2. bom導(dǎo)入順序：自定義版本的bom（如spring-security-bom）必須放在spring-boot-dependencies前面，否則會被SpringBoot默認(rèn)版本覆蓋；
3. 通用模塊A的定位：只放“所有子模塊都需要”的依賴，非公共依賴（如security、web）絕對不放入；
4. 版本統(tǒng)一：所有核心依賴（tomcat、security、mybatis-plus等）在父模塊properties中定義變量，統(tǒng)一管理，避免硬編碼；
5. 依賴傳遞：子模塊依賴通用模塊時，會自動繼承其所有依賴，因此通用模塊必須“干凈”，不引入非公共依賴；
6. 避免排除濫用：排除（exclusion）只用于臨時救急，長期解決方案是“按需依賴”，拆分模塊，而非大量使用排除；
7. 版本驗證：修改依賴后，用mvn dependency:tree命令驗證版本是否正確，避免隱性沖突；
8. SpringBoot與組件版本兼容性：SpringBoot 3.3.13默認(rèn)對應(yīng)spring-security 6.3.x，升級至6.5.x需確認(rèn)API兼容性（本次實踐無問題）；
9. 模塊命名規(guī)范：通用模塊建議命名為core-service、common-core等，明確其定位，避免混淆；
10. 長期維護：定期清理無用依賴，保持模塊“瘦身”，避免依賴冗余導(dǎo)致的沖突和性能問題。

五、總結(jié)

SpringBoot多模塊項目的核心痛點的是“依賴沖突”和“模塊設(shè)計不合理”，本次實踐通過“父模塊版本統(tǒng)一管理+通用模塊瘦身+按需依賴”，徹底解決了tomcat、spring-security版本沖突，以及非公共依賴污染問題。

核心思路：模塊化設(shè)計的本質(zhì)是“職責(zé)清晰、按需依賴”，父模塊管版本，通用模塊管公共能力，業(yè)務(wù)模塊管自身需求，這樣既能保證代碼復(fù)用，又能避免依賴混亂，提升項目可維護性。

本文所有配置均經(jīng)過實際項目驗證，可直接復(fù)制使用，若遇到類似問題，可對照排查，也歡迎在評論區(qū)交流補充。

以上就是SpringBoot多模塊依賴沖突排查與架構(gòu)優(yōu)化實戰(zhàn)的詳細(xì)內(nèi)容，更多關(guān)于SpringBoot多模塊依賴沖突排查與優(yōu)化的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論