Maven 依赖传递与排除基础逻辑

Maven 依赖排除：父模块与子模块的处理实践

在 Maven 项目构建中，依赖管理是核心环节之一。合理处理依赖的传递与排除，能有效避免依赖冲突、精简项目依赖树。本文结合实际项目结构，详细讲解父模块与子模块间依赖排除的逻辑，并通过示例演示配置调整，助力大家清晰掌握 Maven 依赖排除的实操要点。

一、项目初始结构与需求背景

1. 原始项目结构

我们有一个多模块 Maven 项目，父模块为 hbis-test-service，其包含多个子模块，结构如下：

hbis-test-service 
├── .idea
├── hbis-test-service-api
├── hbis-test-service-app
├── hbis-test-service-common
├── hbis-test-service-domain
├── hbis-test-service-generator
├── hbis-test-service-infrastructure
├── hbis-test-service-mq
│   ├── src
│   ├── target
│   └── pom.xml
├── logs
├── .gitignore
├── .gitlab-ci.yml
└── pom.xml

梳理 tthh-oplog-sdk-starter 依赖排除逻辑。

2. 依赖排除场景

项目中引入了 com.tthh.middleware:hbis-oplog-sdk-starter 依赖，需排除其传递的 cn.hutool:hutool-all 依赖，要清晰处理父模块与子模块间依赖排除的继承与覆盖问题。

二、Maven 依赖传递与排除基础逻辑

1. 依赖传递机制

Maven 中，依赖会沿父子模块、"依赖的依赖"关系传递 。例如父模块依赖 A，A 依赖 B，子模块引入父模块后，默认会传递获得 B 依赖（除非主动排除）。这种传递机制方便了依赖复用，但也可能引入不必要依赖或冲突。

2. 排除依赖（exclusions）作用

exclusions 用于声明依赖时，主动剔除该依赖传递的某个子依赖，让其不进入当前模块依赖树。语法如下：

<dependency>
    <groupId>...</groupId>
    <artifactId>...</artifactId>
    <version>...</version>
    <exclusions>
        <exclusion>
            <groupId>要排除的子依赖groupId</groupId>
            <artifactId>要排除的子依赖artifactId</artifactId>
        </exclusion>
    </exclusions>
</dependency>

三、父模块与子模块依赖排除实践

1. 项目结构

结构：

hbis-test-service 
├── .idea
├── hbis-test-service-api
├── hbis-test-service-app
├── hbis-test-service-common
├── hbis-test-service-domain
├── hbis-test-service-generator
├── hbis-test-service-infrastructure
├── hbis-test-service-mq
│   ├── src
│   ├── target
│   └── pom.xml
├── logs
├── .gitignore
├── .gitlab-ci.yml
└── pom.xml

2. 父模块依赖排除配置

在父模块 hbis-test-service 的 pom.xml 中，若直接在 <dependencies> 配置 hbis-oplog-sdk-starter 依赖及排除：

<dependencies>
    <dependency>
        <groupId>com.tthh.middleware</groupId>
        <artifactId>tthh-oplog-sdk-starter</artifactId>
        <version>${tthh-oplog.version}</version>
        <exclusions>
            <exclusion>
                <groupId>cn.hutool</groupId>
                <artifactId>hutool-all</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
</dependencies>

注意 ：父模块 <dependencies> 里的排除，仅影响父模块自身依赖树，不会自动传递给子模块 。子模块若自己声明该依赖，需重新考虑排除配置。

若在父模块 <dependencyManagement> 中配置（更推荐，用于统一版本和依赖管理）：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tthh.middleware</groupId>
            <artifactId>tthh-oplog-sdk-starter</artifactId>
            <version>${tthh-oplog.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>cn.hutool</groupId>
                    <artifactId>hutool-all</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
</dependencyManagement>

此时，子模块显式声明 该依赖时，若未重新指定 <exclusions>，会继承父模块 <dependencyManagement> 的排除规则，无需重复配置。

3. 子模块依赖排除处理

• 子模块未直接声明依赖 ：若子模块（如 hbis-test-service-mq）未自己声明 hbis-oplog-sdk-starter 依赖，仅通过父模块传递，父模块的排除规则（无论在 <dependencies> 还是 <dependencyManagement> ）不影响子模块（因子模块没引入相关传递依赖）。
• 子模块直接声明依赖 ：若子模块自己声明了 hbis-oplog-sdk-starter 依赖：

  • 若父模块在 <dependencyManagement> 配置了排除，子模块声明时可直接复用：

    <dependencies>
        <dependency>
            <groupId>com.tthh.middleware</groupId>
            <artifactId>tthh-oplog-sdk-starter</artifactId>
            <!-- 无需重复写版本和排除，继承父模块 dependencyManagement 配置 -->
        </dependency>
    </dependencies>

  • 若父模块在 <dependencies> 配置排除，或子模块需自定义排除，需在子模块 pom.xml 中重新配置 <exclusions>：

    <dependency>
        <groupId>com.hbis.middleware</groupId>
        <artifactId>tthh-oplog-sdk-starter</artifactId>
        <version>${tthh-oplog.version}</version>
        <exclusions>
            <exclusion>
                <groupId>cn.hutool</groupId>
                <artifactId>hutool-all</artifactId>
            </exclusion>
        </exclusions>
    </dependency>

四、验证与调试

1. 查看依赖树

使用 mvn dependency:tree 命令，分别查看父模块和子模块的依赖树，验证排除是否生效。例如，在父模块根目录执行：

mvn dependency:tree -Dverbose

在子模块目录（如 hbis-test-service-mq）执行：

cd hbis-test-service-mq
mvn dependency:tree -Dverbose

通过依赖树，可清晰看到 hutool-all 是否被排除，以及依赖传递路径。

2. 常见问题排查

• 排除未生效 ：检查 <exclusion> 中 groupId 和 artifactId 是否与实际依赖一致；确认依赖声明位置（<dependencies> 或 <dependencyManagement> ）是否符合继承逻辑。
• 依赖冲突 ：若仍存在依赖冲突，结合 dependency:tree 分析冲突来源，调整排除策略或依赖版本。

五、总结

Maven 依赖排除需关注父模块与子模块的配置继承关系：

1. 父模块 <dependencyManagement> 的排除规则，子模块显式声明依赖时可直接继承，简化配置。
2. 父模块 <dependencies> 的排除仅影响自身，子模块需自己声明排除。
3. 利用 mvn dependency:tree 可有效验证依赖排除效果，排查问题。

合理运用依赖排除，能优化项目依赖结构，避免冲突，提升构建稳定性。大家可根据实际项目需求，灵活调整父模块与子模块的依赖配置，让 Maven 依赖管理更高效 。