Spring Boot：模块化实战 - 保持清晰架构

有过 Java Web 开发经验的同学，大多都有这样一个痛点：项目刚开始写得挺清爽，Controller、Service、Mapper 各司其职。结果功能一多、模块一杂，代码就开始复杂了：

不同业务之间相互依赖，改一个地方牵一发而动全身；
同一套依赖在每个模块都引入，打包体积暴涨；
想做微服务又不敢拆，担心拆了之后部署复杂、数据不一致；

这些问题的根源，其实在于缺乏模块化思维。 Spring Boot 的单体项目开发虽然高效，但当代码规模上升到几万行甚至十几万行时，模块界限不清就会变成生产力的天敌。

一、什么是模块化？

模块化（Modularization）是一种把复杂系统拆分成相互独立、低耦合模块的设计方式。每个模块都有清晰的边界和职责，像是一个个积木块，既能独立开发，又能灵活组合。

在 Spring Boot 项目中，模块化通常意味着：

将单体项目拆成若干业务子模块；
每个模块有独立的包结构和依赖；
公共功能抽取成独立核心模块或基础模块；
模块间通过接口或事件机制通信；
最终由一个统一的主应用模块来启动加载。

这种架构的目标是：保持单体的部署简单性，同时具备微服务的扩展性与清晰性。

二、模块化架构的常见分层设计

以一个典型的企业级系统为例，比如"公寓租赁管理系统"，我们可以按职责拆分模块：

在 Maven 工程结构中，它通常表现为父子模块的关系：

apartment-platform

├── apartment-common

├── apartment-framework

├── apartment-user

├── apartment-room

├── apartment-order

└── apartment-application

顶层父工程 apartment-platform 主要管理依赖与版本，而每个子模块之间则各自独立、职责分明。

三、模块化项目的依赖设计

模块化项目通常采用 Maven 多模块架构（multi-module）。这种方式下，依赖管理尤为关键。

1. 父工程 pom.xml

父模块主要定义统一的依赖版本，子模块继承即可：

dart 复制代码

<modules>
    <module>apartment-common</module>
    <module>apartment-framework</module>
    <module>apartment-user</module>
    <module>apartment-room</module>
    <module>apartment-order</module>
    <module>apartment-application</module>
</modules>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2. 子模块 pom.xml

例如在 apartment-user 模块：

dart 复制代码

<parent>
    <groupId>com.procode</groupId>
    <artifactId>apartment-platform</artifactId>
    <version>1.0.0</version>
</parent>

<dependencies>
    <dependency>
        <groupId>com.procode</groupId>
        <artifactId>apartment-common</artifactId>
    </dependency>
</dependencies>

这样所有模块的依赖都可统一管理，避免版本冲突与重复定义。

四、模块之间如何通信？（3种方式）

1. 直接依赖调用（最简单）

适用于强耦合的业务，比如 order 模块依赖 room 模块：

dart 复制代码

@Service
public class OrderService {
    @Autowired
    private RoomService roomService;
}

但这种方式仅限于单体架构内部使用，一旦要拆分微服务就不适用了。

2. 接口层抽象（解耦方式）

可以通过定义接口在 common 模块中声明，不同业务模块各自实现，主模块通过注入实现类完成调用。

dart 复制代码

public interface RentCalculator {
    BigDecimal calculate(Room room);
}

room-service 模块实现接口，order-service 模块只依赖接口而非实现。

3. 事件驱动机制（推荐）

通过 Spring 的 ApplicationEventPublisher 实现模块解耦：

java 复制代码

@Component
public class RoomCreatedEvent extends ApplicationEvent {
    private Long roomId;
    // ...
}

publisher.publishEvent(new RoomCreatedEvent(roomId));

这样不同模块之间通过事件机制感知变更，无需直接依赖。

五、模块化项目中的"公共层"设计

模块化最大的问题之一是"公共代码怎么放"。常见几类内容可以统一放入 common 模块：

通用工具类（日期、字符串、Bean拷贝等）
全局异常类与业务异常基类
常量类（比如状态码、业务类型枚举）
通用响应对象（Result、ResponseData）
公共注解、自定义 AOP 切面
公共配置（Jackson、Swagger、MyBatis-Plus等）

例如通用响应类：

java 复制代码

@Data
publicclass ApiResponse<T> {
    private Integer code;
    private String message;
    private T data;

    publicstatic <T> ApiResponse<T> success(T data) {
        ApiResponse<T> result = new ApiResponse<>();
        result.setCode(200);
        result.setMessage("OK");
        result.setData(data);
        return result;
    }
}

只需在各模块中统一引入 apartment-common 依赖即可。

六、模块化与自动配置：让模块"自启动"

Spring Boot 的强大之处就在于"约定大于配置"。模块化架构同样可以借助自动配置机制，让模块按需启用。

在每个模块中编写自动配置类：

java 复制代码

@Configuration
@ConditionalOnClass(UserService.class)
public class UserAutoConfiguration {
    @Bean
    public UserService userService() {
        return new UserServiceImpl();
    }
}

然后在 resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件中注册：

com.procode.user.config.UserAutoConfiguration

主模块在启动时会自动扫描并加载这些配置，实现模块级的"按需装配"，无需手动引入 Bean。

七、模块化中的常见问题与解决方案

Bean 重复注入问题多模块加载相同包路径时，可能出现 Bean 重名冲突。可通过 @Primary 指定优先级，或调整扫描路径解决。

模块循环依赖典型如 A 模块依赖 B 模块，B 又依赖 A。应将交叉部分抽取到公共接口模块，或使用事件机制解耦。

打包部署体积大多模块项目容易产生冗余依赖，可使用 spring-boot-maven-plugin 的 exclude 属性过滤。

统一配置管理难使用父模块统一管理版本和插件配置，减少维护成本。

总结

当系统越写越复杂，真正拖垮我们的从来不是业务本身，而是结构混乱。模块化让你有能力重新组织项目，让它可生长、可维护、可重构。

模块化不是为"架构而架构"，而是让代码的生命更长。它让你面对一个几万行的项目时，仍能一眼看清全貌；让版本演进时，稳定的模块无需动，新增功能轻松插拔。