Java模块拆分案例如何实操

wen java案例 2026-06-27 28

本文目录导读：

Java模块拆分案例如何实操

项目结构规划
实操步骤
关键配置说明
构建与运行
常见问题解决

下面我通过一个用户管理系统的案例，手把手教你如何实操 Java 模块拆分。

项目结构规划

原始单模块项目：

user-management/
├── src/main/java/com/example/
│   ├── controller/UserController.java
│   ├── service/UserService.java
│   ├── domain/User.java
│   └── repository/UserRepository.java
└── pom.xml

拆分后多模块项目：

user-management-parent/          # 父工程（聚合）
├── pom.xml                      # 只打包为pom
├── user-common                  # 公共模块（实体类、工具类）
├── user-repository              # 数据访问模块
├── user-service                 # 业务逻辑模块
└── user-web                     # Web层模块（启动类、控制器）

实操步骤

创建父工程

pom.xml（父项目）：

<?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.example</groupId>
    <artifactId>user-management-parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>   <!-- 父工程打包为pom -->
    <!-- 聚合子模块 -->
    <modules>
        <module>user-common</module>
        <module>user-repository</module>
        <module>user-service</module>
        <module>user-web</module>
    </modules>
    <!-- 统一管理依赖版本 -->
    <properties>
        <java.version>17</java.version>
        <spring-boot.version>3.1.0</spring-boot.version>
    </properties>
    <!-- 依赖管理（只声明版本，不引入） -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
                <version>${spring-boot.version}</version>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-data-jpa</artifactId>
                <version>${spring-boot.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

创建公共模块（user-common）

user-common/pom.xml：

<?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">
    <parent>
        <groupId>com.example</groupId>
        <artifactId>user-management-parent</artifactId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>user-common</artifactId>
    <dependencies>
        <!-- 只放公共依赖，如Lombok、工具类 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>
</project>

User.java（实体类）：

package com.example.common.domain;
import lombok.Data;
@Data
public class User {
    private Long id;
    private String username;
    private String email;
    private Integer age;
}

创建数据访问模块（user-repository）

user-repository/pom.xml：

<?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">
    <parent>
        <groupId>com.example</groupId>
        <artifactId>user-management-parent</artifactId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>user-repository</artifactId>
    <dependencies>
        <!-- 依赖common模块 -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>user-common</artifactId>
            <version>${project.version}</version>
        </dependency>
        <!-- 数据库相关依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
    </dependencies>
</project>

UserRepository.java：

package com.example.repository;
import com.example.common.domain.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    User findByUsername(String username);
}

创建业务逻辑模块（user-service）

user-service/pom.xml：

<?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">
    <parent>
        <groupId>com.example</groupId>
        <artifactId>user-management-parent</artifactId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>user-service</artifactId>
    <dependencies>
        <!-- 依赖repository模块 -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>user-repository</artifactId>
            <version>${project.version}</version>
        </dependency>
        <!-- 事务管理 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-tx</artifactId>
        </dependency>
    </dependencies>
</project>

UserService.java：

package com.example.service;
import com.example.common.domain.User;
import com.example.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;
    @Transactional
    public User createUser(String username, String email) {
        User user = new User();
        user.setUsername(username);
        user.setEmail(email);
        return userRepository.save(user);
    }
    public User findByUsername(String username) {
        return userRepository.findByUsername(username);
    }
}

创建Web层模块（user-web）

user-web/pom.xml：

<?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">
    <parent>
        <groupId>com.example</groupId>
        <artifactId>user-management-parent</artifactId>
        <version>1.0.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>user-web</artifactId>
    <dependencies>
        <!-- 依赖service模块 -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>user-service</artifactId>
            <version>${project.version}</version>
        </dependency>
        <!-- Web相关依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <!-- 只在web模块配置Spring Boot Maven插件 -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

UserController.java：

package com.example.web.controller;
import com.example.common.domain.User;
import com.example.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;
    @PostMapping
    public User createUser(@RequestParam String username, 
                          @RequestParam String email) {
        return userService.createUser(username, email);
    }
    @GetMapping("/{username}")
    public User getUser(@PathVariable String username) {
        return userService.findByUsername(username);
    }
}

Application.java（启动类）：

package com.example.web;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
@SpringBootApplication
// 扫描所有子模块的组件
@ComponentScan(basePackages = "com.example")
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

关键配置说明

模块间依赖关系

user-web → user-service → user-repository → user-common
                      ↘ user-common（间接依赖）

依赖传递规则

compile：默认scope，传递到下游模块
provided：不传递，如Lombok
runtime：运行时需要，如MySQL驱动
test：仅测试时使用

打包配置

父工程：packaging=pom，不生成jar
非web模块：不需要spring-boot-maven-plugin
web模块：需要该插件生成可执行jar

构建与运行

# 1. 清理并编译所有模块
mvn clean compile
# 2. 打包所有模块（web模块生成可执行jar）
mvn clean package
# 3. 仅打包某个模块
mvn clean package -pl user-web -am
# 4. 运行
java -jar user-web/target/user-web-1.0.0.jar

常见问题解决

问题1：找不到其他模块的类

原因：未先安装依赖模块到本地仓库解决：执行 mvn install，不要用compile

问题2：多个模块有相同配置

解决：在父工程pom中统一配置：

<!-- 统一Java版本 -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <source>17</source>
        <target>17</target>
    </configuration>
</plugin>

问题3：启动时扫描不到其他模块的Bean

解决：在web模块的启动类添加：

@SpringBootApplication(scanBasePackages = "com.example")
// 或
@ComponentScan(basePackages = "com.example")

这个案例完整演示了从单模块到多模块的拆分过程，建议你按照步骤实操一遍,理解每个模块的职责和依赖关系。