Spring Boot 项目 代码目录结构规范

在Spring Boot项目中，遵循清晰的目录结构规范能提高代码可维护性和团队协作效率。以下是推荐的目录结构规范（基于Maven/Gradle项目）：

标准目录结构

src
├── main
│   ├── java
│   │   └── com
│   │       └── yourcompany
│   │           └── yourproject
│   │               ├── Application.java          # 主启动类
│   │               ├── config                    # 配置类
│   │               ├── controller                # 控制器层
│   │               ├── service                   # 服务层
│   │               │   ├── impl                  # 服务实现
│   │               ├── repository                # 数据访问层（或dao）
│   │               ├── model                     # 实体类（或entity, domain）
│   │               │   ├── entity                # JPA实体
│   │               │   ├── dto                   # 数据传输对象
│   │               │   └── vo                    # 视图对象
│   │               ├── exception                 # 异常处理
│   │               ├── util                     # 工具类
│   │               ├── aspect                    # AOP切面
│   │               └── security                  # 安全模块
│   │
│   └── resources
│       ├── static                   # 静态资源
│       ├── templates                # 模板文件
│       ├── application.yml          # 主配置文件
│       ├── application-dev.yml      # 开发环境配置
│       ├── application-prod.yml     # 生产环境配置
│       └── db
│           ├── migration            # 数据库迁移脚本（Flyway/Liquibase）
│           └── sql                  # 自定义SQL文件
│
└── test                            # 测试代码
    ├── java                        # 测试源码
    └── resources                   # 测试资源

---

关键目录说明

1. 主启动类 (Application.java)

   • 位置：根包下
   • 注解：@SpringBootApplication
   • 示例：

     package com.yourcompany.yourproject;
     @SpringBootApplication
     public class Application {
         public static void main(String[] args) {
             SpringApplication.run(Application.class, args);
         }
     }

2. 控制器层 (controller)

   • 处理HTTP请求，返回响应
   • 注解：@RestController/@Controller
   • 示例：

     @RestController
     @RequestMapping("/api/users")
     public class UserController {
         @Autowired
         private UserService userService;
         
         @GetMapping("/{id}")
         public ResponseEntity<UserDTO> getUser(@PathVariable Long id) {
             // ...
         }
     }

3. 服务层 (service + impl)

   • 接口定义在 service 包
   • 实现在 service/impl 包
   • 注解：@Service
   • 示例：

     // 接口
     public interface UserService {
         UserDTO findUserById(Long id);
     }
     
     // 实现
     @Service
     public class UserServiceImpl implements UserService {
         // 业务逻辑实现
     }

4. 数据访问层 (repository)

   • 数据库操作接口
   • 注解：@Repository (可省略，Spring会自动扫描)
   • 示例：

     public interface UserRepository extends JpaRepository<UserEntity, Long> {
         Optional<UserEntity> findByEmail(String email);
     }

5. 实体模型 (model)

   • entity: JPA实体类（对应数据库表）

     @Entity
     @Table(name = "users")
     public class UserEntity {
         @Id
         @GeneratedValue(strategy = GenerationType.IDENTITY)
         private Long id;
         private String name;
         // getters/setters
     }

   • dto: 数据传输对象（用于API交互）
   • vo: 视图对象（用于前端展示）

6. 配置类 (config)

   • 全局配置（Web、安全、Swagger等）
   • 示例：

     @Configuration
     public class WebConfig implements WebMvcConfigurer {
         // 跨域配置等
     }

7. 异常处理 (exception)

   • 全局异常处理器：

     @ControllerAdvice
     public class GlobalExceptionHandler {
         @ExceptionHandler(ResourceNotFoundException.class)
         public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
             // 返回自定义错误结构
         }
     }

---

最佳实践建议

1. 包命名规范

   • 使用反转域名：com.yourcompany.yourproject
   • 禁止使用保留字（如 default, class）

2. 分层原则

   • 单向依赖：Controller → Service → Repository
   • 禁止跨层调用（如Controller直接访问Repository）

3. 配置管理

   • 主配置：application.yml
   • 环境隔离：application-{env}.yml
   • 敏感数据：使用 spring-cloud-config 或环境变量

4. 测试规范

   • 测试类路径与源码一致（src/test/java 镜像 src/main/java）
   • 使用分层测试：
     • Controller：@WebMvcTest
     • Service：@SpringBootTest（聚焦服务层）
     • Repository：@DataJpaTest

5. 资源文件

   • 静态资源：/static（JS/CSS/图片）
   • 模板文件：/templates（Thymeleaf等）
   • SQL脚本：/db/migration（版本化管理）

6. 多模块项目结构（大型项目）

   your-project
   ├── core-module         # 核心业务
   ├── web-module          # Web接口
   ├── repository-module   # 数据访问
   └── common-module       # 公共工具

---

常见错误规避

1. 避免"上帝类"

   • 单个类不超过500行
   • 单个方法不超过50行

2. 实体类隔离

   • 禁止将JPA实体直接暴露给Controller
   • 使用DTO转换：

     public UserDTO convertToDTO(UserEntity entity) {
         // 使用MapStruct或手动转换
     }

3. 配置集中化

   • 禁止在代码中硬编码配置（如数据库URL）
   • 使用 @Value 或 @ConfigurationProperties 注入

4. 日志规范

   • 使用SLF4J接口：

     private static final Logger log = LoggerFactory.getLogger(YourClass.class);
     log.info("Request received: {}", requestId);

提示：使用 spring-boot-starter-actuator 监控应用状态，结合 springdoc-openapi 自动生成API文档。

遵循此规范可使项目保持高可读性和可扩展性，尤其适用于中大型项目开发。