Maven 多模块项目设计与构建

Maven实战：多模块项目设计与构建

1. 为什么需要多模块项目？

随着项目规模的增长，单模块架构会面临诸多挑战：

1.1 单模块项目的痛点

• 代码耦合严重：所有功能混在一起，修改一处可能影响全局
• 构建效率低下：每次修改都要重新构建整个项目
• 复用困难：难以将通用功能抽取给其他项目使用
• 团队协作冲突：多个团队在同一个模块中开发容易产生冲突
• 部署不灵活：必须整体部署，无法按模块独立部署

1.2 多模块项目的优势

• 代码组织与架构清晰化
• 依赖管理精细化
• 构建效率显著提升
• 团队协作效率优化
• 测试策略更加灵活
• 版本管理统一化
• 部署策略多样化
• 代码复用性最大化
• 技术债务管理更加有效
• 持续集成/持续部署优化

下一章节我将详细讲解多模块项目的核心优势

2. 多模块项目基础概念

2.1 聚合模块（Parent POM）

聚合模块的packaging必须为pom，它负责管理子模块的构建顺序和公共配置。

<!-- 父pom.xml -->
<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.company</groupId>
    <artifactId>enterprise-app</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>  <!-- 关键：打包方式为pom -->
    
    <name>企业级应用平台</name>
    <description>多模块企业级应用示例</description>
    
    <!-- 子模块声明 -->
    <modules>
        <module>core-module</module>
        <module>service-module</module>
        <module>web-module</module>
        <module>integration-module</module>
    </modules>
</project>

2.2 项目结构设计

enterprise-app/                    # 根目录（聚合模块）
├── pom.xml                       # 父POM
├── core-module/                  # 核心模块
│   ├── pom.xml
│   └── src/
├── service-module/               # 服务模块  
│   ├── pom.xml
│   └── src/
├── web-module/                   # Web模块
│   ├── pom.xml
│   └── src/
└── integration-module/           # 集成模块
    ├── pom.xml
    └── src/

2.3 实战：从单模块到多模块的演进

(1) 阶段一：单模块项目分析

假设我们有一个电商单模块项目：

// 原始单模块结构
ecommerce-app/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   ├── com/company/controller/  # 控制层
│   │   │   ├── com/company/service/     # 业务层
│   │   │   ├── com/company/domain/      # 领域层
│   │   │   ├── com/company/repository/  # 数据层
│   │   │   └── com/company/common/      # 通用工具
│   │   └── resources/
│   └── test/
└── pom.xml

(2) 阶段二：设计模块拆分方案

根据职责单一原则进行模块拆分：

• ecommerce-core
• ecommerce-service
• ecommerce-web
• ecommerce-integration

(3) 阶段三：创建父POM文件

