Java Spring Boot项目目录规范示例

以下是一个典型的 Java Spring Boot 项目目录结构规范示例，结合了分层架构和模块化设计的最佳实践：

text

复制

下载

src/
├── main/
│   ├── java/
│   │   └── com/
│   │       └── example/
│   │           └── myapp/
│   │               ├── MyAppApplication.java          # 主启动类
│   │               │
│   │               ├── config/                        # 配置类
│   │               │   ├── SwaggerConfig.java         # Swagger 配置
│   │               │   ├── SecurityConfig.java        # 安全配置
│   │               │   └── WebMvcConfig.java          # MVC 配置
│   │               │
│   │               ├── controller/                   # 控制器层
│   │               │   ├── UserController.java
│   │               │   └── ProductController.java
│   │               │
│   │               ├── service/                      # 服务层
│   │               │   ├── UserService.java
│   │               │   ├── impl/                     # 服务实现
│   │               │   │   ├── UserServiceImpl.java
│   │               │   │   └── ProductServiceImpl.java
│   │               │
│   │               ├── repository/                   # 数据访问层
│   │               │   ├── UserRepository.java       # JPA 接口
│   │               │   └── ProductRepository.java
│   │               │
│   │               ├── model/                        # 数据模型
│   │               │   ├── entity/                   # 数据库实体
│   │               │   │   ├── User.java
│   │               │   │   └── Product.java
│   │               │   │
│   │               │   ├── dto/                      # DTO 对象
│   │               │   │   ├── request/              # 请求对象
│   │               │   │   │   ├── CreateUserRequest.java
│   │               │   │   │   └── UpdateProductRequest.java
│   │               │   │   └── response/            # 响应对象
│   │               │   │
│   │               │   └── enums/                   # 枚举类
│   │               │
│   │               ├── exception/                    # 异常处理
│   │               │   ├── GlobalExceptionHandler.java
│   │               │   └── CustomException.java
│   │               │
│   │               ├── util/                         # 工具类
│   │               │   ├── DateUtils.java
│   │               │   └── StringUtils.java
│   │               │
│   │               ├── security/                     # 安全模块
│   │               │   ├── JwtUtils.java
│   │               │   └── UserDetailsServiceImpl.java
│   │               │
│   │               └── scheduler/                    # 定时任务
│   │                   └── ReportGenerationScheduler.java
│   │
│   └── resources/
│       ├── static/                                   # 静态资源
│       ├── templates/                               # 模板文件
│       ├── application.yml                          # 主配置文件
│       ├── application-dev.yml                      # 开发环境配置
│       ├── application-prod.yml                     # 生产环境配置
│       └── db/
│           ├── migration/                           # 数据库迁移脚本（Flyway/Liquibase）
│           │   └── V1__init_schema.sql
│           └── data.sql                             # 初始数据
│
└── test/                                            # 测试代码
    └── java/
        └── com/
            └── example/
                └── myapp/
                    ├── controller/
                    │   └── UserControllerTest.java
                    ├── service/
                    │   └── UserServiceTest.java
                    └── integration/                # 集成测试
                        └── UserIntegrationTest.java

核心目录说明：

1. 主启动类

   • 位于根包下，用于启动 Spring Boot 应用

2. 分层结构

   • controller: 处理 HTTP 请求，调用 Service 层

   • service: 业务逻辑层，接口与实现分离

   • repository: 数据访问层（JPA/Hibernate）

   • model: 数据模型定义（DTO/Entity）

3. 配置类

   • 集中管理 Spring 配置（安全、Swagger、数据库等）

4. 异常处理

   • 统一异常处理和自定义异常定义

5. 资源文件

   • application-*.yml: 多环境配置文件

   • db/migration/: 数据库迁移脚本（推荐使用 Flyway）

6. 测试目录

   • 分层测试结构（单元测试/集成测试）

最佳实践建议：

1. 包命名规范

   • 使用全小写字母，避免使用下划线

   • 按功能模块分包（如：com.example.myapp.order）

2. 代码分离原则

   • Controller 保持简洁（仅处理参数校验和响应封装）

   • 业务逻辑集中在 Service 层

   • 数据访问逻辑在 Repository 层

3. DTO 使用规范

   • 使用单独的 DTO 进行接口数据传输

   • 避免直接暴露 Entity 对象给前端

4. 版本控制

   • 数据库迁移脚本使用版本号管理

   • API 版本控制（如：/api/v1/users）

5. 测试规范

   • 测试类命名：被测试类名 + Test 后缀

   • 使用 @SpringBootTest 进行集成测试

   • 使用 @Mock 和 @InjectMocks 进行单元测试

根据项目复杂度可适当调整结构，例如增加以下目录：

• aspects/: AOP 切面

• client/: 外部服务调用客户端

• messaging/: 消息处理（Kafka/RabbitMQ）

• validation/: 自定义校验逻辑