Maven 多模块项目工程化实践：依赖管理、资源过滤与构建优化

作者： 必码｜ bima.cc

前言

在企业级 Java 开发中，Maven 作为最主流的项目构建工具，其多模块管理能力直接决定了项目的可维护性和团队协作效率。然而，许多开发者对 Maven 的理解仅停留在 mvn clean install 的层面，对其背后的依赖传递机制、资源过滤原理、打包策略等工程化细节缺乏深入认知。

本文基于 smart-scaffold 项目中三种主流微服务架构（SpringBoot 单体版、Dubbo 分布式版、SpringCloud 微服务版）的真实 POM 配置，系统性地梳理 Maven 多模块项目的工程化实践。我们不会堆砌完整的配置文件，而是通过简化的教学示例，帮助读者理解每一个配置决策背后的"为什么"。

无论你是正在从单体架构向微服务转型的技术负责人，还是希望深化 Maven 功底的资深开发者，这篇文章都将为你提供体系化的知识框架和可落地的实践经验。

一、Maven 多模块项目概述

1.1 为什么需要多模块

在项目规模较小时，单模块结构足以应对开发需求。但随着业务复杂度的增长，单模块项目会暴露出一系列问题：代码耦合度高、构建耗时长、职责边界模糊、团队协作冲突频繁。多模块架构正是为了解决这些问题而生的。

代码复用是多模块最直观的优势。在 smart-scaffold 项目中，无论是 SpringBoot 版、Dubbo 版还是 SpringCloud 版，都存在大量公共逻辑——数据校验、通用工具类、统一异常处理、基础实体定义等。将这些公共逻辑抽取到独立的 common 模块中，各业务模块通过 Maven 依赖引用即可，彻底消除了代码重复。

独立构建是提升开发效率的关键。在多模块项目中，修改 common 模块的某个工具方法后，只需重新构建 common 模块及其依赖方，而无需重新构建整个项目。对于包含数十个模块的大型工程，这种增量构建能力可以将日常构建时间从分钟级降低到秒级。

职责分离是架构层面的核心价值。通过模块划分，我们强制性地为代码建立了物理边界。DAO 层只负责数据访问，Service 层只负责业务编排，Web 层只负责请求处理。这种分离不仅使代码结构更清晰，也为后续的微服务拆分奠定了基础。

此外，多模块架构还带来了依赖隔离的好处。每个模块的 pom.xml 声明了该模块所需的全部依赖，使得依赖关系变得透明可控。当某个模块需要升级第三方库版本时，影响范围被限制在该模块及其直接依赖方，降低了版本变更的风险。

1.2 三种架构的模块结构对比

smart-scaffold 项目提供了三种典型的架构实现，它们的模块划分策略各有侧重，反映了不同架构范式下的设计思维。

SpringBoot 单体版采用按技术层划分的策略，包含 4 个子模块：

smart-scaffold-springboot (parent)
├── smart-scaffold-common      # 公共模块：工具类、常量、基础实体
├── smart-scaffold-dao         # 数据访问层：Mapper接口、XML映射
├── smart-scaffold-service     # 业务逻辑层：Service实现
└── smart-scaffold-web         # Web层：Controller、配置类、启动类

这种分层结构是经典的"洋葱架构"在 Maven 中的映射。依赖方向严格单向：web → service → dao → common。每一层只能依赖其下层，不能跨层依赖。这种结构在单体应用中非常成熟，清晰的层次边界使得代码审查和新人上手都更加容易。

Dubbo 分布式版采用按服务角色划分的策略，包含 3 个子模块：

smart-scaffold-dubbo (parent)
├── smart-scaffold-api          # API模块：服务接口定义、DTO
├── smart-scaffold-provider     # 服务提供者：接口实现、数据访问
└── smart-scaffold-consumer     # 服务消费者：远程调用、Web层

这种结构的核心理念是"接口与实现分离"。api 模块只定义服务接口和数据传输对象（DTO），不包含任何实现逻辑。provider 和 consumer 都依赖 api 模块，但彼此之间没有直接依赖。这种设计使得 provider 和 consumer 可以独立部署、独立升级，是 RPC 框架下的标准实践。

SpringCloud 微服务版同样按服务角色划分，但增加了一个公共模块，包含 3 个子模块：

smart-scaffold-springcloud (parent)
├── smart-scaffold-common       # 公共模块：工具类、Feign客户端定义
├── smart-scaffold-provider     # 服务提供者：业务实现、数据访问
└── smart-scaffold-consumer     # 服务消费者：API网关、Feign调用

与 Dubbo 版不同的是，SpringCloud 版的 common 模块承担了更多的职责——除了通用工具类外，还包含 Feign 客户端接口定义、统一的异常处理、以及跨服务的公共配置。这是因为 SpringCloud 生态中，服务间通信通过 HTTP/Feign 实现，接口定义天然适合放在公共模块中。

1.3 模块划分的核心原则

通过对三种架构的对比分析，我们可以提炼出模块划分的几条核心原则。

单一职责原则要求每个模块有明确的职责边界。common 模块不应包含业务逻辑，dao 模块不应包含 Controller，api 模块不应包含实现。当一个模块的职责变得模糊时，应该考虑进一步拆分。

依赖方向原则要求模块间的依赖关系形成有向无环图（DAG）。在 SpringBoot 版中，依赖链是 web → service → dao → common；在 Dubbo 版中，是 provider → api 和 consumer → api。任何形式的循环依赖都是架构设计的危险信号。

变更频率原则建议将变更频率相近的代码放在同一模块中。common 模块的变更频率最低，dao 模块次之（数据库结构变更时），service 模块较高（业务逻辑迭代），web 模块最高（接口调整、参数变更）。变更频率的差异越大，模块边界就应该越清晰。

复用维度原则强调模块的可复用性。api 模块之所以独立存在，正是因为它需要被 provider 和 consumer 同时引用。如果一个代码单元只被一个模块使用，就没有必要将其独立为模块。

二、父 POM 继承与依赖管理

2.1 Parent POM 的核心职责

在 Maven 多模块项目中，父 POM（通常称为聚合 POM 或超级 POM）是整个项目的"宪法"。它不包含任何业务代码，甚至没有 src 目录，但它的 <modules> 声明将所有子模块组织在一起，它的 <dependencyManagement> 统一了依赖版本，它的 <pluginManagement> 规范了构建行为。

父 POM 的核心职责可以归纳为以下五个方面：

第一，模块聚合。通过 <modules> 标签声明子模块列表，使得在父目录执行 mvn clean install 时，Maven 能够按照依赖顺序自动构建所有子模块。

第二，依赖版本统一。通过 <dependencyManagement> 声明所有依赖的版本号，子模块引用时无需指定版本，确保整个项目使用一致的依赖版本。

第三，插件行为规范。通过 <pluginManagement> 统一插件的版本和配置，避免各子模块因插件版本不一致导致构建行为差异。

第四，属性集中管理。通过 <properties> 定义 Java 版本、项目编码、依赖版本等全局属性，实现"一处修改，处处生效"。

第五，环境配置继承。父 POM 中定义的仓库配置、资源过滤规则等会被所有子模块继承，减少重复配置。

一个典型的父 POM 结构（教学简化版）如下所示：

xml

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>smart-scaffold-parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <modules>
        <module>smart-scaffold-common</module>
        <module>smart-scaffold-dao</module>
        <module>smart-scaffold-service</module>
        <module>smart-scaffold-web</module>
    </modules>

    <properties>
        <java.version>17</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <!-- 依赖版本统一管理 -->
        <lombok.version>1.18.30</lombok.version>
        <commons-lang3.version>3.14.0</commons-lang3.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!-- 在此声明依赖及版本 -->
        </dependencies>
    </dependencyManagement>

    <build>
        <pluginManagement>
            <plugins>
                <!-- 在此声明插件及配置 -->
            </plugins>
        </pluginManagement>
    </build>
</project>

注意父 POM 的 <packaging> 值为 pom，这是聚合 POM 的标准配置。它告诉 Maven 这个项目本身不产生构建产物，仅用于管理子模块。

2.2 spring-boot-starter-parent 继承体系

smart-scaffold 项目选择 spring-boot-starter-parent 作为父 POM 的父级（即项目的"祖父"POM），这是一个非常普遍但值得深入理解的设计决策。

spring-boot-starter-parent 本质上是一个特殊的 POM，它提供了以下开箱即用的配置：

