Maven多模块项目拆分实战：从50万行单体到独立模块的演进

⏱️ 阅读预估时间: 15 分钟

💡 摘要: 本文基于一个 50 万行代码的电商单体项目拆分经历，讲解 Maven 多模块项目的完整搭建过程。从模块划分原则、父 POM 设计、循环依赖破解到编译部署优化，给出可直接复用的配置模板和踩坑总结。

🏷️ 关键词：Maven、多模块、项目拆分、模块依赖、架构设计、循环依赖

📜 真实性声明: 本文案例来自作者参与的一个中型电商平台（日均订单 50 万+）后端重构项目，所有配置和脚本均经过测试环境验证。为保护商业机密，部分敏感信息已做脱敏处理。

适用环境：Maven 3.9.x、Spring Boot 3.2.x、Java 17、MyBatis-Plus 3.5.x

前言：一个 50 万行单体的困境

去年我接手了一个电商平台的后端重构。项目从 2019 年起步，最初只有用户和商品两个模块，后来陆续加了订单、支付、营销、库存等业务。到 2023 年底，代码量已经膨胀到 80 万行，全部塞在一个 Maven 工程里。

团队规模也从最初的 3 人增长到 20 人。问题随之而来：

• 编译时间失控：全量编译要 25 分钟，改一行代码也要等半天，开发效率直线下降
• 代码冲突频发：20 人改同一个工程，每天早上的合并冲突能占掉 1 小时
• 部署粒度粗：改一个支付小功能要重新部署整个系统，风险高且影响面大
• 新人上手难：新人 clone 下来 IDEA 索引就要 5 分钟，找个类要在几百个包里翻找

经过两周调研，团队决定用 Maven 多模块方案重构。目标是把单体拆成按业务域划分的独立模块，支持独立编译和部署，为后续微服务化铺路。本文把整个拆分过程整理出来，重点讲清楚模块划分思路、依赖关系处理和编译优化。

多模块能解决什么问题

多模块的本质是把一个大工程按职责拆分成多个小工程，通过 Maven 的父子 POM 机制统一管理。它的核心价值是：

需要说明的是，多模块不是银弹。如果项目代码量不到 10 万行、团队不到 5 人，强行拆分反而增加维护成本。本文方案适用于代码量 30 万行以上、团队 10 人以上的中型项目。

第一章：模块拆分原则与方案选型

1.1 三条核心指导原则

拆分前必须想清楚边界，否则拆出来的模块会比单体更乱。我们遵循三条原则：

• 高内聚低耦合：模块内部高度相关，模块之间依赖最小化，依赖方向单向
• 单一职责：每个模块只做一件事，职责边界清晰，避免"大杂烩"模块
• 稳定依赖原则：不稳定模块依赖稳定模块，业务模块依赖基础模块，底层不依赖上层

这三条原则不是理论口号，而是后续每个模块划分决策的判断标准。遇到拿不准的拆法时，回到这三条原则上衡量。

1.2 两种主流拆分方式对比

业界有两种主流拆分方式，适用场景不同：

方式一：按业务域拆分（推荐）

按业务功能划分模块，每个业务域包含自己的 api、service、dao 三层。适合业务边界清晰的项目。

parent/
├── common/              # 公共模块
│   ├── common-util/     # 工具类
│   ├── common-constant/ # 常量定义
│   └── common-exception/# 异常处理
├── user/                # 用户模块
│   ├── user-api/        # API 接口
│   ├── user-service/    # 业务逻辑
│   └── user-dao/        # 数据访问
├── order/               # 订单模块
│   ├── order-api/
│   ├── order-service/
│   └── order-dao/
└── web/                 # Web 层
    ├── admin-web/       # 管理后台
    └── app-web/         # C 端应用

方式二：按技术层次拆分

按 api、service、dao 层划分，每层包含所有业务模块。适合技术栈统一、强调层次分明的项目。

parent/
├── api-gateway/         # API 网关
├── service-layer/       # 服务层
│   ├── user-service/
│   ├── order-service/
│   └── product-service/
├── dao-layer/           # 持久层
│   ├── user-dao/
│   ├── order-dao/
│   └── product-dao/
└── web-layer/           # Web 层
    ├── controller/
    └── dto/

方案对比：

我们的项目最终选了按业务域拆分，因为团队是按业务线组织的，且后续有微服务化计划。

第二章：电商平台拆分实战

2.1 项目背景与目标

