跳至主要內容

模块设计

GGBOND2025/5/21大约 4 分钟Java

Java 多模块项目的模块划分与 Maven 依赖管理规范

在企业级开发中，为了提高代码复用率、分工协作效率以及系统的可维护性，Java 项目通常采用 多模块（multi-module）架构。本篇将从模块划分思路出发，介绍如何进行合理的模块组织，并讲解 Maven 的依赖管理方式。

一、模块如何划分？

模块划分需遵循 高内聚、低耦合、职责单一 的原则，常见方式包括：

1. 业务维度划分

  • user-service：用户注册、登录、信息管理等功能
  • order-service：订单创建、支付、状态流转等功能
  • payment-service：支付接口、交易记录等
  • inventory-service：库存管理、锁库存、减库存等

2. 技术维度划分

  • common-module：公共工具类、DTO、统一响应结构、异常处理等
  • auth-service：权限认证中心（如 Spring Security + JWT）
  • gateway-module：统一入口网关服务（如 Spring Cloud Gateway）
  • config-service：配置中心（如 Spring Cloud Config）

二、推荐模块目录结构

my-project/
├── pom.xml               # 父模块，统一依赖和版本控制
├── common-module         # 公共模块（工具类、响应体等）
│   └── pom.xml
├── domain-module         # 实体模块，统一管理 Entity/VO/DTO
│   └── pom.xml
├── user-service          # 用户服务模块
│   └── pom.xml
├── order-service         # 订单服务模块
│   └── pom.xml
├── auth-service          # 登录认证、权限鉴权模块
│   └── pom.xml
└── gateway-module        # 网关模块
    └── pom.xml

三、父模块 pom.xml 配置（聚合模块）

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

  <modules>
    <module>common-module</module>
    <module>domain-module</module>
    <module>user-service</module>
    <module>order-service</module>
    <module>auth-service</module>
    <module>gateway-module</module>
  </modules>

  <dependencyManagement>
    <dependencies>
      <!-- 集中定义版本 -->
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>3.2.0</version>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

四、子模块 pom.xml 如何配置？

1. 继承父模块

<parent>
  <groupId>com.example</groupId>
  <artifactId>my-project</artifactId>
  <version>1.0.0</version>
</parent>

2. 引入依赖（无需指定版本）

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  
  <!-- 引入公共模块 -->
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>common-module</artifactId>
  </dependency>

  <!-- 引入实体模块 -->
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>domain-module</artifactId>
  </dependency>
</dependencies>

五、模块命名规范

命名方式示例说明
功能导向user-service用户服务模块
公共模块common-module工具类、统一响应、异常处理
实体模块domain-moduleEntity、DTO、VO 集中管理
鉴权模块auth-serviceSpring Security、JWT 管理
接口模块api-gateway网关服务模块

命名建议：

  • 使用 kebab-case（小写+短横线）用于文件夹和 artifactId
  • 模块名使用名词组合，避免使用动词，如：process-order
  • 避免混用大小写或缩写不统一

六、登录与权限认证模块放哪？

推荐将登录和权限认证逻辑单独抽离为 auth-service 模块，职责包括：

功能放置模块说明
登录接口、验证码、密码校验auth-service控制器、登录逻辑
用户权限加载、认证逻辑auth-service + user-service实现 UserDetailsService
JWT 工具类common-module加解密、生成 token
权限控制配置auth-serviceSpring Security 拦截器配置等
实体类（User、Role）domain-module所有模块共用

七、模块源码结构标准（src）

每个模块应采用 Maven 标准结构：

模块/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/             # 源码目录（必须）
    │   │   └── com/example/xxx
    │   └── resources/        # 配置文件目录
    └── test/
        └── java/             # 测试代码

所有模块都必须以 src/main/java 为 Java 源码目录，这是 Maven 默认识别的结构。

八、包名为什么是 com.example.xxx 形式？

Java 推荐使用倒置的组织域名作为包名前缀，理由如下：

  • 保证唯一性（避免类名、包名冲突）
  • 组织清晰（适合多人协作、开源发布）
  • 遵循官方规范（JDK、Spring、MyBatis 等全部采用此规范）

示例：

所属组织域名推荐包名
百度baidu.comcom.baidu.xxx
阿里alibaba.comcom.alibaba.xxx
教育系统edu.cncn.edu.xxx

九、构建 & 依赖管理建议

实践建议说明
使用父模块统一构建mvn clean install 自动构建所有子模块
公共依赖版本集中管理父模块使用 <dependencyManagement> 控制版本
尽量少写版本号子模块继承父模块，无需重复写依赖版本
封装公共逻辑共用类、工具类、响应封装统一放入 common-module
模块间显式依赖子模块间通过 groupId + artifactId 显式依赖
Copyright © 2025 GGBOND