Java 版本默认配置：默认使用 Java 17（在 3.x 版本中），子模块无需重复指定编译版本。
编码格式统一：默认使用 UTF-8 编码，避免不同操作系统下的编码问题。
资源过滤默认开启：对 application.properties 和 application.yml 文件自动启用过滤。
插件版本锁定：预配置了 maven-compiler-plugin、maven-surefire-plugin、maven-jar-plugin 等常用插件的版本。
依赖版本管理：通过内部的 BOM 管理了 Spring Boot 生态中数百个依赖的版本。

继承关系如下：

smart-scaffold-parent
  └── spring-boot-starter-parent:3.5.12
        └── spring-boot-dependencies:3.5.12 (BOM)

当我们的父 POM 继承了 spring-boot-starter-parent 后，所有子模块自动获得上述配置。这意味着在子模块中声明 Spring Boot 相关依赖时，通常不需要指定版本号。

但这里有一个重要的架构决策需要理解：当项目需要同时使用 Spring Boot 和 Spring Cloud 时，如何管理 Spring Cloud 的版本？ 答案是通过 <dependencyManagement> 引入 Spring Cloud BOM，我们将在下一节详细讨论。

对于 Dubbo 版项目，由于不需要 Spring Cloud，父 POM 的继承关系更为简洁。Dubbo 的版本管理通过直接在 <properties> 中定义版本号来实现，无需额外的 BOM 引入。

2.3 dependencyManagement 与 dependencies 的本质区别

这是 Maven 依赖管理中最容易被混淆的概念，也是面试中的高频考点。

<dependencies> 声明的依赖会被所有子模块自动继承。也就是说，在父 POM 的 <dependencies> 中声明的依赖，子模块即使不显式声明，也会自动引入。这种"强制引入"的特性适合用于真正全局必需的依赖。

<dependencyManagement> 声明的依赖不会被子模块自动引入。它仅仅是"声明"了依赖的版本信息，子模块需要显式声明该依赖（但不需指定版本号）才能使用。这种"按需引入"的特性是依赖管理的推荐方式。

用一个比喻来理解：<dependencies> 是"强制配餐"——不管你吃不吃，菜都端上来了；<dependencyManagement> 是"菜单标价"——告诉你每道菜多少钱，但你自己决定点什么。

在 smart-scaffold 项目中，父 POM 使用 <dependencyManagement> 来管理所有依赖版本。这是一种最佳实践，原因如下：

第一，避免依赖污染。如果 common 模块引入了 MySQL 驱动，而 Dubbo 版的 api 模块根本不需要数据库访问，那么通过 <dependencies> 强制引入就会导致 api 模块携带不必要的依赖。

第二，版本一致性。所有子模块引用同一个依赖时，使用的是 <dependencyManagement> 中声明的版本，消除了版本不一致的风险。

第三，依赖透明。每个子模块的 POM 中明确声明了自己需要的依赖，使得模块的依赖关系一目了然。

来看一个教学示例，对比两种方式的差异：

xml

<!-- 方式一：dependencies（不推荐用于父POM） -->
<dependencies>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.30</version>
    </dependency>
</dependencies>
<!-- 结果：所有子模块自动引入 lombok，无论是否需要 -->

<!-- 方式二：dependencyManagement（推荐） -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.30</version>
        </dependency>
    </dependencies>
</dependencyManagement>
<!-- 结果：子模块需要显式声明 lombok，但无需指定版本 -->

在实际项目中，<dependencies> 和 <dependencyManagement> 并非完全对立。对于真正全局必需且无副作用的依赖（如 Lombok，它只在编译期生效，不会被打入最终产物），放在 <dependencies> 中也是可以接受的。但作为架构规范，统一使用 <dependencyManagement> 是更严谨的做法。

2.4 Spring Cloud BOM 的引入方式

在 SpringCloud 版项目中，需要同时管理 Spring Boot 和 Spring Cloud 两套依赖的版本。由于 Spring Cloud 的版本与 Spring Boot 版本有严格的兼容性要求，正确引入 Spring Cloud BOM 至关重要。

Spring Cloud 通过 spring-cloud-dependencies BOM 来管理其生态组件的版本。引入方式是在父 POM 的 <dependencyManagement> 中添加：

xml

<dependencyManagement>
    <dependencies>
        <!-- Spring Cloud BOM -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2025.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

这里有几个关键细节需要注意：

<type>pom</type> 声明这是一个 POM 类型的依赖，不是 JAR。Spring Cloud BOM 本身是一个 POM 文件，它通过 <dependencyManagement> 管理了大量 Spring Cloud 组件的版本。

<scope>import</scope> 是关键。它的作用是将 spring-cloud-dependencies POM 中定义的 <dependencyManagement> 合并到当前项目的 <dependencyManagement> 中。这是 Maven BOM 机制的核心——通过 import scope 实现依赖管理信息的"继承"而非"引入"。

版本兼容性是必须严格把控的。Spring Cloud 的版本命名规则在 2025.0.0 版本中已经简化，不再使用字母后缀（如 Hoxton.SR12）。每个 Spring Cloud 版本都对应特定的 Spring Boot 版本范围，使用不兼容的组合会导致运行时错误。

需要注意的是，由于父 POM 已经继承了 spring-boot-starter-parent，Spring Boot 的依赖版本管理已经通过继承链生效。Spring Cloud BOM 的引入不会与 Spring Boot 的版本管理冲突，因为 Spring Cloud BOM 主要管理的是 Spring Cloud 自有组件（如 spring-cloud-starter-openfeign、spring-cloud-starter-netflix-eureka-client 等）的版本。

2.5 全局依赖版本统一管理

在父 POM 中，通过 <properties> 定义版本号是实现版本统一管理的标准做法。这种方式的核心价值在于：当需要升级某个依赖时，只需修改一处即可。

smart-scaffold 项目中管理的典型依赖版本包括：

xml

<properties>
    <!-- Java 版本 -->
    <java.version>17</java.version>

    <!-- 编码 -->
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

    <!-- 第三方库版本 -->
    <lombok.version>1.18.30</lombok.version>
    <commons-lang3.version>3.14.0</commons-lang3.version>
    <hutool.version>5.8.25</hutool.version>
    <mapstruct.version>1.5.5.Final</mapstruct.version>

    <!-- 数据库相关 -->
    <mybatis-plus.version>3.5.5</mybatis-plus.version>
    <mysql.version>8.0.33</mysql.version>

    <!-- 中间件 -->
    <dubbo.version>3.2.12</dubbo.version>
    <zookeeper.version>3.9.1</zookeeper.version>
</properties>

然后在 <dependencyManagement> 中通过 ${property.name} 引用：

