Maven 多模块项目结构解析

项目父模块 POM 配置分析

以下是一个典型的多模块 Maven 项目的父 POM 配置示例：

xml

<?xml version="1.0" encoding="UTF-8"?>
<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 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <!-- 项目基本信息 -->
    <groupId>org.example</groupId>
    <artifactId>wyl-iot</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    
    <!-- 继承 Spring Boot 父项目 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.18</version>
        <relativePath/>
    </parent>
    
    <!-- 模块定义 -->
    <modules>
        <module>iot-common</module>
        <module>iot-gateway</module>
        <module>iot-mqtt</module>
    </modules>
    
    <!-- 统一属性配置 -->
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <hutool.version>5.8.11</hutool.version>
        <mqtt.version>1.2.5</mqtt.version>
    </properties>
    
    <!-- 依赖版本管理 -->
    <dependencyManagement>
        <dependencies>
            <!-- MQTT 客户端依赖管理 -->
            <dependency>
                <groupId>org.eclipse.paho</groupId>
                <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
                <version>${mqtt.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
    
    <!-- 子模块共享依赖 -->
    <dependencies>
        <!-- Lombok 注解处理器 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>
        
        <!-- Hutool 工具库 -->
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>${hutool.version}</version>
        </dependency>
    </dependencies>
</project>

父 POM 关键特性解析

1. 继承机制

通过继承 spring-boot-starter-parent，项目自动获得 Spring Boot 的默认配置和依赖管理

子模块可以无需指定版本号直接使用 Spring Boot 相关依赖，例如：

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. 依赖管理

<dependencyManagement> 节用于统一管理依赖版本，确保多模块间版本一致性
声明的依赖不会直接引入，需要在子模块中显式引用

子模块引用时无需指定版本号：

xml

<dependency>
    <groupId>org.eclipse.paho</groupId>
    <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
</dependency>

3. 共享依赖

在 <dependencies> 节中定义的依赖会被所有子模块继承
这些依赖会通过依赖传递机制自动提供给子模块使用

子模块 POM 配置示例

以下是一个子模块的典型 POM 配置：

xml

<?xml version="1.0" encoding="UTF-8"?>
<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 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <!-- 指定父模块 -->
    <parent>
        <groupId>org.example</groupId>
        <artifactId>wyl-iot</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    
    <!-- 子模块标识 -->
    <artifactId>iot-mqtt</artifactId>
    
    <!-- 模块特定依赖 -->
    <dependencies>
        <!-- 引用同一项目中的其他模块 -->
        <dependency>
            <groupId>org.example</groupId>
            <artifactId>iot-common</artifactId>
            <version>${project.version}</version>
        </dependency>
        
        <!-- Spring Boot 相关依赖（无需版本号） -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- 父模块依赖管理中定义的依赖 -->
        <dependency>
            <groupId>org.eclipse.paho</groupId>
            <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
        </dependency>
        
        <!-- 其他第三方依赖 -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
        </dependency>
        
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>
    </dependencies>
    
    <!-- 构建配置 -->
    <build>
        <plugins>
            <!-- Spring Boot 打包插件 -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

子模块关键特性解析

1. 属性继承

子模块可以引用父模块中定义的所有属性
例如：${maven.compiler.source} 引用父模块中定义的 Java 版本

2. 依赖管理

子模块自动继承父模块的依赖管理配置
对于父模块中已通过 <dependencies> 定义的依赖（如 Lombok、Hutool），子模块无需显式声明即可使用
对于父模块中仅在 <dependencyManagement> 定义的依赖，子模块需要显式声明依赖但无需指定版本号
Spring Boot 相关依赖也无需指定版本号，由继承的 Spring Boot 父 POM 管理

3. 模块间依赖

子模块可以依赖同一项目中的其他模块
建议使用 ${project.version} 确保版本一致性

maven中的坑

依赖管理问题

父POM

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version>
</parent>

<!-- 通过import scope导入BOM -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2021.0.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

子模块：

<parent>
    <groupId>org.example</groupId>
    <artifactId>wyl-iot</artifactId>
    <version>1.0-SNAPSHOT</version>
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId><!-- 不需要指定版本 -->
        
        <!--nacos 服务注册发现-->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>

        <!--负载均衡-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-loadbalancer</artifactId>
        </dependency>

        <!--网关-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway</artifactId>
        </dependency>
    </dependency>
</dependencies>

如果版本管理中引入的spring-cloud-dependencies中没有使用import。子模块会找不到版本号。例如，这里如果去掉了。下面的：nacos 服务注册发现、负载均衡、网关统统找不到。但是，如果加了一次版本号，构建后去掉版本号又能找到了。所以这里有个坑。

原因分析：

已经使用了spring-boot-starter-parent作为parent，不能再有另一个parent。所以对于Spring Cloud的依赖管理，只能通过import scope来导入。

总结：Spring Boot starters不需要指定版本是因为版本管理通过parent继承，而Spring Cloud组件需要通过import scope导入BOM来进行版本管理。

scope	说明
compile	默认值。表示依赖在编译、测试、运行阶段都可用。这类依赖会被打包进最终的 artifact（如 JAR/WAR）。
provided	表示依赖在编译和测试时需要，但在运行时由容器或 JDK 提供，不会被打包。典型场景：Servlet API、JSP API 等。
runtime	表示依赖在编译阶段不需要，但在运行和测试时需要。例如 JDBC 驱动，编译时仅通过接口编程，运行时才需要具体实现。
test	表示依赖仅在测试编译和执行时有效，不会传递到其他模块，也不会被打包。例如 JUnit、Mockito。
system	类似 `provided`，但依赖不是从 Maven 仓库获取，而是通过 `<systemPath>` 显式指定本地文件路径。通常用于引入系统路径中的 JAR，不推荐使用。
import	仅用于 `<dependencyManagement>` 中，且 `type` 必须为 `pom`。它表示将目标 POM 的 `<dependencyManagement>` 内容合并到当前项目的依赖管理中，常用于统一管理多个模块的版本（如 Spring Boot BOM、Spring Cloud BOM）。

Maven注意事项

一个项目不能直接依赖parent模块，例如

<?xml version="1.0" encoding="UTF-8"?>
<project>
    <parent>
        <artifactId>java-study</artifactId>
        <groupId>psn.wyl</groupId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>http-ota</artifactId>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId> <!--这里直接依赖行不通-->
            <version>2.7.18</version>
            <scope>import</scope>
        </dependency>
    </dependencies>
</project>

解决方法

<?xml version="1.0" encoding="UTF-8"?>
<project>
    <parent>
        <artifactId>java-study</artifactId>
        <groupId>psn.wyl</groupId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>http-ota</artifactId>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId> <!--不依赖parent-->
            <version>2.7.18</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

坑2

父pom


<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>${mybatis.plus.version}</version>
        </dependency>
        <!-- 缺少 mybatis-plus-core 的版本管理 -->
    </dependencies>
</dependencyManagement>

子pom

<dependencies>
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-core</artifactId>
        </dependency>
</dependencies>

这时候，项目是拿不到mybatis-plus-core依赖包的

只有这种写法可以

<dependencies>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
    </dependency>
</dependencies>

如果已经有还想依赖spirngboot

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>2.7.18</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.kafka</groupId>
        <artifactId>spring-kafka</artifactId>
        <version>2.9.11</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

📒 笔记文档