kotlin-springboot

使用 Kotlin 的 Spring Boot 最佳实践

你的目标是帮助我使用 Kotlin 编写高质量、符合惯用法的 Spring Boot 应用。

项目设置与结构

• 构建工具： 使用 Maven（pom.xml）或 Gradle（build.gradle），并搭配 Kotlin 插件（kotlin-maven-plugin 或 org.jetbrains.kotlin.jvm）。
• Kotlin 插件： 对于 JPA，启用 kotlin-jpa 插件，无需样板代码即可自动将实体类设为 open。
• Starter： 照常使用 Spring Boot starter（例如 spring-boot-starter-web、spring-boot-starter-data-jpa）。
• 包结构： 按功能/领域组织代码（例如 com.example.app.order、com.example.app.user），而不是按分层组织。

依赖注入与组件

• 主构造函数： 始终使用主构造函数进行必需的依赖注入。这是 Kotlin 中最符合惯用法、最简洁的方式。
• 不可变性： 在主构造函数中将依赖声明为 private val。在所有地方优先使用 val 而非 var，以促进不可变性。
• 组件构造型注解： 像在 Java 中一样使用 @Service、@Repository 和 @RestController 注解。

配置

• 外部化配置： 使用 application.yml，因为它具有可读性和层次化结构。
• 类型安全属性： 使用 @ConfigurationProperties 搭配 data class 创建不可变、类型安全的配置对象。
• Profile： 使用 Spring Profile（application-dev.yml、application-prod.yml）管理特定环境的配置。
• 密钥管理： 切勿硬编码密钥。使用环境变量或专用的密钥管理工具，如 HashiCorp Vault 或 AWS Secrets Manager。

Web 层（控制器）

• RESTful API： 设计清晰且一致的 RESTful 端点。
• 使用 Data Class 作为 DTO： 对所有 DTO 使用 Kotlin data class。这会免费提供 equals()、hashCode()、toString() 和 copy()，并促进不可变性。
• 校验： 在 DTO data class 上使用 Java Bean Validation（JSR 380）注解（@Valid、@NotNull、@Size）。
• 错误处理： 使用 @ControllerAdvice 和 @ExceptionHandler 实现全局异常处理器，以提供一致的错误响应。

服务层

• 业务逻辑： 将业务逻辑封装在 @Service 类中。
• 无状态性： 服务应当是无状态的。
• 事务管理： 在服务方法上使用 @Transactional。在 Kotlin 中，这可以应用于类级别或函数级别。

数据层（Repository）

• JPA 实体： 将实体定义为类。请记住它们必须是 open。强烈建议使用 kotlin-jpa 编译器插件来自动处理这一点。
• 空安全： 利用 Kotlin 的空安全（?）在类型层面清晰地定义哪些实体字段是可选的或必需的。
• Spring Data JPA： 通过继承 JpaRepository 或 CrudRepository 使用 Spring Data JPA repository。
• 协程： 对于响应式应用，利用 Spring Boot 在数据层对 Kotlin 协程的支持。

日志

• 伴生对象日志记录器： 声明日志记录器的惯用方式是在伴生对象中进行。

  companion object {
      private val logger = LoggerFactory.getLogger(MyClass::class.java)
  }
  

• 参数化日志： 使用参数化消息（logger.info("Processing user {}...", userId)）以获得更好的性能和清晰度。

测试

• JUnit 5： JUnit 5 是默认选项，可与 Kotlin 无缝协作。
• 惯用的测试库： 如需更流畅、更符合惯用法的测试，可考虑使用 Kotest 进行断言，使用 MockK 进行模拟。它们专为 Kotlin 设计，提供更具表现力的语法。
• 测试切片： 使用测试切片注解，如 @WebMvcTest 或 @DataJpaTest，测试应用的特定部分。
• Testcontainers： 使用 Testcontainers 与真实数据库、消息代理等进行可靠的集成测试。

协程与异步编程

• suspend 函数： 对于非阻塞的异步代码，请在控制器和服务中使用 suspend 函数。Spring Boot 对协程有出色的支持。
• 结构化并发： 使用 coroutineScope 或 supervisorScope 来管理协程的生命周期。