xml

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>${commons-lang3.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

这种"先定义、后引用"的模式有几个优势：

第一，版本号语义化。属性名 lombok.version 比直接写 1.18.30 更具可读性，尤其在 <dependencyManagement> 中有大量依赖时。

第二，升级便利。升级 Lombok 版本时，只需修改 <properties> 中的值，所有引用该属性的依赖声明自动更新。

第三，条件化版本管理。可以通过 Maven Profile 为不同环境定义不同的版本号，实现灵活的版本策略。

对于 Spring Boot 和 Spring Cloud 管理的依赖，则不需要在 <properties> 中重复定义版本号，因为它们的版本由 spring-boot-starter-parent 和 spring-cloud-dependencies BOM 统一管理。子模块直接声明依赖即可，无需指定版本。

2.6 pluginManagement 与 plugins 的协同

与 <dependencyManagement> 和 <dependencies> 的关系类似，<pluginManagement> 和 <plugins> 也遵循"声明 vs 激活"的模式。

<pluginManagement> 在父 POM 中声明插件的版本和配置，子模块不会自动继承这些插件。子模块需要显式声明使用哪些插件，但可以省略版本号和通用配置。

<plugins> 在父 POM中直接声明插件，所有子模块自动继承并执行这些插件。

在 smart-scaffold 项目中，父 POM 通过 <pluginManagement> 管理了以下核心插件：

xml

<build>
    <pluginManagement>
        <plugins>
            <!-- 编译插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>

            <!-- Spring Boot 打包插件 -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- 资源插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.3.1</version>
                <configuration>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

子模块在需要使用这些插件时，只需在 <build><plugins> 中声明插件坐标，无需重复版本号和通用配置：

xml

<!-- 子模块中激活编译插件 -->
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <!-- 版本和配置继承自父POM的pluginManagement -->
        </plugin>
    </plugins>
</build>

这种模式的优势在于：父 POM 控制"用什么版本、怎么配置"，子模块控制"用不用"。当需要升级编译插件版本时，只需修改父 POM 的一处配置。

需要注意的是，spring-boot-maven-plugin 通常只在 web 模块（或启动模块）中激活，其他模块（如 common、dao、service）不需要这个插件。这体现了"按需激活"的设计理念。

三、子模块 POM 设计

3.1 模块间依赖关系设计

子模块的 POM 设计核心是依赖关系图的设计。在 smart-scaffold 项目中，三种架构的依赖关系图各有特点。

SpringBoot 版的依赖链最为经典：

web  →  service  →  dao  →  common

web 模块的 POM 需要同时依赖 service 和 dao（因为 Spring Boot 的组件扫描可能需要直接引用 dao 层的接口），service 模块依赖 dao，dao 模块依赖 common。这种链式依赖确保了每一层只能访问其下层提供的功能。

一个简化的 web 模块 POM 示例：

xml

<project>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>smart-scaffold-parent</artifactId>
        <version>1.0.0</version>
    </parent>
    <artifactId>smart-scaffold-web</artifactId>

    <dependencies>
        <!-- 依赖 service 层 -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>smart-scaffold-service</artifactId>
            <version>${project.version}</version>
        </dependency>
        <!-- Web 相关依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
</project>

注意 ${project.version} 的使用——子模块之间的版本号通常保持一致，使用属性引用可以避免版本不同步的问题。

Dubbo 版的依赖关系呈现星型结构：

provider  →  api
consumer  →  api

provider 和 consumer 都依赖 api 模块，但彼此之间没有依赖关系。这种结构支持 provider 和 consumer 的独立部署。

SpringCloud 版的依赖关系同样是星型，但 common 模块承担了更多职责：

provider  →  common
consumer  →  common

common 模块中定义了 Feign 客户端接口、公共 DTO、工具类等，provider 和 consumer 都依赖它来实现服务间的契约。

3.2 依赖作用域管理

Maven 的 <scope> 标签用于控制依赖的可见性和传递性。理解作用域对于避免"依赖污染"和"类找不到"问题至关重要。

Maven 定义了六种作用域，其中最常用的是以下四种：

**compile（编译作用域）**是默认值。依赖在编译、测试和运行时都可用，且会传递给依赖此模块的其他模块。大多数第三方库依赖（如 Spring Framework、Apache Commons）都使用此作用域。

**provided（已提供作用域）**表示依赖在编译时需要，但在运行时由 JDK 或容器提供。最典型的例子是 servlet-api——编译时需要 Servlet 接口定义，但运行时由 Tomcat 提供。如果使用 compile 作用域引入 servlet-api，会导致与 Tomcat 内置的 servlet-api 冲突。

xml

<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <scope>provided</scope>
</dependency>

**runtime（运行时作用域）**表示依赖在编译时不需要，但在测试和运行时需要。最典型的例子是 JDBC 驱动——代码中通常通过反射或 SPI 机制加载驱动类，编译时不需要直接引用。

xml

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

**test（测试作用域）**表示依赖仅在测试编译和测试运行时可用，不会被打入最终产物。单元测试框架（如 JUnit、Mockito）都应使用此作用域。

xml

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

在 smart-scaffold 项目中，Lombok 是一个特殊的存在。它只在编译期生效（通过注解处理器生成代码），运行时不需要。因此，理论上应该使用 provided 作用域。但在实际项目中，由于 spring-boot-starter-parent 已经为 Lombok 定义了 provided 作用域，子模块通常不需要额外指定。

作用域的传递性规则如下表所示：

依赖的作用域	compile	provided	runtime	test
compile	传递	不传递	传递	不传递
provided	不传递	不传递	不传递	不传递
runtime	传递	不传递	传递	不传递
test	不传递	不传递	不传递	不传递

理解这个传递性表格对于排查"为什么某个类在运行时找不到"的问题非常重要。

3.3 optional 依赖的巧妙运用

<optional>true</optional> 是 Maven 中一个容易被忽视但非常实用的配置。它的作用是：当前模块依赖某个库，但不希望这个依赖传递给引用当前模块的其他模块。

在 smart-scaffold 的 common 模块中，可能存在这样的场景：common 模块提供了多种工具方法，其中某些方法依赖于特定库（如 Redis 客户端），但并非所有引用 common 的模块都需要 Redis 功能。

xml

<!-- common 模块的 POM -->
<dependencies>
    <!-- 所有模块都可能需要的工具库 -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
    </dependency>

    <!-- 只有需要 Redis 的模块才需要的库 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

通过将 spring-boot-starter-data-redis 标记为 optional，dao 模块依赖 common 时不会自动引入 Redis 依赖。如果 dao 模块确实需要 Redis 功能，它需要在自己的 POM 中显式声明。

optional 依赖与 provided 作用域的区别在于：provided 作用域的依赖在编译时可用但运行时由容器提供，而 optional 依赖完全不传递——下游模块既不会在编译时看到它，也不会在运行时得到它。

在实际项目中，optional 依赖常用于以下场景：

公共模块中的可选功能：如 common 模块中的 Redis 工具类、邮件工具类等。
多实现场景：如日志模块同时支持 Logback 和 Log4j2，通过 optional 引入，由最终应用决定使用哪个。
SPI 接口的多实现：如数据库驱动，common 模块定义接口，具体驱动由使用方选择。

3.4 spring-boot-maven-plugin 的精准配置

spring-boot-maven-plugin 是 Spring Boot 项目中最关键的构建插件，它负责将普通的 JAR 包重新打包为可执行的 Fat JAR（也称为 Uber JAR）。

在 smart-scaffold 项目中，这个插件只在 web 模块中激活，其他模块（common、dao、service）不需要它。这是因为只有 web 模块包含 Spring Boot 的启动类，是需要独立运行的模块。

xml

<!-- 仅在 web 模块中配置 -->
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
    </plugins>
</build>

这里有几个值得注意的配置细节：

excludes 配置用于排除不需要打入 Fat JAR 的依赖。Lombok 只在编译期生效，运行时不需要，排除它可以减小最终 JAR 包的体积。虽然 Lombok 本身很小（约 2MB），但在生产环境中，每一个字节的减少都有意义。

repackage 目标是此插件的核心功能，它绑定在 Maven 的 package 生命周期阶段。执行 mvn package 时，Maven 先通过 maven-jar-plugin 生成普通的 JAR 包，然后 spring-boot-maven-plugin 的 repackage 目标将这个普通 JAR 包重新打包为可执行的 Fat JAR。

对于 Dubbo 版和 SpringCloud 版项目，spring-boot-maven-plugin 只在 provider 模块中配置（provider 包含启动类），consumer 模块如果是纯 API 网关或前端服务，也可能需要配置。

四、资源过滤配置

4.1 Maven 资源过滤机制原理

Maven 的资源过滤（Resource Filtering）是一种在构建过程中动态替换资源文件中占位符的机制。它的原理很简单：在将资源文件从 src/main/resources 复制到 target/classes 的过程中，Maven 会扫描文件内容，将 ${variable.name} 形式的占位符替换为对应的属性值。

属性值的来源包括：

POM 中的 <properties> 定义的属性
系统属性（通过 -D 参数传入）
环境变量
POM 自身的属性（如 ${project.version}、${project.artifactId}）

资源过滤的开关是 <filtering> 标签。当 <filtering>true</filtering> 时，Maven 会启用过滤；当 <filtering>false</filtering> 或未设置时，Maven 只做简单的文件复制。

一个常见的使用场景是在 application.yml 中引用 POM 定义的版本号：

yaml

# application.yml
application:
  name: @project.artifactId@
  version: @project.version@

注意这里使用的是 @...@ 而不是 ${...}。这是因为 Spring Boot 的配置文件本身使用 ${...} 作为属性引用语法，如果 Maven 也使用 ${...}，会产生语法冲突。Spring Boot 提供了一种解决方案：使用 @...@ 作为 Maven 资源过滤的占位符格式，需要在 POM 中显式配置。

4.2 filtering 与非 filtering 资源的分离策略

在实际项目中，并非所有资源文件都需要过滤。配置文件（如 application.yml）需要过滤以替换占位符，但二进制文件（如图片、Excel 模板）如果被过滤，会导致文件损坏。

smart-scaffold 项目采用了"分离策略"——将需要过滤和不需要过滤的资源分别配置：

xml

<build>
    <resources>
        <!-- 需要过滤的资源：配置文件 -->
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
            <includes>
                <include>**/*.yml</include>
                <include>**/*.yaml</include>
                <include>**/*.properties</include>
            </includes>
        </resource>

        <!-- 不需要过滤的资源：静态文件、二进制文件 -->
        <resource>
            <directory>src/main/resources</directory>
            <filtering>false</filtering>
            <excludes>
                <exclude>**/*.yml</exclude>
                <exclude>**/*.yaml</exclude>
                <exclude>**/*.properties</exclude>
            </excludes>
        </resource>
    </resources>
</build>

这种配置的逻辑是：

第一个 <resource> 块只处理 .yml、.yaml、.properties 文件，并启用过滤。第二个 <resource> 块处理其余所有文件，但不启用过滤。

为什么要分成两个 <resource> 块而不是一个？因为一个 <resource> 块只能设置一个 <filtering> 值。如果所有资源放在同一个目录下（src/main/resources），就必须通过多个 <resource> 块来实现不同文件的不同处理方式。

4.3 配置文件的变量替换实践

在 smart-scaffold 项目中，资源过滤最典型的应用场景是配置文件中的变量替换。通过 Maven Profile 和资源过滤的结合，可以实现不同环境使用不同配置的目标。

在 application.yml 中使用 Maven 属性：

yaml

server:
  port: ${server.port:8080}

spring:
  datasource:
    url: jdbc:mysql://${db.host:localhost}:${db.port:3306}/${db.name:smart_scaffold}
    username: ${db.username:root}
    password: ${db.password:root}

这里使用了 ${variable:defaultValue} 的语法，冒号后面是默认值。当 Maven 没有提供对应的属性时，使用默认值。

通过 Maven 命令行传入属性值：

bash

mvn clean package -Ddb.host=192.168.1.100 -Ddb.port=3306

这种方式在 CI/CD 流水线中特别有用——构建时通过参数注入不同环境的配置，无需维护多套配置文件。

但更推荐的做法是结合 Maven Profile（将在第七章详细讨论），通过 Profile 定义不同环境的属性集，构建时通过 -P 参数激活对应的 Profile。

4.4 二进制文件的排除规则

二进制文件（如 .xlsx、.docx、.pdf、.png、.zip 等）绝对不能被 Maven 资源过滤处理。如果 Maven 尝试替换二进制文件中的 ${...} 或 @...@ 序列，会导致文件结构损坏，打开时报错。

在 smart-scaffold 项目中，通过 <filtering>false</filtering> 配置确保二进制文件不被过滤。但如果某些二进制文件恰好存放在需要过滤的目录中，就需要额外的排除规则。

一种更精细的配置方式是使用 <nonFilteredFileExtensions>：

xml

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <configuration>
        <nonFilteredFileExtensions>
            <nonFilteredFileExtension>xlsx</nonFilteredFileExtension>
            <nonFilteredFileExtension>docx</nonFilteredFileExtension>
            <nonFilteredFileExtension>pdf</nonFilteredFileExtension>
            <nonFilteredFileExtension>pptx</nonFilteredFileExtension>
            <nonFilteredFileExtension>zip</nonFilteredFileExtension>
            <nonFilteredFileExtension>png</nonFilteredFileExtension>
            <nonFilteredFileExtension>jpg</nonFilteredFileExtension>
            <nonFilteredFileExtension>woff2</nonFilteredFileExtension>
        </nonFilteredFileExtensions>
    </configuration>
</plugin>

这个配置告诉 maven-resources-plugin：即使 <filtering>true</filtering>，也不要对上述扩展名的文件执行过滤。这是一种"白名单"式的保护机制，比分离策略更加简洁。

4.5 MyBatis XML Mapper 的资源构建

MyBatis 框架需要加载 XML Mapper 文件来定义 SQL 映射。在 Maven 项目中，Mapper XML 文件通常有两种存放方式：

方式一：与 Java 源文件同目录存放（推荐）

将 Mapper XML 文件放在 src/main/java 目录下，与对应的 Mapper 接口同包存放。这种方式的好处是接口和映射文件在物理位置上紧邻，便于维护。

但 Maven 默认不会将 src/main/java 下的非 .java 文件复制到 target/classes。因此需要在 POM 中额外配置：

xml

<build>
    <resources>
        <!-- 标准资源目录 -->
        <resource>
            <directory>src/main/resources</directory>
        </resource>
        <!-- Java 目录下的 XML 文件也需要作为资源 -->
        <resource>
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.xml</include>
            </includes>
            <filtering>false</filtering>
        </resource>
    </resources>
</build>

注意这里的 <filtering>false</filtering>——MyBatis 的 XML 文件中可能包含 ${} 形式的参数占位符（如 ${tableName}），如果启用 Maven 过滤，Maven 会尝试替换这些占位符，导致 SQL 语句被破坏。

方式二：放在 resources 目录下

将 Mapper XML 文件放在 src/main/resources/mapper/ 目录下，这是 Maven 的默认资源目录，无需额外配置。但需要在 application.yml 中指定 Mapper 文件的路径：

yaml

mybatis-plus:
  mapper-locations: classpath:mapper/**/*.xml

smart-scaffold 项目采用的是方式一（同目录存放），这种方式在 MyBatis-Plus 社区中被广泛推荐。它不仅使代码结构更清晰，还避免了 Mapper 接口与 XML 文件不一致的问题——因为它们就在同一个目录下，开发者很容易注意到两者的对应关系。

五、Spring Boot 可执行 JAR 打包

5.1 spring-boot-maven-plugin 工作原理

spring-boot-maven-plugin 是 Spring Boot 生态中最核心的构建插件，它的 repackage 目标将普通的 Maven JAR 包转换为 Spring Boot 可执行 JAR。理解其工作原理有助于排查打包和运行时的问题。

普通 JAR 的结构：

myapp.jar
├── META-INF/
│   └── MANIFEST.MF
└── com/
    └── example/
        └── myapp/
            └── MyClass.class

普通 JAR 只包含项目自身的编译产物，不包含依赖库。运行时需要通过 -classpath 参数指定依赖 JAR 的路径。

Spring Boot Fat JAR 的结构：

myapp.jar
├── META-INF/
│   └── MANIFEST.MF          # 包含 Main-Class 和 Start-Class
├── BOOT-INF/
│   ├── classes/              # 项目自身的编译产物
│   │   └── com/example/myapp/
│   └── lib/                  # 所有依赖 JAR
│       ├── spring-core-6.x.jar
│       ├── mybatis-plus-3.x.jar
│       └── ...
└── org/
    └── springframework/
        └── boot/
            └── loader/       # Spring Boot 类加载器
                ├── JarLauncher.class
                ├── LaunchedURLClassLoader.class
                └── ...

Fat JAR 的核心设计思想是"自包含"——一个 JAR 文件包含了运行所需的全部内容。BOOT-INF/lib/ 目录存放所有依赖 JAR，BOOT-INF/classes/ 存放项目自身的类文件，org/springframework/boot/loader/ 存放 Spring Boot 的启动类加载器。

MANIFEST.MF 中的关键属性：

Main-Class: org.springframework.boot.loader.JarLauncher
Start-Class: com.example.myapp.Application

Main-Class 指向 Spring Boot 的 JarLauncher，它是 JAR 的真正入口点。JarLauncher 创建一个自定义的类加载器（LaunchedURLClassLoader），从 BOOT-INF/lib/ 和 BOOT-INF/classes/ 加载类，然后调用 Start-Class 指定的应用程序主类。

这种设计的巧妙之处在于：它使用自定义类加载器实现了"JAR 中的 JAR"加载，使得 java -jar myapp.jar 一条命令就能启动整个应用，无需额外的 classpath 配置。

5.2 repackage 目标深度解析

repackage 目标是 spring-boot-maven-plugin 最核心的功能，它绑定在 Maven 的 package 生命周期阶段。执行流程如下：

Maven 执行 package 阶段，maven-jar-plugin 生成普通 JAR（假设命名为 myapp.jar）。
spring-boot-maven-plugin 的 repackage 目标介入，将 myapp.jar 重命名为 myapp.jar.original。
创建新的 myapp.jar（Fat JAR），将原始 JAR 的内容放入 BOOT-INF/classes/，将所有依赖 JAR 放入 BOOT-INF/lib/，并添加 Spring Boot Loader 类。

repackage 目标支持以下关键配置参数：

<mainClass>：显式指定启动类的全限定名。如果不指定，插件会自动搜索带有 @SpringBootApplication 注解的类。
<classifier>：为 Fat JAR 添加分类标识。默认情况下，Fat JAR 覆盖原始 JAR（原始 JAR 被重命名为 .original）。如果设置了 classifier（如 exec），则原始 JAR 保持不变，Fat JAR 使用 myapp-exec.jar 作为文件名。
<attach>：控制是否将 Fat JAR 安装到本地仓库。默认为 true。

xml

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <mainClass>com.example.smartscaffold.Application</mainClass>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>repackage</goal>
            </goals>
        </execution>
    </executions>
</plugin>

5.3 excludes 配置与依赖裁剪

在打包 Fat JAR 时，并非所有依赖都需要包含在最终的 JAR 中。通过 excludes 配置，可以将特定的依赖从 Fat JAR 中排除。

smart-scaffold 项目中排除了 Lombok：

xml

<configuration>
    <excludes>
        <exclude>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </exclude>
    </excludes>
</configuration>

排除 Lombok 的原因是它只在编译期通过注解处理器工作，运行时不需要。虽然 Lombok 本身体积不大，但排除它体现了"只打包必要依赖"的工程原则。

除了 Lombok，以下类型的依赖也适合排除：

编译期注解处理器：如 mapstruct-processor、spring-boot-configuration-processor 等。
文档生成工具：如 swagger-annotations（如果运行时不需要 API 文档功能）。
测试框架：理论上测试依赖的 scope 为 test，不会被打入 Fat JAR。但如果某些测试依赖被错误地声明为 compile，就需要通过 excludes 排除。

需要注意的是，excludes 排除的是依赖 JAR，而不是项目自身的类。如果项目代码中直接 import 了被排除依赖的类，运行时会抛出 ClassNotFoundException。因此，在排除依赖之前，务必确认该依赖在运行时确实不需要。

5.4 finalName 自定义与版本管理

<finalName> 用于自定义构建产物的文件名。在 smart-scaffold 项目中，web 模块的构建产物名称被自定义：

xml

<build>
    <finalName>${project.artifactId}</finalName>
</build>

这样配置后，构建产物为 smart-scaffold-web.jar，而不是默认的 smart-scaffold-web-1.0.0.jar。去掉版本号的好处是 Dockerfile 中的 COPY 和 CMD 指令不需要随版本更新而修改。

如果需要在文件名中保留版本信息，可以使用：

xml

<finalName>${project.artifactId}-${project.version}</finalName>

在 CI/CD 流水线中，更常见的做法是使用时间戳或构建号作为版本标识：

xml

<finalName>${project.artifactId}-${maven.build.timestamp}</finalName>

或者在 Docker 构建时通过参数传入：

bash

mvn clean package -DfinalName=smart-scaffold-web-${BUILD_NUMBER}

5.5 瘦 JAR 与 Fat JAR 的取舍

Fat JAR（可执行 JAR）将所有依赖打包在一起，部署简单，但体积较大（通常 50MB-200MB）。在某些场景下，瘦 JAR（只包含项目自身代码）可能是更好的选择。

Fat JAR 的优势：

部署简单：一个文件包含一切，java -jar 即可启动。
环境一致：不依赖服务器上已安装的库版本。
容器友好：特别适合 Docker 容器化部署。

Fat JAR 的劣势：

体积大：每次部署都需要传输完整的 JAR 包。
升级不便：升级一个依赖需要重新打包整个应用。
内存占用：类加载器需要加载所有依赖，即使某些依赖在特定场景下不使用。

瘦 JAR 的适用场景：

多个应用共享同一套依赖库（如放在 Tomcat 的 lib 目录下）。
需要频繁更新应用代码但依赖不变的场景。
对启动速度有极高要求的场景（瘦 JAR 的类加载更快）。

在 smart-scaffold 项目中，选择了 Fat JAR 方案，这与项目的 Docker 容器化部署策略一致。在容器环境中，Fat JAR 的"自包含"特性与容器的"隔离性"理念完美契合。

如果同时需要两种 JAR，可以通过 classifier 配置实现：

xml

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>repackage</id>
            <goals>
                <goal>repackage</goal>
            </goals>
            <configuration>
                <classifier>exec</classifier>
            </configuration>
        </execution>
    </executions>
</plugin>

这样，mvn package 会生成两个文件：

smart-scaffold-web-1.0.0.jar（瘦 JAR，原始产物）
smart-scaffold-web-1.0.0-exec.jar（Fat JAR，可执行产物）

六、Maven 构建性能优化

6.1 并行构建 -T 参数详解

Maven 3.x 引入了并行构建能力，通过 -T 参数可以显著缩短多模块项目的构建时间。

smart-scaffold 项目在 Dockerfile 中使用了 -T 1C 参数：

dockerfile

RUN mvn clean package -T 1C -DskipTests

-T 1C 表示每个 CPU 核心分配 1 个线程。在 4 核机器上，相当于 -T 4（4 个线程并行构建）。1C 的写法比固定数字更灵活，能够自动适应不同配置的构建环境。

Maven 支持以下几种并行构建配置：

-T 1：使用 1 个线程（等同于串行构建，无加速效果）。
-T 4：使用 4 个线程并行构建。
-T 1C：每个 CPU 核心分配 1 个线程（推荐）。
-T 2C：每个 CPU 核心分配 2 个线程（I/O 密集型构建时有效）。

并行构建的加速效果取决于模块间的依赖关系。对于无依赖关系的模块（如 Dubbo 版的 provider 和 consumer），可以完全并行构建，加速效果接近线性。对于有依赖关系的模块（如 SpringBoot 版的 web 依赖 service 依赖 dao），Maven 会按照依赖拓扑排序，尽可能并行构建无依赖关系的模块。

需要注意的是，并行构建并非没有代价。每个构建线程都会占用内存（默认每个线程约 512MB-1GB），在内存有限的环境中，过多的并行线程可能导致 OOM。建议在 CI 环境中根据机器配置合理设置线程数。

6.2 跳过测试与分层测试策略

-DskipTests 是 CI/CD 流水线中最常用的 Maven 参数之一，它跳过测试执行阶段（但仍然编译测试代码）。

bash

mvn clean package -DskipTests

与 -DskipTests 相关的还有 -Dmaven.test.skip=true，它更彻底——不仅跳过测试执行，还跳过测试代码的编译。两者的区别：

参数	编译测试代码	执行测试
无参数	是	是
`-DskipTests`	是	否
`-Dmaven.test.skip=true`	否	否

在 CI/CD 流水线中，推荐使用 -DskipTests 而不是 -Dmaven.test.skip=true。原因在于：即使不执行测试，编译测试代码也能验证测试代码与生产代码的兼容性。如果生产代码的 API 变更导致测试代码编译失败，-DskipTests 能够及时发现，而 -Dmaven.test.skip=true 则会掩盖这个问题。

但这并不意味着测试不重要。更推荐的做法是分层测试策略：

本地开发：运行单元测试（mvn test），确保代码逻辑正确。
CI 构建：跳过测试执行（-DskipTests），快速产出构建产物。
CI 部署前：单独运行集成测试或端到端测试，验证系统整体功能。

这种策略在构建速度和代码质量之间取得了平衡。

6.3 本地仓库缓存机制

Maven 的本地仓库（默认位于 ~/.m2/repository/）是构建性能优化的重要环节。每次构建时，Maven 首先检查本地仓库中是否已有所需的依赖，如果有则直接使用，无需从远程仓库下载。

本地仓库的缓存机制遵循以下规则：

依赖下载：从远程仓库下载的依赖会被永久缓存在本地仓库中，除非手动删除或执行 mvn dependency:purge-local-repository。
SNAPSHOT 版本：对于 SNAPSHOT 版本的依赖，Maven 会定期检查远程仓库是否有更新（默认每天一次）。可以通过 -U 参数强制更新。
插件缓存：Maven 插件同样被缓存在本地仓库中。

在 Docker 构建中，本地仓库缓存是一个需要特别关注的问题。每次 Docker 构建都会创建一个新的容器环境，~/.m2/repository/ 是空的，所有依赖都需要重新下载。这会导致构建时间显著增加。

解决方案是将宿主机的 .m2 目录挂载到容器中，或者使用 Docker 的多阶段构建配合缓存卷（将在第八章详细讨论）。

6.4 镜像加速配置

在中国大陆地区，直接访问 Maven 中央仓库（repo.maven.apache.org）速度较慢甚至超时。配置国内镜像源是提升依赖下载速度的有效手段。

在 Maven 的 settings.xml 中配置阿里云镜像：

xml

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>central</mirrorOf>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

<mirrorOf>central</mirrorOf> 表示该镜像替代 Maven 中央仓库。所有对中央仓库的请求都会被重定向到阿里云镜像。

如果项目使用了 Spring Cloud 等需要从 Spring 仓库下载依赖的场景，可以扩展 mirrorOf 的范围：

xml

<mirrorOf>central,spring-milestones,spring-snapshots</mirrorOf>

在 Docker 构建环境中，镜像配置尤为重要。由于构建环境通常是全新的，需要在 Dockerfile 中确保使用正确的 Maven 配置。一种常见的做法是将自定义的 settings.xml 复制到容器中：

dockerfile

COPY settings.xml /root/.m2/settings.xml

6.5 依赖分析与冲突排查

mvn dependency:tree 是排查依赖问题的利器。它以树形结构展示项目的完整依赖关系，包括传递依赖。

bash

mvn dependency:tree -Dverbose

-Dverbose 参数会显示所有依赖（包括冲突和重复的依赖），并标注哪些依赖被省略（因为版本冲突）。

常见的依赖问题及排查方法：

版本冲突：当同一个依赖的多个版本同时出现在依赖树中时，Maven 采用"最近优先"原则——依赖树中路径最短的版本胜出。如果路径长度相同，先声明的版本胜出。

bash

# 查找特定依赖的来源
mvn dependency:tree -Dincludes=org.springframework:spring-core

依赖泄漏：某个不需要的依赖通过传递依赖被引入。解决方法是在引入方使用 <exclusion> 排除不需要的传递依赖：

xml

<dependency>
    <groupId>com.example</groupId>
    <artifactId>example-lib</artifactId>
    <exclusions>
        <exclusion>
            <groupId>unwanted.group</groupId>
            <artifactId>unwanted-artifact</artifactId>
        </exclusion>
    </exclusions>
</dependency>

依赖缺失：编译通过但运行时报 ClassNotFoundException 或 NoSuchMethodError。这通常是因为某个依赖被标记为 provided 或 optional，在运行时不可用。使用 mvn dependency:tree 检查该依赖是否在运行时 classpath 中。

七、多环境 Profile 配置

7.1 Spring Profile 机制概述

Spring 的 Profile 机制提供了一种在不同环境间切换配置的方式。在 smart-scaffold 项目中，典型的环境包括：

dev（开发环境）：本地开发使用，连接本地数据库和中间件。
qa（测试环境）：QA 团队使用，连接测试环境的数据库和中间件。
prd（生产环境）：正式运行环境，连接生产数据库和高可用中间件。

Spring Profile 的核心思想是：定义一组配置，通过激活条件决定哪些配置生效。激活方式包括命令行参数、环境变量、配置文件等多种途径。

在 Spring Boot 中，Profile 的配置文件命名约定为 application-{profile}.yml。当激活某个 Profile 时，Spring Boot 会加载对应的配置文件，并与主配置文件（application.yml）合并。Profile 配置文件中的属性会覆盖主配置文件中的同名属性。

7.2 多环境配置文件设计

smart-scaffold 项目采用了标准的 Spring Boot 多环境配置文件结构：

src/main/resources/
├── application.yml           # 主配置（公共配置）
├── application-dev.yml       # 开发环境配置
├── application-qa.yml        # 测试环境配置
└── application-prd.yml       # 生产环境配置

主配置文件（application.yml）包含所有环境共享的配置：

yaml

spring:
  application:
    name: smart-scaffold
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: Asia/Shanghai

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

logging:
  level:
    com.example: debug

开发环境配置（application-dev.yml）：

yaml

server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/smart_scaffold_dev?useSSL=false
    username: root
    password: ${DB_PASSWORD:root}
  redis:
    host: localhost
    port: 6379

生产环境配置（application-prd.yml）：

yaml

server:
  port: 8443

spring:
  datasource:
    url: jdbc:mysql://db-master.prod.example.com:3306/smart_scaffold_prd?useSSL=true
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
  redis:
    host: redis-cluster.prod.example.com
    port: 6379
    password: ${REDIS_PASSWORD}

注意生产环境配置中的 ${DB_USERNAME} 和 ${DB_PASSWORD}——这些是环境变量引用，实际的密码不会出现在配置文件中。这是一种安全最佳实践，避免了敏感信息泄露到代码仓库。

7.3 Profile 激活的多种方式

Spring Boot 支持多种 Profile 激活方式，各有适用场景：

方式一：配置文件指定（推荐用于开发环境）

在 application.yml 中通过 spring.profiles.active 指定：

yaml

spring:
  profiles:
    active: dev

方式二：命令行参数（推荐用于生产环境）

bash

java -jar smart-scaffold-web.jar --spring.profiles.active=prd

方式三：环境变量（推荐用于容器化部署）

bash

export SPRING_PROFILES_ACTIVE=prd
java -jar smart-scaffold-web.jar

方式四：JVM 系统属性

bash

java -Dspring.profiles.active=prd -jar smart-scaffold-web.jar

在 Docker 环境中，通常通过环境变量激活 Profile：

dockerfile

ENV SPRING_PROFILES_ACTIVE=prd

或者在 docker run 时传入：

bash

docker run -e SPRING_PROFILES_ACTIVE=prd smart-scaffold-web

多种方式可以同时使用，优先级从高到低为：命令行参数 > 环境变量 > 配置文件。

7.4 各环境差异化配置实践

不同环境的差异化配置通常涉及以下几个方面：

数据库配置差异：

开发环境：单节点 MySQL，小连接池，允许 SQL 日志输出。
测试环境：主从 MySQL，中等连接池，SQL 日志级别为 INFO。
生产环境：主从 MySQL + 读写分离，大连接池，SQL 日志关闭或仅记录慢查询。

端口配置差异：

开发环境：8080（HTTP）。
测试环境：8080（HTTP）。
生产环境：8443（HTTPS）或通过反向代理统一入口。

中间件配置差异：

开发环境：单节点 Redis、单节点 ZooKeeper。
测试环境：哨兵模式 Redis、三节点 ZooKeeper。
生产环境：集群模式 Redis、集群模式 ZooKeeper。

日志配置差异：

开发环境：DEBUG 级别，控制台输出。
测试环境：INFO 级别，文件输出。
生产环境：WARN 级别，文件输出 + ELK 采集。

安全配置差异：

开发环境：关闭 HTTPS、关闭 CSRF。
生产环境：启用 HTTPS、启用 CSRF、配置 CORS 白名单。

这些差异通过 Profile 配置文件实现，使得同一套代码可以在不同环境中运行，无需修改任何代码。

7.5 Maven Profile 与 Spring Profile 的联动

Maven Profile 和 Spring Profile 是两个不同层面的配置机制，但它们可以协同工作，实现更灵活的环境管理。

Maven Profile 在构建时生效，可以控制哪些资源文件被打包、替换配置文件中的占位符等。Spring Profile 在运行时生效，控制 Spring Boot 加载哪些配置。

一种常见的联动方式是通过 Maven Profile 控制 spring.profiles.active 的值：

xml

<!-- 父 POM 中的 Maven Profile -->
<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <env>dev</env>
        </properties>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
    </profile>
    <profile>
        <id>qa</id>
        <properties>
            <env>qa</env>
        </properties>
    </profile>
    <profile>
        <id>prd</id>
        <properties>
            <env>prd</env>
        </properties>
    </profile>
</profiles>

然后在 application.yml 中引用 Maven 属性：

yaml

spring:
  profiles:
    active: @env@

构建时通过 -P 参数激活 Maven Profile：

bash

mvn clean package -P prd

这样，@env@ 会被替换为 prd，生成的 application.yml 中 spring.profiles.active 的值为 prd。

这种联动方式在 CI/CD 流水线中特别有用——不同环境的构建任务使用不同的 Maven Profile 参数，自动生成对应环境的配置。

八、Maven 与 Docker 集成

8.1 多阶段构建中的 Maven 配置

Docker 的多阶段构建（Multi-stage Build）与 Maven 的结合是现代 Java 应用容器化的标准实践。其核心思想是：第一阶段使用 Maven 镜像编译和打包，第二阶段使用 JRE 镜像运行，最终镜像只包含运行时所需的内容。

dockerfile

# 第一阶段：构建
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /app
COPY pom.xml .
COPY settings.xml /root/.m2/settings.xml
COPY module-common/pom.xml module-common/
COPY module-dao/pom.xml module-dao/
COPY module-service/pom.xml module-service/
COPY module-web/pom.xml module-web/
RUN mvn dependency:go-offline -B
COPY . .
RUN mvn clean package -T 1C -DskipTests

# 第二阶段：运行
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY --from=builder /app/module-web/target/smart-scaffold-web.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

这个 Dockerfile 的构建阶段有几个值得深入分析的细节：

dependency:go-offline 是一个优化技巧。它预先下载所有依赖（包括插件），但不执行编译。由于 Docker 的层缓存机制，只要 pom.xml 没有变化，这一层就会被缓存。后续的代码变更不会触发依赖重新下载，大幅缩短构建时间。

先复制 POM 文件，再复制源代码是另一个关键优化。POM 文件的变化频率远低于源代码，将它们分开复制可以利用 Docker 的层缓存。只有当 POM 文件变化时，才会触发依赖重新下载。

-T 1C 并行构建利用多核 CPU 加速编译过程。在 CI 环境中，构建机器通常配置了较多的 CPU 核心，并行构建可以显著缩短构建时间。

8.2 .m2 缓存优化策略

Maven 本地仓库缓存是 Docker 构建中的关键性能瓶颈。每次构建都从零开始下载依赖是不现实的，尤其是在网络条件不佳的环境中。

策略一：Docker BuildKit 缓存挂载

dockerfile

# syntax=docker/dockerfile:1
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /app
COPY pom.xml .
COPY settings.xml /root/.m2/settings.xml

RUN --mount=type=cache,target=/root/.m2/repository \
    mvn dependency:go-offline -B

COPY . .
RUN --mount=type=cache,target=/root/.m2/repository \
    mvn clean package -T 1C -DskipTests

--mount=type=cache,target=/root/.m2/repository 将宿主机的缓存目录挂载到容器的 Maven 本地仓库目录。多次构建之间共享缓存，避免重复下载。

策略二：Docker Volume 挂载

bash

docker build --mount=type=cache,target=/root/.m2/repository -t smart-scaffold .

或者在 docker run 时挂载：

bash

docker run -v ~/.m2:/root/.m2 maven:3.9-eclipse-temurin-17 mvn clean package

策略三：CI/CD 缓存

在 Jenkins、GitLab CI 等平台中，通常提供了构建缓存机制。例如，GitLab CI 的 cache 配置：

yaml

cache:
  paths:
    - .m2/repository/

8.3 构建参数传递与动态配置

在 CI/CD 流水线中，经常需要将外部参数传递到 Maven 构建过程中。Docker 提供了 ARG 和 ENV 两种机制。

ARG 用于构建时参数：

dockerfile

ARG APP_VERSION=1.0.0
ARG SPRING_PROFILE=dev

FROM maven:3.9-eclipse-temurin-17 AS builder
ARG SPRING_PROFILE
RUN mvn clean package -P ${SPRING_PROFILE} -DskipTests

构建时传入参数：

bash

docker build --build-arg SPRING_PROFILE=prd --build-arg APP_VERSION=2.0.0 -t smart-scaffold:2.0.0 .

ENV 用于运行时参数：

dockerfile

FROM eclipse-temurin:17-jre-alpine
ENV SPRING_PROFILES_ACTIVE=prd
ENV JAVA_OPTS="-Xms512m -Xmx1024m"
ENTRYPOINT ["sh", "-c", "java ${JAVA_OPTS} -jar app.jar"]

ENV 设置的环境变量在容器运行时可用，Spring Boot 会自动读取 SPRING_PROFILES_ACTIVE 环境变量来激活对应的 Profile。

Maven 属性与 Docker 参数的传递链路：

CI/CD 参数 → Docker ARG → Maven -D 参数 → POM 属性 → 资源过滤 → 配置文件

这条链路实现了从 CI/CD 流水线到应用配置的端到端参数传递。例如，在 GitLab CI 中：

yaml

build:
  script:
    - docker build
        --build-arg DB_HOST=${CI_DB_HOST}
        --build-arg DB_PASSWORD=${CI_DB_PASSWORD}
        -t smart-scaffold:${CI_COMMIT_TAG} .

8.4 Dockerfile 最佳实践

基于 smart-scaffold 项目的实践，总结 Dockerfile 中 Maven 相关的最佳实践：

使用特定版本标签：不要使用 latest 标签，因为 Maven 镜像和 JRE 镜像的更新可能导致构建行为不一致。使用确定的版本标签（如 maven:3.9-eclipse-temurin-17）。

利用层缓存：将变化频率低的操作（如依赖下载）放在前面，变化频率高的操作（如代码编译）放在后面。先复制 POM 文件，再复制源代码。

使用非 root 用户：出于安全考虑，运行阶段应使用非 root 用户：

dockerfile

FROM eclipse-temurin:17-jre-alpine
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

设置合理的 JVM 参数：容器环境中需要特别注意内存配置。使用 -XX:MaxRAMPercentage=75.0 让 JVM 根据容器内存限制自动调整堆大小，比固定 -Xmx 更灵活。

健康检查：添加 HEALTHCHECK 指令，让容器编排系统（如 Kubernetes）能够监控应用状态：

dockerfile

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost:8080/actuator/health || exit 1

多阶段构建：始终使用多阶段构建，最终镜像只包含 JRE 和应用 JAR，不包含 Maven 和源代码，大幅减小镜像体积。

九、常见问题与解决方案

9.1 循环依赖的诊断与消除

循环依赖是多模块项目中最严重的架构问题之一。当模块 A 依赖模块 B，模块 B 又直接或间接依赖模块 A 时，就会形成循环依赖。

Maven 在构建时会检测到循环依赖并报错：

The dependencies of project A form a cycle: A → B → C → A

循环依赖的常见原因：

第一，模块职责不清。当 common 模块中包含了业务逻辑，而业务模块又需要被 common 模块引用时，就会形成循环。

第二，DTO 放置位置不当。如果模块 A 定义了一个 DTO，模块 B 使用了这个 DTO，同时模块 A 又需要调用模块 B 的服务，就会产生循环。

第三，接口与实现分离不彻底。在 Dubbo 版项目中，如果 provider 模块直接依赖 consumer 模块（而不是通过 api 模块），就会形成循环。

消除循环依赖的方法：

上移（抽取公共模块）：将 A 和 B 共同依赖的代码抽取到新的模块 C 中，A → C，B → C。
下移（调整职责归属）：将 A 中被 B 依赖的代码移到 B 中，A → B（单向依赖）。
引入接口模块：在 A 和 B 之间插入一个接口模块 I，A → I，B → I，A 和 B 之间没有直接依赖。Dubbo 版的 api 模块就是这种模式。

在 smart-scaffold 项目中，三种架构都通过合理的模块划分避免了循环依赖。SpringBoot 版通过严格的分层依赖（web → service → dao → common）确保单向性；Dubbo 版和 SpringCloud 版通过 api/common 模块解耦 provider 和 consumer。

9.2 版本冲突的排查与解决

版本冲突是 Maven 项目中最常见的问题之一。当依赖树中同一个构件的多个版本同时存在时，可能导致 NoSuchMethodError、ClassNotFoundException、NoClassDefFoundError 等运行时错误。

排查步骤：

第一步，使用 mvn dependency:tree 查看完整的依赖树：

bash

mvn dependency:tree -Dincludes=org.springframework:spring-web

第二步，使用 mvn dependency:tree -Dverbose 查看被省略的冲突依赖：

bash

mvn dependency:tree -Dverbose | grep "omitted for conflict"

第三步，使用 IDE 的依赖分析工具（如 IntelliJ IDEA 的 Maven Helper 插件）可视化查看冲突。

解决方案：

在 dependencyManagement 中锁定版本：这是最推荐的方式。在父 POM 的 <dependencyManagement> 中显式声明冲突依赖的版本，Maven 会使用该版本覆盖传递依赖带来的版本。

xml

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-web</artifactId>
            <version>6.1.5</version>
        </dependency>
    </dependencies>
</dependencyManagement>

使用 exclusion 排除冲突版本：在引入冲突依赖的地方排除不需要的版本。
升级引入冲突依赖的库：如果冲突是因为某个库引入了过旧版本的传递依赖，升级该库通常可以解决问题。

9.3 资源文件找不到的根因分析

"资源文件找不到"是 Maven 项目中另一个常见问题，表现形式包括：

FileNotFoundException：运行时找不到配置文件。
MyBatis 报 Invalid bound statement：找不到 Mapper XML 文件。
静态资源 404：前端页面或静态文件无法访问。

根因一：资源目录配置错误

Maven 默认只识别 src/main/resources 作为资源目录。如果资源文件放在其他目录下，需要在 POM 中显式配置。

根因二：过滤配置导致资源被排除

如果 <resources> 配置中的 <includes> 或 <excludes> 规则不当，可能导致某些资源文件没有被复制到 target/classes。

根因三：MyBatis Mapper XML 没有被打包

如前所述，如果 Mapper XML 放在 src/main/java 目录下，需要额外配置 <resource> 才能被打包。忘记配置是最常见的原因。

根因四：IDE 与 Maven 构建不一致

IDE（如 IntelliJ IDEA）使用自己的构建系统，可能与 Maven 的构建结果不一致。解决方法是使用 Maven 构建而不是 IDE 内部构建，或者在 IDE 中配置使用 Maven 构建。

排查方法：

bash

# 检查 target/classes 中是否包含预期的资源文件
mvn clean compile
find target/classes -name "*.xml" -o -name "*.yml"

如果 target/classes 中缺少预期的资源文件，说明 POM 的 <resources> 配置有问题。如果资源文件存在但运行时找不到，可能是类加载器的问题。

9.4 打包后运行报错的排查思路

打包后运行报错是多模块项目中综合性最强的问题，可能涉及依赖、资源、打包配置等多个方面。

错误一：jar 不是可执行的

no main manifest attribute, in smart-scaffold-web.jar

原因：没有配置 spring-boot-maven-plugin，或者该插件没有在正确的模块中激活。检查 web 模块的 POM 中是否包含 spring-boot-maven-plugin 的 repackage 目标。

错误二：ClassNotFoundException

java.lang.ClassNotFoundException: com.example.common.utils.StringUtil

原因：common 模块没有被正确打包为依赖。检查 Fat JAR 的 BOOT-INF/lib/ 目录中是否包含 smart-scaffold-common-x.x.x.jar。如果不包含，说明 web 模块的 POM 中没有声明对 common 模块的依赖。

错误三：BeanCreationException

Error creating bean with name 'dataSource' defined in class path resource

原因：配置文件中的占位符没有被正确替换。检查资源过滤是否启用，以及 application.yml 中的属性引用是否正确。

错误四：Port already in use

***************************
APPLICATION FAILED TO START
***************************
Web server failed to start. Port 8080 was already in use.

原因：端口冲突。检查是否有其他进程占用了该端口，或者在 application.yml 中修改端口配置。

错误五：UnsatisfiedDependencyException

Unsatisfied dependency expressed through constructor parameter 0

原因：Spring Bean 的依赖注入失败。可能是因为某个 Bean 所在的包不在组件扫描范围内，或者条件注解（如 @ConditionalOnProperty）的条件不满足。

通用排查方法：

检查 Fat JAR 结构：jar tf smart-scaffold-web.jar | head -50
检查 MANIFEST.MF：unzip -p smart-scaffold-web.jar META-INF/MANIFEST.MF
使用 --debug 参数启动：java -jar smart-scaffold-web.jar --debug
检查依赖树：mvn dependency:tree
使用 Actuator 端点诊断：访问 /actuator/health 和 /actuator/env

总结与展望

Maven 多模块项目的工程化实践远不止 pom.xml 的配置编写，它涉及架构设计决策、构建流程优化、环境管理策略等多个维度。通过对 smart-scaffold 项目三种架构的深入分析，我们可以提炼出以下核心认知：

架构决定模块划分。SpringBoot 单体版的分层模块结构、Dubbo 版的接口-实现分离结构、SpringCloud 版的公共模块-服务角色结构，各有其适用场景。选择哪种结构，取决于项目的架构范式和团队的组织方式。

依赖管理是工程化的基石。dependencyManagement 与 dependencies 的区别、scope 的正确使用、optional 依赖的合理运用，这些细节决定了项目的依赖是否清晰、可控、可维护。

资源过滤是连接构建与配置的桥梁。通过 Maven 资源过滤与 Spring Profile 的联动，可以实现从构建时到运行时的全链路配置管理，支撑多环境的平滑切换。

构建优化是持续交付的保障。并行构建、依赖缓存、镜像加速、多阶段 Docker 构建，这些优化手段共同缩短了从代码提交到部署上线的反馈周期。

展望未来，随着 Java 构建生态的演进，Maven 正面临着 Gradle 等新兴构建工具的竞争。Gradle 在构建速度、配置灵活性、DSL 表达力等方面具有优势，但 Maven 在稳定性、插件生态、社区支持等方面仍然不可替代。对于企业级项目而言，Maven 的成熟度和可预测性仍然是其最大的优势。

无论构建工具如何演进，本文所讨论的工程化原则——模块化设计、依赖管理、资源过滤、构建优化、环境隔离——都是超越工具的通用理念。掌握这些原则，才能在面对不同的技术选型时做出合理的架构决策。

版权声明： 本文为必码（bima.cc）原创技术文章，仅供学习交流。
本文内容基于实际项目源码解析整理，代码示例均为教学简化版本，仅供学习参考。
文档内容提取自项目源码与配置文件，如需获取完整项目代码，请访问 bima.cc。

Maven 多模块项目工程化实践：依赖管理、资源过滤与构建优化 ​

前言 ​

一、Maven 多模块项目概述 ​

1.1 为什么需要多模块 ​

1.2 三种架构的模块结构对比 ​

1.3 模块划分的核心原则 ​

二、父 POM 继承与依赖管理 ​

2.1 Parent POM 的核心职责 ​

2.2 spring-boot-starter-parent 继承体系 ​

2.3 dependencyManagement 与 dependencies 的本质区别 ​

2.4 Spring Cloud BOM 的引入方式 ​

2.5 全局依赖版本统一管理 ​

2.6 pluginManagement 与 plugins 的协同 ​

三、子模块 POM 设计 ​

3.1 模块间依赖关系设计 ​

3.2 依赖作用域管理 ​

3.3 optional 依赖的巧妙运用 ​

3.4 spring-boot-maven-plugin 的精准配置 ​

四、资源过滤配置 ​

4.1 Maven 资源过滤机制原理 ​

4.2 filtering 与非 filtering 资源的分离策略 ​

4.3 配置文件的变量替换实践 ​

4.4 二进制文件的排除规则 ​

4.5 MyBatis XML Mapper 的资源构建 ​

五、Spring Boot 可执行 JAR 打包 ​

5.1 spring-boot-maven-plugin 工作原理 ​

5.2 repackage 目标深度解析 ​

5.3 excludes 配置与依赖裁剪 ​

5.4 finalName 自定义与版本管理 ​

5.5 瘦 JAR 与 Fat JAR 的取舍 ​

六、Maven 构建性能优化 ​

6.1 并行构建 -T 参数详解 ​

6.2 跳过测试与分层测试策略 ​

6.3 本地仓库缓存机制 ​

6.4 镜像加速配置 ​

6.5 依赖分析与冲突排查 ​

七、多环境 Profile 配置 ​

7.1 Spring Profile 机制概述 ​

7.2 多环境配置文件设计 ​

7.3 Profile 激活的多种方式 ​

7.4 各环境差异化配置实践 ​

7.5 Maven Profile 与 Spring Profile 的联动 ​

八、Maven 与 Docker 集成 ​

8.1 多阶段构建中的 Maven 配置 ​

8.2 .m2 缓存优化策略 ​

8.3 构建参数传递与动态配置 ​

8.4 Dockerfile 最佳实践 ​

九、常见问题与解决方案 ​

9.1 循环依赖的诊断与消除 ​

9.2 版本冲突的排查与解决 ​

9.3 资源文件找不到的根因分析 ​

9.4 打包后运行报错的排查思路 ​

总结与展望 ​

Maven 多模块项目工程化实践：依赖管理、资源过滤与构建优化

前言

一、Maven 多模块项目概述

1.1 为什么需要多模块

1.2 三种架构的模块结构对比

1.3 模块划分的核心原则

二、父 POM 继承与依赖管理

2.1 Parent POM 的核心职责

2.2 spring-boot-starter-parent 继承体系

2.3 dependencyManagement 与 dependencies 的本质区别

2.4 Spring Cloud BOM 的引入方式

2.5 全局依赖版本统一管理

2.6 pluginManagement 与 plugins 的协同

三、子模块 POM 设计

3.1 模块间依赖关系设计

3.2 依赖作用域管理

3.3 optional 依赖的巧妙运用

3.4 spring-boot-maven-plugin 的精准配置

四、资源过滤配置

4.1 Maven 资源过滤机制原理

4.2 filtering 与非 filtering 资源的分离策略

4.3 配置文件的变量替换实践

4.4 二进制文件的排除规则

4.5 MyBatis XML Mapper 的资源构建

五、Spring Boot 可执行 JAR 打包

5.1 spring-boot-maven-plugin 工作原理

5.2 repackage 目标深度解析

5.3 excludes 配置与依赖裁剪

5.4 finalName 自定义与版本管理

5.5 瘦 JAR 与 Fat JAR 的取舍

六、Maven 构建性能优化

6.1 并行构建 -T 参数详解

6.2 跳过测试与分层测试策略

6.3 本地仓库缓存机制

6.4 镜像加速配置

6.5 依赖分析与冲突排查

七、多环境 Profile 配置

7.1 Spring Profile 机制概述

7.2 多环境配置文件设计

7.3 Profile 激活的多种方式

7.4 各环境差异化配置实践

7.5 Maven Profile 与 Spring Profile 的联动

八、Maven 与 Docker 集成

8.1 多阶段构建中的 Maven 配置

8.2 .m2 缓存优化策略

8.3 构建参数传递与动态配置

8.4 Dockerfile 最佳实践

九、常见问题与解决方案

9.1 循环依赖的诊断与消除

9.2 版本冲突的排查与解决

9.3 资源文件找不到的根因分析

9.4 打包后运行报错的排查思路

总结与展望