好的目录结构，是项目成功的一半
前言
在Spring Boot项目开发中，目录结构的选择往往被很多开发者忽视。一个清晰、合理的目录结构不仅能提高代码的可读性和可维护性，还能为团队协作打下坚实的基础。本文将深入探讨两种主流的Spring Boot目录结构设计，并给出实际的选择建议。
为什么目录结构如此重要？
想象一下，当你接手一个陌生项目时，如果打开源代码看到的是杂乱的包结构，你会是什么感受？反之，如果目录结构清晰明了，你能快速定位到想要的代码，开发效率会提升多少？
一个好的目录结构应该具备以下特点：
可读性：一眼就能看出项目的组织方式
可维护性：修改功能时能快速定位相关代码
可扩展性：新增功能时不会破坏现有结构
团队友好：团队成员能达成共识，减少协作成本
方案一：经典分层架构
架构概述
经典分层架构按技术职责划分，将代码分为控制层、业务层、数据访问层等，这是最传统的Spring Boot项目结构。
完整目录结构
src/main/java/com/example/project/
├── ProjectApplication.java # 启动类
│
├── controller/ # 控制器层 - 处理HTTP请求
│ ├── UserController.java
│ ├── OrderController.java
│ └── ProductController.java
│
├── service/ # 业务逻辑层
│ ├── UserService.java # 接口
│ ├── impl/
│ │ └── UserServiceImpl.java # 实现类
│ ├── OrderService.java
│ └── ProductService.java
│
├── repository/ # 数据访问层
│ ├── UserRepository.java
│ ├── OrderRepository.java
│ └── ProductRepository.java
│
├── entity/ # 实体类（与数据库对应）
│ ├── User.java
│ ├── Order.java
│ └── Product.java
│
├── dto/ # 数据传输对象
│ ├── request/
│ │ ├── UserLoginRequest.java
│ │ └── CreateOrderRequest.java
│ └── response/
│ ├── UserInfoResponse.java
│ └── OrderDetailResponse.java
│
├── vo/ # 视图对象
│ └── PageVO.java
│
├── config/ # 配置类
│ ├── RedisConfig.java
│ ├── WebMvcConfig.java
│ └── SecurityConfig.java
│
├── common/ # 公共组件
│ ├── result/
│ │ ├── Result.java # 统一返回结果
│ │ └── ResultCode.java # 状态码枚举
│ ├── exception/
│ │ ├── BusinessException.java
│ │ └── GlobalExceptionHandler.java
│ └── utils/
│ ├── JwtUtils.java
│ └── RedisUtils.java
│
├── interceptor/ # 拦截器
│ └── AuthInterceptor.java
│
├── aspect/ # AOP切面
│ └── LogAspect.java
│
├── task/ # 定时任务
│ └── ScheduledTasks.java
│
└── enums/ # 枚举类
├── OrderStatus.java
└── UserRole.java
src/main/resources/
├── application.yml # 主配置文件
├── application-dev.yml # 开发环境
├── application-prod.yml # 生产环境
├── mapper/ # MyBatis映射文件
│ └── UserMapper.xml
├── db/
│ └── migration/ # 数据库迁移脚本
└── static/ # 静态资源
└── templates/ # 模板文件
核心包说明
优点分析
✅ 职责清晰：每一层都有明确的职责，代码边界清晰
✅ 依赖单向：严格遵循controller → service → repository的调用方向
✅ 易于理解：新人上手快，学习成本低
✅ 测试友好：可以轻松对每一层进行单元测试
缺点分析
❌ 业务分散：同一个业务功能的代码分散在不同包中
❌ 包膨胀：随着业务增长，controller和service包会变得非常庞大
❌ 修改成本高：修改一个功能需要跨多个包进行操作
方案二：模块化架构
架构概述
模块化架构按业务领域划分，将相关功能聚合在一起，每个模块内部再按层次组织。这种结构更适合复杂业务场景。
完整目录结构
src/main/java/com/example/project/
├── ProjectApplication.java
│
├── user/ # 用户模块
│ ├── controller/
│ │ ├── UserController.java
│ │ └── UserAuthController.java
│ ├── service/
│ │ ├── UserService.java
│ │ └── impl/
│ │ └── UserServiceImpl.java
│ ├── repository/
│ │ └── UserRepository.java
│ ├── entity/
│ │ └── User.java
│ ├── dto/
│ │ ├── UserRegisterDTO.java
│ │ └── UserProfileDTO.java
│ ├── vo/
│ │ └── UserVO.java
│ ├── mapper/
│ │ └── UserExtMapper.java
│ └── event/
│ ├── UserCreatedEvent.java
│ └── UserEventListener.java
│
├── order/ # 订单模块
│ ├── controller/
│ │ └── OrderController.java
│ ├── service/
│ │ ├── OrderService.java
│ │ ├── OrderStateMachine.java
│ │ └── impl/
│ │ └── OrderServiceImpl.java
│ ├── repository/
│ │ └── OrderRepository.java
│ ├── entity/
│ │ ├── Order.java
│ │ └── OrderItem.java
│ ├── dto/
│ │ ├── CreateOrderDTO.java
│ │ └── OrderQueryDTO.java
│ ├── vo/
│ │ └── OrderVO.java
│ └── job/
│ └── OrderTimeoutJob.java
│
├── product/ # 商品模块
│ ├── controller/
│ │ └── ProductController.java
│ ├── service/
│ │ └── ProductService.java
│ ├── repository/
│ │ └── ProductRepository.java
│ ├── entity/
│ │ └── Product.java
│ ├── dto/
│ │ └── ProductDTO.java
│ └── cache/
│ └── ProductCacheManager.java
│
├── common/ # 公共模块
│ ├── config/
│ │ ├── SwaggerConfig.java
│ │ ├── RedisConfig.java
│ │ └── WebConfig.java
│ ├── result/
│ │ ├── Result.java
│ │ └── ResultCode.java
│ ├── exception/
│ │ ├── BusinessException.java
│ │ └── GlobalExceptionHandler.java
│ ├── utils/
│ │ ├── JwtUtil.java
│ │ └── DateUtil.java
│ └── annotation/
│ ├── RequiresPermission.java
│ └── LogExecutionTime.java
│
├── infrastructure/ # 基础设施层
│ ├── datasource/
│ │ ├── DataSourceConfig.java
│ │ └── MybatisPlusConfig.java
│ ├── cache/
│ │ └── RedisConfig.java
│ ├── mq/
│ │ ├── RabbitMQConfig.java
│ │ └── MessageProducer.java
│ └── client/
│ ├── PaymentClient.java
│ └── NotificationClient.java
│
└── shared/ # 共享类型
├── enums/
│ ├── OrderStatus.java
│ └── UserRole.java
└── constants/
├── RedisKeys.java
└── ApiConstants.java
src/main/resources/
├── application.yml
├── application-dev.yml
├── application-prod.yml
├── db/
│ ├── migration/
│ │ ├── V1__create_user_table.sql
│ │ ├── V2__create_order_table.sql
│ │ └── V3__create_product_table.sql
│ └── seed/
│ └── init_data.sql
├── mapper/ # MyBatis映射文件
│ ├── user/
│ │ └── UserMapper.xml
│ ├── order/
│ │ └── OrderMapper.xml
│ └── product/
│ └── ProductMapper.xml
└── static/
└── templates/
模块职责说明
优点分析
✅ 高内聚低耦合：业务相关代码聚合在一起，模块间依赖清晰
✅ 团队协作友好：不同团队可以负责不同模块，减少代码冲突
✅ 微服务就绪：模块可以轻松拆分为独立的微服务
✅ 代码复用：通过common和shared模块实现代码复用
缺点分析
❌ 初期复杂度高：需要良好的模块划分设计
❌ 模块间通信成本：模块间调用需要明确接口定义
❌ 可能产生重复代码：需要在common层做好抽象
两种方案对比
实际选择建议
选择方案一的场景
🚀 创业项目，需要快速验证想法
📝 简单的CRUD应用
👥 团队规模较小，技术栈统一
🎯 项目生命周期短，不需要长期维护
📚 学习项目，用于理解Spring Boot基础
选择方案二的场景
🏢 企业级应用，业务逻辑复杂
👨👩👧👦 团队规模较大，多人协作
🔄 计划未来拆分为微服务
📈 项目需要长期迭代和维护
🎨 需要支持多团队并行开发
实战技巧
1. 模块间通信设计
当采用模块化架构时，模块间的通信需要特别注意。推荐使用：
// 定义清晰的接口
public interface UserClient {
UserInfo getUserById(Long userId);
}
// 在infrastructure层实现
@Component
public class UserClientImpl implements UserClient {
private final UserRepository userRepository;
@Override
public UserInfo getUserById(Long userId) {
// 实现逻辑
}
}
2. 公共代码的抽取原则
将公共代码放入common模块时，遵循以下原则：
三处以上使用：代码在三个以上模块中使用时考虑抽取
无业务依赖：公共代码不应依赖具体业务模块
稳定不变：接口定义后尽量保持稳定
3. 资源文件的组织
# application.yml
spring:
profiles:
active: dev
datasource:
# 配置信息
建议将配置文件按环境拆分：
application.yml- 公共配置application-dev.yml- 开发环境application-prod.yml- 生产环境
总结
选择目录结构没有绝对的正确答案，关键在于是否符合项目实际情况。我个人的建议是：
中小型项目：从方案一开始，保持简单
成长型项目：随着业务增长，逐步向方案二演进
大型项目：直接采用方案二，做好模块划分
记住：好的目录结构不是一成不变的，而是随着项目发展不断演进的。
写在最后
目录结构只是代码组织的一部分，真正重要的是团队能够达成共识并保持一致。无论选择哪种方案，都建议在项目初期就确定下来，并在团队内部形成文档规范。