当前位置：首页 > news >正文

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

news 2025/8/28 7:06:46

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 分析冲突来源，调整排除策略或依赖版本。