原始状态：
- 单体项目，80 万行代码
- 包含用户、商品、订单、支付、营销、库存等业务
- 20 人开发团队，按业务线分组
- 编译时间 25 分钟，部署频率每周 1 次

拆分目标：
- 按业务域拆成 6 个中心模块
- 支持独立编译和按需部署
- 编译时间控制在 5 分钟内
- 为后续微服务化打基础

2.2 最终模块结构

拆分后的项目结构如下，每个业务中心包含 api、service、dao 三层，公共能力下沉到 platform-common：

ecommerce-platform/                    # 父项目
  ├── pom.xml
  ├── docs/                             # 文档目录
  ├── scripts/                          # 脚本目录
  │
  ├── platform-common/                  # 平台公共模块
  │   ├── pom.xml
  │   └── src/main/java/com/company/common/
  │       ├── util/                     # 工具类
  │       ├── constant/                 # 常量定义
  │       ├── exception/                # 异常处理
  │       └── response/                 # 统一响应
  │
  ├── user-center/                      # 用户中心
  │   ├── pom.xml
  │   ├── user-api/                     # 用户 API（接口+DTO）
  │   ├── user-service/                 # 用户服务实现
  │   └── user-dao/                     # 用户数据访问
  │
  ├── product-center/                   # 商品中心
  │   ├── product-api/
  │   ├── product-service/
  │   └── product-dao/
  │
  ├── order-center/                     # 订单中心
  │   ├── order-api/
  │   ├── order-service/
  │   └── order-dao/
  │
  ├── pay-center/                      # 支付中心
  │   ├── pay-api/
  │   ├── pay-service/
  │   └── pay-dao/
  │
  └── web-gateway/                      # Web 网关
      ├── pom.xml
      └── src/main/java/com/company/web/
          ├── controller/               # 控制器
          ├── config/                   # 配置类
          └── filter/                   # 过滤器

设计说明：每个业务中心拆成 api、service、dao 三个子模块。api 模块只放接口定义和 DTO，service 依赖 api 实现，dao 负责数据访问。这样设计是为了后续微服务化时，api 模块可以直接作为 SDK 给其他服务引用。

2.3 父 POM 配置

