架构与系统设计 / 系统课时
多模块工程划分
多模块工程划分
本课把单体代码仓库拆成职责清晰的 Maven 多模块工程,并用固定依赖方向隔离认证、租户、业务、基础设施与接口层,最终得到可以直接构建和继续开发的工程骨架。
学习目标
- 明确各模块的职责、公开边界和禁止依赖
- 创建可聚合构建的 Maven 父工程与子模块
- 通过依赖树验证模块关系没有反向或循环引用
划分职责与依赖方向
模块不是按包名简单搬家,而是通过 Maven 依赖形成编译期边界。本项目采用“业务核心不依赖技术实现”的方向:认证、租户和业务模块只依赖公共模块;基础设施模块实现数据库、Redis 和消息队列适配;接口模块负责装配并暴露 HTTP 接口。
| 模块 | 主要职责 | 允许直接依赖 |
|---|---|---|
saas-common |
通用异常、值对象、基础工具 | 无业务模块 |
saas-auth |
登录、令牌、权限规则 | saas-common |
saas-tenant |
租户、套餐、成员关系 | saas-common |
saas-business |
示例业务领域与用例 | saas-common、必要的租户契约 |
saas-infrastructure |
MySQL、Redis、RabbitMQ 适配器 | 公共模块和各业务模块 |
saas-api |
Spring Boot 启动、控制器、装配 | 其余全部模块 |

跨业务模块调用应优先依赖稳定的应用服务接口或只读契约,不要直接访问另一个模块的数据库 Mapper。这样后续把某个模块拆成独立服务时,改动范围会更小。
创建 Maven 聚合骨架
先建立目录。下面的命令只创建工程结构,不生成业务代码,适用于 macOS、Linux、Git Bash 和 WSL。
mkdir -p saas-common saas-auth saas-tenant saas-business saas-infrastructure saas-api预期结果是当前目录出现六个子目录,命令成功时通常没有终端输出。
saas-common/
saas-auth/
saas-tenant/
saas-business/
saas-infrastructure/
saas-api/在根目录创建父工程 pom.xml。父工程只负责聚合模块、统一 Java 版本和管理 Spring Boot 依赖,不放业务源码。
<?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>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.0</version>
<relativePath/>
</parent>
<groupId>com.example.saas</groupId>
<artifactId>saas-platform</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<modules>
<module>saas-common</module>
<module>saas-auth</module>
<module>saas-tenant</module>
<module>saas-business</module>
<module>saas-infrastructure</module>
<module>saas-api</module>
</modules>
<properties>
<java.version>21</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
</project>父 POM 生效后,所有子模块共享同一组坐标、Java 版本和依赖版本。每个子模块都要把根工程声明为 parent,避免重复维护版本。
配置子模块依赖
saas-common、saas-auth、saas-tenant 和 saas-business 都使用普通 jar 打包。下面以 saas-auth 为完整示例,它只允许依赖公共模块。
<?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>
<parent>
<groupId>com.example.saas</groupId>
<artifactId>saas-platform</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>saas-auth</artifactId>
<dependencies>
<dependency>
<groupId>com.example.saas</groupId>
<artifactId>saas-common</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
</project>saas-infrastructure 是适配器集合,需要看见业务模块中定义的仓储接口,因此依赖方向由基础设施指向业务核心,而不是相反。
<dependencies>
<dependency>
<groupId>com.example.saas</groupId>
<artifactId>saas-auth</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.example.saas</groupId>
<artifactId>saas-tenant</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.example.saas</groupId>
<artifactId>saas-business</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-amqp</artifactId>
</dependency>
</dependencies>上面是 saas-infrastructure/pom.xml 的依赖片段,需放入完整子模块 POM 的 <project> 节点内。它的生效行为是基础设施模块可以实现业务模块声明的接口,但业务模块无法直接引用 JDBC、Redis 或 RabbitMQ 类。
saas-api 负责最终装配,依赖全部业务模块与基础设施模块,并引入 Web 启动器。只有该模块需要 Spring Boot 可执行打包插件。
<dependencies>
<dependency>
<groupId>com.example.saas</groupId>
<artifactId>saas-auth</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.example.saas</groupId>
<artifactId>saas-tenant</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.example.saas</groupId>
<artifactId>saas-business</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.example.saas</groupId>
<artifactId>saas-infrastructure</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>这同样是 saas-api/pom.xml 的片段示例。认证、租户和业务模块不应依赖 saas-api,否则控制器或启动配置会反向渗透到核心代码。
构建并检查依赖
补齐每个子目录的 POM 后,在根目录执行聚合构建。当前骨架即使还没有 Java 源码,也应完成模块解析和打包。
mvn clean verify预期结果中六个子模块和父工程均为 SUCCESS,最后出现构建成功。耗时和时间戳会因机器与网络不同。
Reactor Summary:
saas-platform ................. SUCCESS
saas-common ................... SUCCESS
saas-auth ..................... SUCCESS
saas-tenant ................... SUCCESS
saas-business ................. SUCCESS
saas-infrastructure ........... SUCCESS
saas-api ...................... SUCCESS
BUILD SUCCESS再检查依赖树,确认 saas-auth 中没有基础设施或接口模块。
mvn -pl saas-auth dependency:tree预期结果只包含 saas-common 以及它明确声明的第三方依赖,不应出现 saas-infrastructure 或 saas-api。
com.example.saas:saas-auth:jar:1.0.0-SNAPSHOT
\- com.example.saas:saas-common:jar:1.0.0-SNAPSHOT:compile
BUILD SUCCESS如果 Maven 报循环依赖,不要用调整模块顺序掩盖问题。应把双方共享的数据结构或接口下沉到 saas-common,或建立独立契约模块,再删除反向依赖。
本课总结
- 模块边界必须由 Maven 依赖约束,而不能只靠包名和开发约定
- 业务核心依赖公共契约,基础设施实现业务接口,接口层负责最终装配
- 聚合构建与依赖树检查可以在编码前发现缺失模块、反向依赖和循环引用
下一课预告
下一课将为多模块工程补充统一异常、返回模型、配置分层和基础包结构,让后续租户与认证功能按同一套工程规范落地。