架构与系统设计 / 系统课时
多模块工程结构
多模块工程结构
支付平台会持续增加商户、交易、路由和对账能力,单模块工程很快会出现依赖混乱。本课给出一套可扩展的 Maven 多模块骨架,使公共能力、业务规则和技术实现保持清晰边界。
学习目标
- 按职责拆分公共、契约、业务、基础设施和启动模块
- 建立只允许单向依赖的模块关系
- 使用 Maven 聚合构建并验证启动模块产物
先确定依赖方向
模块拆分的重点不是目录数量,而是限制谁可以依赖谁。业务模块应面向接口编程,基础设施模块负责实现数据库、缓存和消息队列适配器,启动模块只负责装配组件并提供运行入口。

推荐的职责划分如下:
| 模块 | 主要职责 | 禁止放入 |
|---|---|---|
pay-common |
通用异常、结果对象、基础工具 | 具体业务规则 |
pay-contract |
DTO、领域端口、服务接口 | 数据库实现 |
pay-service-merchant |
商户领域用例与规则 | Controller 启动配置 |
pay-service-trade |
下单、支付、退款等用例 | MQ 客户端细节 |
pay-infrastructure |
MyBatis、Redis、RabbitMQ 适配器 | 业务流程编排 |
pay-boot |
Spring Boot 入口、配置和组件装配 | 可复用业务代码 |
创建目录骨架
先建立聚合工程和六个子模块。下面的命令可直接在空目录中执行。
mkdir -p payment-platform/{pay-common,pay-contract,pay-service-merchant,pay-service-trade,pay-infrastructure,pay-boot}
cd payment-platform
find . -maxdepth 1 -type d | sort预期输出
.
./pay-boot
./pay-common
./pay-contract
./pay-infrastructure
./pay-service-merchant
./pay-service-trade模块名使用统一前缀,能在依赖树、日志和制品仓库中快速识别归属。业务模块按领域拆分,而不是按 controller、service、mapper 这类技术分层拆成独立模块。
配置根聚合 POM
在根目录创建 pom.xml。这是完整的聚合 POM,负责统一 Java 版本、Spring Boot 依赖版本和子模块构建顺序;每个子模块仍需创建自己的 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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example.payment</groupId>
<artifactId>payment-platform</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
<java.version>21</java.version>
<spring-boot.version>3.5.0</spring-boot.version>
<maven.compiler.release>${java.version}</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<modules>
<module>pay-common</module>
<module>pay-contract</module>
<module>pay-service-merchant</module>
<module>pay-service-trade</module>
<module>pay-infrastructure</module>
<module>pay-boot</module>
</modules>
<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>
</dependencies>
</dependencyManagement>
</project>dependencyManagement 只统一版本,不会自动把依赖加入子模块。子模块需要在自己的 <dependencies> 中显式声明真正使用的依赖,这能避免公共模块被无意间带入数据库或 Web 组件。
声明启动模块依赖
片段示例:下面是 pay-boot/pom.xml 的核心依赖部分,依赖坐标需要放入继承根 POM 的完整子模块文件中。启动模块负责聚合业务实现,不应被任何其他模块依赖。
<dependencies>
<dependency>
<groupId>com.example.payment</groupId>
<artifactId>pay-service-merchant</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.example.payment</groupId>
<artifactId>pay-service-trade</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.example.payment</groupId>
<artifactId>pay-infrastructure</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>业务模块只依赖 pay-common 与 pay-contract。pay-infrastructure 可以依赖 pay-contract 来实现端口,但业务模块不能直接引用 MyBatis Mapper、RedisTemplate 或 RabbitMQ 客户端。
构建并检查边界
所有子模块 POM 和源码就绪后,从根目录构建启动模块,并通过 -am 自动同时构建它依赖的模块。
mvn -pl pay-boot -am clean package -DskipTests预期输出
[INFO] Reactor Summary:
[INFO] payment-platform ........................ SUCCESS
[INFO] pay-common .............................. SUCCESS
[INFO] pay-contract ............................ SUCCESS
[INFO] pay-service-merchant .................... SUCCESS
[INFO] pay-service-trade ....................... SUCCESS
[INFO] pay-infrastructure ...................... SUCCESS
[INFO] pay-boot ................................ SUCCESS
[INFO] BUILD SUCCESS实际耗时和日志行数会不同,但模块顺序应符合依赖关系。若 Maven 报循环依赖,优先检查是否把基础设施实现放进了契约模块,或让业务模块反向依赖了启动模块。