---
name: java-springboot
description: '获取 Spring Boot 应用开发的最佳实践。'
---

# Spring Boot 最佳实践

你的目标是通过遵循成熟的最佳实践，帮助我编写高质量的 Spring Boot 应用程序。

## 项目搭建与结构

- **构建工具：** 使用 Maven（`pom.xml`）或 Gradle（`build.gradle`）进行依赖管理。
- **起步依赖：** 采用 Spring Boot starter（如：`spring-boot-starter-web`、`spring-boot-starter-data-jpa`）以简化依赖配置。
- **包结构：** 按照功能或领域划分包结构（例如：`com.example.app.order`、`com.example.app.user`），避免按分层（如 `controller`、`service`）组织。

## 依赖注入与组件

- **构造器注入：** 必须依赖项全部采用构造器注入，这让组件更易于测试，并使依赖关系显式可见。
- **不可变性：** 依赖字段声明为 `private final`。
- **组件注解：** 合理使用 `@Component`、`@Service`、`@Repository`、`@Controller`/`@RestController` 注解定义 Spring Bean。

## 配置管理

- **外部化配置：** 使用 `application.yml`（或 `application.properties`）管理配置。推荐 YAML，因其层级式结构更清晰易读。
- **类型安全配置：** 使用 `@ConfigurationProperties` 将配置绑定到强类型 Java 对象上。
- **多环境配置：** 利用 Spring Profiles（如 `application-dev.yml`、`application-prod.yml`）管理不同环境下的配置。
- **密钥管理：** 禁止硬编码敏感信息。应使用环境变量或专用的密钥管理工具（如 HashiCorp Vault、AWS Secrets Manager）。

## Web 层（控制器）

- **RESTful API：** 设计清晰、统一、REST 风格的接口。
- **DTO（数据传输对象）：** 使用 DTO 进行接口层数据输入与输出，禁止直接暴露 JPA 实体对象。
- **参数校验：** 在 DTO 类上使用 Java Bean Validation（JSR 380）注解（如 `@Valid`、`@NotNull`、`@Size`）校验请求参数。
- **异常处理：** 通过 `@ControllerAdvice` 和 `@ExceptionHandler` 实现全局异常处理，保证异常响应风格统一。

## 服务层

- **业务逻辑：** 所有业务逻辑应封装在 `@Service` 类中。
- **无状态性：** 服务应设计为无状态模式。
- **事务管理：** 在服务方法上使用 `@Transactional` 声明式管理数据库事务，并尽量细化事务的作用范围。

## 数据访问层（仓库）

- **Spring Data JPA：** 标准的数据访问操作可通过继承 `JpaRepository` 或 `CrudRepository` 实现。
- **自定义查询：** 复杂查询可使用 `@Query` 注解或 JPA Criteria API 实现。
- **投影：** 通过 DTO 投影只获取所需字段，避免提取无关数据。

## 日志

- **SLF4J：** 推荐使用 SLF4J API 作为日志门面。
- **Logger 声明：** `private static final Logger logger = LoggerFactory.getLogger(MyClass.class);`
- **参数化日志：** 使用参数化日志（如 `logger.info("Processing user {}...", userId);`）代替字符串拼接，提高性能。

## 测试

- **单元测试：** 使用 JUnit 5 和 Mockito 等 mock 框架为服务和组件编写单元测试。
- **集成测试：** 使用 `@SpringBootTest` 加载 Spring 上下文进行集成测试。
- **测试切片：** 采用 `@WebMvcTest`（针对控制器）、`@DataJpaTest`（针对仓库）等测试切片注解，仅测试应用部分内容，提高测试效率。
- **Testcontainers：** 推荐使用 Testcontainers 结合真实数据库、中间件等进行高可靠性的集成测试。

## 安全性

- **Spring Security：** 使用 Spring Security 完成认证与授权。
- **密码加密：** 必须采用强加密算法（如 BCrypt）加密密码。
- **输入校验：** 用 Spring Data JPA 或参数化查询方式防护 SQL 注入攻击；通过输出编码防护 XSS（跨站脚本攻击）。