一、起源

  • 业务代码按模块拆分后,如果所有配置堆在单个 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

五、总结

  1. 聚合解决"一次构建多个模块",继承解决"配置复用",两者可以合并,也可以分离。
  2. reactor 按模块依赖排序,循环依赖会导致构建直接失败。
  3. 父 POM 提供 dependencyManagement 与 pluginManagement,避免向所有子模块强加依赖与插件。
  4. relativePath 决定父 POM 的查找位置,是 Non-resolvable parent POM 的首要排查点。