java-springboot

Spring Boot 最佳实践

你的目标是帮助我遵循既定的最佳实践，编写高质量的 Spring Boot 应用。

项目设置与结构

• 构建工具： 使用 Maven（pom.xml）或 Gradle（build.gradle）进行依赖管理。
• Starter： 使用 Spring Boot starter（例如 spring-boot-starter-web、spring-boot-starter-data-jpa）来简化依赖管理。
• 包结构： 按功能/领域（例如 com.example.app.order、com.example.app.user）组织代码，而不是按层（例如 com.example.app.controller、com.example.app.service）组织。

依赖注入与组件

• 构造器注入： 对必需依赖始终使用基于构造器的注入。这使组件更易于测试，并使依赖关系更加明确。
• 不可变性： 将依赖字段声明为 private final。
• 组件构造型： 适当使用 @Component、@Service、@Repository 和 @Controller/@RestController 注解来定义 bean。

配置

• 外部化配置： 使用 application.yml（或 application.properties）进行配置。YAML 通常因其可读性和层次化结构而更受青睐。
• 类型安全属性： 使用 @ConfigurationProperties 将配置绑定到强类型的 Java 对象。
• Profile： 使用 Spring Profile（application-dev.yml、application-prod.yml）管理特定环境的配置。
• 密钥管理： 不要硬编码密钥。使用环境变量，或使用 HashiCorp Vault、AWS Secrets Manager 等专用密钥管理工具。

Web 层（Controller）

• RESTful API： 设计清晰且一致的 RESTful 端点。
• DTO（数据传输对象）： 使用 DTO 在 API 层暴露和消费数据。不要将 JPA 实体直接暴露给客户端。
• 校验： 在 DTO 上使用 Java Bean Validation（JSR 380）及注解（@Valid、@NotNull、@Size）来校验请求负载。
• 错误处理： 使用 @ControllerAdvice 和 @ExceptionHandler 实现全局异常处理器，以提供一致的错误响应。

服务层

• 业务逻辑： 将所有业务逻辑封装在 @Service 类中。
• 无状态性： 服务应无状态。
• 事务管理： 在服务方法上使用 @Transactional 以声明式方式管理数据库事务。在必要的范围内尽可能细粒度地应用它。

数据层（Repository）

• Spring Data JPA： 通过扩展 JpaRepository 或 CrudRepository 使用 Spring Data JPA 仓库，以执行标准数据库操作。
• 自定义查询： 对于复杂查询，使用 @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 等 mocking 框架为服务和组件编写单元测试。
• 集成测试： 使用 @SpringBootTest 进行加载 Spring 应用上下文的集成测试。
• 测试切片： 使用 @WebMvcTest（用于 Controller）或 @DataJpaTest（用于 Repository）等测试切片注解，以隔离方式测试应用的特定部分。
• Testcontainers： 考虑使用 Testcontainers 与真实数据库、消息代理等进行可靠的集成测试。

安全

• Spring Security： 使用 Spring Security 进行身份验证和授权。
• 密码编码： 始终使用 BCrypt 等强哈希算法对密码进行编码。
• 输入清理： 通过使用 Spring Data JPA 或参数化查询防止 SQL 注入。通过正确编码输出防止跨站脚本攻击（XSS）。