<?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>com.company.ecommerce</groupId>
    <artifactId>ecommerce-platform</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    
    <!-- 模块声明 -->
    <modules>
        <module>ecommerce-core</module>
        <module>ecommerce-service</module>
        <module>ecommerce-web</module>
        <module>ecommerce-integration</module>
    </modules>
    
    <!-- 属性管理 -->
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <spring.version>5.3.8</spring.version>
        <junit.version>5.7.2</junit.version>
    </properties>
    
    <!-- 依赖管理 -->
    <dependencyManagement>
        <dependencies>
            <!-- Spring框架依赖管理 -->
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-framework-bom</artifactId>
                <version>${spring.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            
            <!-- 测试依赖 -->
            <dependency>
                <groupId>org.junit.jupiter</groupId>
                <artifactId>junit-jupiter</artifactId>
                <version>${junit.version}</version>
                <scope>test</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    
    <!-- 构建配置 -->
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.8.1</version>
                    <configuration>
                        <source>${maven.compiler.source}</source>
                        <target>${maven.compiler.target}</target>
                        <encoding>${project.build.sourceEncoding}</encoding>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

(4) 阶段四：创建核心模块（ecommerce-core）

<!-- ecommerce-core/pom.xml -->
<project>
    <modelVersion>4.0.0</modelVersion>
    
    <!-- 继承父POM -->
    <parent>
        <groupId>com.company.ecommerce</groupId>
        <artifactId>ecommerce-platform</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    
    <artifactId>ecommerce-core</artifactId>
    <packaging>jar</packaging>
    
    <dependencies>
        <!-- 核心模块依赖 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </dependency>
        
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.12.4</version>
        </dependency>
        
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.20</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

核心模块包含内容：

• 领域模型（Entity、VO、DTO）
• 通用工具类
• 异常定义
• 常量定义
• 基础配置

(5) 阶段五：创建服务模块（ecommerce-service）

<!-- ecommerce-service/pom.xml -->
<project>
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>com.company.ecommerce</groupId>
        <artifactId>ecommerce-platform</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    
    <artifactId>ecommerce-service</artifactId>
    <packaging>jar</packaging>
    
    <dependencies>
        <!-- 依赖核心模块 -->
        <dependency>
            <groupId>com.company.ecommerce</groupId>
            <artifactId>ecommerce-core</artifactId>
            <version>${project.version}</version>
        </dependency>
        
        <!-- 服务模块特有依赖 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-tx</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.mybatis</groupId>
            <artifactId>mybatis</artifactId>
            <version>3.5.7</version>
        </dependency>
    </dependencies>
</project>

(6) 阶段六：创建Web模块（ecommerce-web）

<!-- ecommerce-web/pom.xml -->
<project>
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>com.company.ecommerce</groupId>
        <artifactId>ecommerce-platform</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    
    <artifactId>ecommerce-web</artifactId>
    <packaging>war</packaging>  <!-- Web应用打包为WAR -->
    
    <dependencies>
        <!-- 依赖服务模块 -->
        <dependency>
            <groupId>com.company.ecommerce</groupId>
            <artifactId>ecommerce-service</artifactId>
            <version>${project.version}</version>
        </dependency>
        
        <!-- Web模块特有依赖 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
        </dependency>
        
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>4.0.1</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    
    <build>
        <finalName>ecommerce-web</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.1</version>
            </plugin>
        </plugins>
    </build>
</project>

(7) 阶段七：创建集成模块（ecommerce-integration）

<!-- ecommerce-integration/pom.xml -->
<project>
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>com.company.ecommerce</groupId>
        <artifactId>ecommerce-platform</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    
    <artifactId>ecommerce-integration</artifactId>
    <packaging>jar</packaging>
    
    <dependencies>
        <!-- 依赖核心模块 -->
        <dependency>
            <groupId>com.company.ecommerce</groupId>
            <artifactId>ecommerce-core</artifactId>
            <version>${project.version}</version>
        </dependency>
        
        <!-- 集成模块特有依赖 -->
        <dependency>
            <groupId>org.springframework.integration</groupId>
            <artifactId>spring-integration-core</artifactId>
            <version>5.5.2</version>
        </dependency>
        
        <dependency>
            <groupId>redis.clients</groupId>
            <artifactId>jedis</artifactId>
            <version>3.6.3</version>
        </dependency>
    </dependencies>
</project>

3. 多模块项目构建与管理

3.1 统一构建所有模块

# 在根目录执行，构建所有模块
mvn clean install

# 构建顺序：core → service → integration → web
# Maven会自动识别依赖关系，按正确顺序构建

3.2 构建特定模块

# 只构建核心模块
mvn -pl ecommerce-core clean install

# 构建核心模块及其依赖模块
mvn -pl ecommerce-web -am clean install

# 排除特定模块构建
mvn clean install -Dmaven.test.skip=true -pl !ecommerce-integration

3.3 模块间依赖关系验证

# 分析依赖树，查看模块间关系
mvn dependency:tree

# 输出示例：
[INFO] com.company.ecommerce:ecommerce-platform:pom:1.0.0-SNAPSHOT
[INFO] +-- ecommerce-core:jar:1.0.0-SNAPSHOT:compile
[INFO] +-- ecommerce-service:jar:1.0.0-SNAPSHOT:compile
[INFO] |   - ecommerce-core:jar:1.0.0-SNAPSHOT:compile
[INFO] +-- ecommerce-web:war:1.0.0-SNAPSHOT:compile
[INFO] |   - ecommerce-service:jar:1.0.0-SNAPSHOT:compile
[INFO] - ecommerce-integration:jar:1.0.0-SNAPSHOT:compile
[INFO]     - ecommerce-core:jar:1.0.0-SNAPSHOT:compile

4. 高级多模块配置技巧

4.1 聚合与继承分离

对于超大型项目，可以将聚合和继承分离：

<!-- 聚合POM（只负责模块聚合） -->
<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.company</groupId>
    <artifactId>project-aggregator</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>
    
    <modules>
        <module>parent-pom</module>
        <module>core-module</module>
        <module>service-module</module>
    </modules>
</project>

<!-- 父POM（只负责依赖管理） -->
<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.company</groupId>
    <artifactId>project-parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>
    
    <dependencyManagement>
        <!-- 统一的依赖管理 -->
    </dependencyManagement>
</project>

4.2 模块版本统一管理

<!-- 在父POM中统一管理模块版本 -->
<properties>
    <core.version>1.0.0</core.version>
    <service.version>1.0.0</service.version>
    <web.version>1.0.0</web.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.company.ecommerce</groupId>
            <artifactId>ecommerce-core</artifactId>
            <version>${core.version}</version>
        </dependency>
        <dependency>
            <groupId>com.company.ecommerce</groupId>
            <artifactId>ecommerce-service</artifactId>
            <version>${service.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

4.3 多环境配置支持

<!-- 支持不同环境的配置 -->
<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <build.env>dev</build.env>
        </properties>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <build.env>prod</build.env>
        </properties>
    </profile>
</profiles>

5. 常见问题与解决方案

问题1：循环依赖

# 错误：模块A依赖模块B，模块B又依赖模块A
[ERROR] The projects in the reactor contain a cyclic reference: 
[ERROR] Edge between 'Vertex{label='com.company:module-a'}' and 
[ERROR] 'Vertex{label='com.company:module-b'}' 

解决方案：提取公共代码到第三个模块，或重新设计模块职责。

问题2：构建顺序错误

# 确保模块依赖关系正确
mvn clean install -rf :failed-module  # 从失败模块重新开始

问题3：版本不一致

<!-- 使用dependencyManagement统一版本 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.company</groupId>
            <artifactId>common-lib</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

6. 总结

多模块项目是Maven最强大的特性之一，通过合理的模块拆分可以带来：

1. 更好的代码组织：职责分离，结构清晰
2. 更高的构建效率：增量构建，并行编译
3. 更强的复用性：模块可独立使用
4. 更灵活的部署：按需部署不同模块
5. 更好的团队协作：团队可专注于特定模块

掌握多模块项目设计与构建，是成为Maven高级使用者的重要里程碑。在实际项目中，建议根据业务复杂度和团队规模，合理规划模块拆分粒度，平衡模块化带来的好处与复杂性成本。