一、起源
- 业务代码按模块拆分后,如果所有配置堆在单个 POM 中,任何版本调整都要在多个模块重复修改,容易遗漏。
- 逐模块独立构建又带来两个问题:构建顺序需要人工判断,公共配置需要在每个模块复制一份。
- Maven 用聚合解决"一次构建多个模块",用继承解决"公共配置只写一份"。两者常同时出现在父 POM 中,但并不是同一机制。
二、原理
2.1 聚合与继承的区别
| 维度 | 聚合(<modules>) | 继承(<parent>) |
| 声明位置 | 聚合 POM 中列出子模块目录 | 子模块 POM 中声明父 POM 坐标 |
| 解决的问题 | 一条命令构建多个模块 | 复用依赖管理、插件管理、属性 |
| 方向 | 父到子 | 子到父 |
| 是否要求 packaging=pom | 是 | 否,父 POM 通常是 pom 打包 |
| 是否强制耦合 | 被聚合的模块可以不继承该父 POM | 被继承的父 POM 不一定聚合该子模块 |
- 两者可以合并到同一个 POM:既写
<modules> 又作为 <parent> 被引用,此时该 POM 同时承担聚合与继承职责。
- 大型工程中也可以分离:一个 POM 只负责聚合,另一个 POM 只负责提供依赖与插件管理。
2.2 reactor 构建顺序
- reactor 是本次构建中所有模块的集合,顺序按模块之间的依赖关系确定。
- 无依赖关系的模块之间按
<modules> 的声明顺序构建。
- 存在循环依赖时,reactor 无法排序,构建直接失败并提示
The projects in the reactor contain a cyclic reference。
2.3 relativePath 解析规则
- 子模块通过
<relativePath> 指向父 POM 的相对路径,默认值为 ../pom.xml。
- 构建时优先按
relativePath 查找父 POM,找不到再按坐标从仓库解析。
relativePath 指向错误时,Maven 会去本地仓库找父 POM,父 POM 未安装则报 Non-resolvable parent POM。
2.4 版本继承
groupId 与 version 可从父 POM 继承,子模块只需声明 artifactId。
- 父 POM 的
dependencyManagement 与 pluginManagement 只提供版本与配置,不引入依赖或激活插件。
- 父 POM 的
<dependencies> 与 <build><plugins> 会被所有子模块无条件继承,应谨慎使用。
三、实现
3.1 目录结构
demo-parent
pom.xml 聚合 POM,同时作为父 POM
demo-common/pom.xml
demo-service/pom.xml
demo-web/pom.xml
3.2 父 POM
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>demo-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<modules>
<module>demo-common</module>
<module>demo-service</module>
<module>demo-web</module>
</modules>
<properties>
<java.version>17</java.version>
<spring.boot.version>3.2.5</spring.boot.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>demo-common</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring.boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<release>${java.version}</release>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>
packaging=pom 表示该模块只承载配置与聚合,不产出构件。
- 子模块之间引用使用
${project.version} 作为版本,避免逐模块修改版本号。
3.3 子模块 POM
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.example</groupId>
<artifactId>demo-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>demo-service</artifactId>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>demo-common</artifactId>
</dependency>
</dependencies>
</project>
groupId 与 version 继承自父 POM 时可省略。
demo-common 的版本由父 POM 的 dependencyManagement 提供,子模块不写版本号。
relativePath 与父 POM 实际位置不一致时会导致父 POM 解析失败。
3.4 局部构建
# 只构建 demo-web 及其依赖
mvn -pl demo-web -am clean package
# 只构建 demo-common 及其下游
mvn -pl demo-common -amd clean package
# 跳过测试构建全部模块
mvn -T 1C clean package -DskipTests
3.5 版本统一
- 常规做法:父 POM 与所有子模块使用同一个版本号,发布前用
mvn versions:set -DnewVersion=1.1.0 一次修改全部模块,再执行 mvn versions:commit 确认。
- CI 中需要动态注入版本时,可使用
revision 属性配合 flatten-maven-plugin:
<properties>
<revision>1.0.0-SNAPSHOT</revision>
</properties>
- 父 POM 与子模块的
<version> 均写 ${revision},构建时用 mvn -Drevision=1.0.0 覆盖。
- 该方式需要
flatten-maven-plugin 生成可安装的 POM,否则安装到仓库的 POM 中仍是占位符。发布流程见 Maven 版本管理与发布流程。
3.6 依赖与插件的继承选择
| 配置 | 写在父 POM 的效果 | 建议 |
dependencyManagement | 只统一版本,子模块按需声明 | 默认使用 |
dependencies | 所有子模块强制引入 | 仅用于全工程通用依赖 |
pluginManagement | 只统一插件版本与配置,不激活 | 默认使用 |
build/plugins | 所有子模块强制激活 | 仅用于必须全量执行的插件 |
四、常见问题
| 现象 | 常见原因 | 处理方式 |
Non-resolvable parent POM | 父 POM 未安装,且 relativePath 未指向正确位置 | 修正 relativePath,或在父目录执行 mvn install |
| 子模块单独构建失败 | 依赖的内部模块未安装到本地仓库 | 使用 mvn -pl 模块 -am,或先安装依赖模块 |
cyclic reference | 模块之间互相依赖 | 抽取公共模块,调整依赖方向 |
| 子模块声明了依赖但没有版本 | 父 POM 的 dependencyManagement 未包含该构件 | 在父 POM 中补充版本,或在子模块显式声明 |
| 修改父 POM 后子模块行为未变化 | 子模块实际继承的父 POM 是仓库中的旧版本 | 修正 relativePath,或重新安装父 POM |
revision 占位符进入仓库 | 未配置 flatten-maven-plugin | 增加 flatten 配置,安装前生成可解析的 POM |
五、总结
- 聚合解决"一次构建多个模块",继承解决"配置复用",两者可以合并,也可以分离。
- reactor 按模块依赖排序,循环依赖会导致构建直接失败。
- 父 POM 提供
dependencyManagement 与 pluginManagement,避免向所有子模块强加依赖与插件。
relativePath 决定父 POM 的查找位置,是 Non-resolvable parent POM 的首要排查点。