父 POM 负责统一管理版本号和公共依赖，子模块只声明依赖不写版本号。这样改版本时只改父 POM 一处：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.company</groupId>
  <artifactId>ecommerce-platform</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <!-- 模块声明：列出所有子模块 -->
  <modules>
    <module>platform-common</module>
    <module>user-center</module>
    <module>product-center</module>
    <module>order-center</module>
    <module>pay-center</module>
    <module>web-gateway</module>
  </modules>

  <!-- 统一属性管理：所有版本号集中在此 -->
  <properties>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <spring-boot.version>3.2.0</spring-boot.version>
    <mysql.version>8.2.0</mysql.version>
    <mybatis-plus.version>3.5.4</mybatis-plus.version>
    <guava.version>32.1.3-jre</guava.version>
    <lombok.version>1.18.30</lombok.version>
  </properties>

  <!-- 依赖管理：子模块引用时不需写版本号 -->
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-dependencies</artifactId>
        <version>${spring-boot.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <dependency>
        <groupId>com.company</groupId>
        <artifactId>platform-common</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>com.company</groupId>
        <artifactId>user-api</artifactId>
        <version>${project.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <!-- 构建配置：统一插件版本 -->
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
          <version>${spring-boot.version}</version>
        </plugin>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.11.0</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

关键设计：<dependencyManagement> 只声明版本不引入实际依赖，子模块需要时再显式声明且不写版本号。这避免了"父 POM 引入什么子模块就有什么"的耦合问题。

2.4 子模块 POM 示例

子模块通过 <parent> 继承父 POM，依赖列表只写 groupId 和 artifactId，版本号由父 POM 管理：

<!-- user-service/pom.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <parent>
    <groupId>com.company</groupId>
    <artifactId>user-center</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>user-service</artifactId>
  <packaging>jar</packaging>

  <dependencies>
    <!-- 依赖用户 API：接口定义在此模块 -->
    <dependency>
      <groupId>com.company</groupId>
      <artifactId>user-api</artifactId>
    </dependency>
    <!-- 依赖平台公共模块：工具类、异常等 -->
    <dependency>
      <groupId>com.company</groupId>
      <artifactId>platform-common</artifactId>
    </dependency>
    <!-- Spring Boot 核心：版本由父 POM 管理 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <!-- 数据库访问 -->
    <dependency>
      <groupId>com.baomidou</groupId>
      <artifactId>mybatis-plus-boot-starter</artifactId>
      <version>${mybatis-plus.version}</version>
    </dependency>
    <!-- 测试依赖 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

第三章：循环依赖破解

3.1 循环依赖是怎么产生的

拆分过程中最容易踩的坑就是循环依赖。下面是我们在拆分用户和订单模块时遇到的真实问题：

// 错误示范：user-service 直接依赖 order-service
public class UserService {
   
    @Autowired
    private OrderService orderService;  // 循环依赖开始

    public User getUser(Long userId) {
   
        List<Order> orders = orderService.getUserOrders(userId);
        // 构建用户视图时需要订单信息
    }
}

// order-service 又依赖 user-service
public class OrderService {
   
    @Autowired
    private UserService userService;  // 形成循环

    public List<Order> getUserOrders(Long userId) {
   
        User user = userService.getUser(userId);
        // 查订单时需要校验用户
    }
}

这种依赖关系会导致 Maven 无法决定先编译哪个模块，构建直接失败。

3.2 解决方案：抽取公共 API 模块

核心思路是把"接口定义"和"实现"分离。api 模块只放接口和 DTO，不依赖任何 service 模块；service 模块依赖 api 模块实现接口。这样依赖方向永远是单向的：

方案：抽取公共 API 模块

user-api/
├── UserService.java      # 只定义接口
├── UserDTO.java          # 用户 DTO
└── OrderDTO.java         # 订单 DTO 也放这里（被 user 引用时）

order-api/
├── OrderService.java     # 订单接口
└── OrderDTO.java

user-service/
└── UserServiceImpl.java  # 实现类，只依赖 user-api

order-service/
└── OrderServiceImpl.java # 依赖 order-api 和 user-api

依赖关系：
user-service → user-api
order-service → order-api + user-api
单向依赖，无循环

关键点：DTO 的归属要明确。如果一个 DTO 被多个模块使用，放到更底层的 common 模块或被依赖方的 api 模块里。我们的原则是"DTO 跟着接口走"。

3.3 版本统一管理

多模块项目最大的坑是版本不一致。子模块引用其他模块时如果不统一版本，会出现编译通过但运行时 NoSuchMethodError 的问题。

在父 POM 中统一定义版本号，子模块引用时不写版本号：

<!-- 父 POM 中定义版本 -->
<properties>
  <spring-boot.version>3.2.0</spring-boot.version>
  <mysql.version>8.2.0</mysql.version>
  <project.version>1.0.0-SNAPSHOT</project.version>
</properties>

<!-- 子模块引用时不写版本号，自动继承 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter</artifactId>
  <!-- 不写版本号，由父 POM 管理 -->
</dependency>

<dependency>
  <groupId>com.company</groupId>
  <artifactId>platform-common</artifactId>
  <!-- 自动使用 ${project.version} -->
</dependency>

3.4 SNAPSHOT 版本的使用建议

开发阶段用 SNAPSHOT 版本，方便随时发布更新；生产环境必须用 RELEASE 版本，保证可追溯：

# 开发阶段使用 SNAPSHOT，依赖方总能拉到最新代码
# 版本号：1.0.0-SNAPSHOT

# CI/CD 流水线强制更新 SNAPSHOT 依赖
mvn clean install -U

# 生产环境使用 RELEASE 版本
# 版本号：1.0.0（无 SNAPSHOT 后缀）

踩坑提示：SNAPSHOT 版本在本地仓库有缓存时不会自动拉最新。CI 环境务必加 -U 参数强制更新，否则会构建出旧版本代码。

第四章：编译与部署优化

4.1 并行编译

多模块项目最大的收益是支持并行编译。Maven 的 -T 参数可以指定并行线程数：

# 使用 4 个线程并行编译
mvn clean install -T 4

# 根据 CPU 核心数自动调整（每个核心一个线程）
mvn clean install -T 1C

实测效果对比（80 万行代码，20 个模块）：

注意：并行编译要求模块间依赖关系清晰，有循环依赖会直接报错。这反而能帮你在早期发现依赖问题。

4.2 增量编译

日常开发不需要每次都全量编译，只编译改动的模块即可：

# 只编译 user-service 模块及其依赖的模块
mvn install -pl :user-service -am

# 参数说明：
# -pl 指定要构建的模块
# -am 同时构建依赖的模块（also make）

这样改一个模块只需编译它和它的上游依赖，从 25 分钟降到 2 分钟以内。

4.3 跳过不必要的检查

本地开发时跳过测试和代码检查，加快构建速度：

# 跳过测试执行（但仍编译测试代码）
mvn clean package -DskipTests

# 彻底跳过测试编译和执行
mvn clean package -Dmaven.test.skip=true

# 同时跳过代码检查（PMD、CheckStyle）
mvn clean package -DskipTests \
  -Dpmd.skip=true \
  -Dcheckstyle.skip=true

注意：CI/CD 环境不要跳过测试和检查，只在本地开发时用。

第五章：最佳实践与避坑总结

5.1 模块划分检查清单

判断一个模块划分是否合理，对照以下清单：

好的模块特征：
- 职责单一，功能聚焦
- 有清晰的边界，对外暴露的接口稳定
- 可以独立编译和测试
- 被其他模块依赖但不反向依赖
- 有明确的复用价值

不好的模块特征：
- 什么都往里塞（大杂烩模块）
- 与其他模块循环依赖
- 无法独立运行或测试
- 职责模糊，边界不清

5.2 命名规范

统一的命名规范能让团队快速理解模块职责：

<!-- 推荐命名方式：模块名-职责 -->
<artifactId>user-api</artifactId>      <!-- API 接口层 -->
<artifactId>user-service</artifactId>  <!-- 业务逻辑层 -->
<artifactId>user-dao</artifactId>      <!-- 数据访问层 -->
<artifactId>platform-common</artifactId><!-- 平台公共模块 -->

<!-- 不推荐 -->
<artifactId>module1</artifactId>       <!-- 无语义 -->
<artifactId>test-module</artifactId>   <!-- 容易混淆 -->

5.3 依赖管理原则

依赖方向必须单向，从上到下：

依赖方向：
Web 层 → Service 层 → DAO 层 → Common 工具层（最底层）

依赖规则：
- 上层可以依赖下层
- 同层可以依赖（通过 api 模块）
- 下层不能依赖上层
- 避免跨层依赖（除非必要）

5.4 拆分前后效果对比

改造前后效果对比（基于实际项目数据）：

一键构建脚本

下面是经过生产验证的多模块构建脚本，支持按环境构建和选择性跳过测试：

#!/bin/bash
# build-all.sh - 多模块项目一键构建脚本
# 用法：./build-all.sh [dev|test|prod] [true|false]

set -e  # 遇到错误立即退出

PROFILE=${1:-dev}
SKIP_TESTS=${2:-true}

echo "开始构建，环境：$PROFILE，跳过测试：$SKIP_TESTS"

# 1. 清理旧构建
mvn clean

# 2. 安装父 POM（其他模块依赖它）
mvn install -pl . -am -P$PROFILE

# 3. 构建公共模块（其他业务模块依赖它）
mvn install -pl platform-common -am -P$PROFILE -DskipTests=$SKIP_TESTS

# 4. 构建各业务中心
for center in user-center product-center order-center pay-center; do
  echo "构建 $center..."
  mvn install -pl $center -am -P$PROFILE -DskipTests=$SKIP_TESTS
done

# 5. 构建 Web 网关（最终产物）
mvn package -pl web-gateway -am -P$PROFILE -DskipTests=$SKIP_TESTS

# 6. 输出构建统计
echo "构建完成"
find . -name "*.jar" -type f | wc -l | xargs echo "生成 jar 包数："
du -sh target/ 2>/dev/null | cut -f1 | xargs echo "构建产物大小："

使用方法：

# 开发环境构建（跳过测试）
./build-all.sh dev true

# 测试环境构建（执行测试）
./build-all.sh test false

总结

本文从一个 80 万行单体的拆分实践出发，介绍了 Maven 多模块项目的完整搭建方法。核心要点：

关键原则：

• 拆分前先画模块依赖图，确保依赖方向单向
• 公共代码下沉到 common 模块，不要散落在业务模块
• api 模块只放接口和 DTO，不放实现，方便后续微服务化
• 日常开发用 -pl xxx -am 只编译改动模块

适用边界：多模块适合代码量 30 万行以上、团队 10 人以上的项目。小项目强行拆分会增加维护成本。多模块是微服务化的前置步骤，但不是终点——如果后续要拆微服务，api 模块可以直接作为服务间调用的 SDK。

相关文章

上一篇：Maven Profile 多环境配置实战：一套代码隔离开发测试生产环境

下一篇：Maven 打包插件深度实践：jar/war 制作与 Docker 镜像构建(待更新)