kotlin-springboot

Spring Boot 搭配 Kotlin 最佳實務

你的目標是協助我使用 Kotlin 撰寫高品質、慣用寫法的 Spring Boot 應用程式。

專案設定與結構

• 建置工具： 使用 Maven（pom.xml）或 Gradle（build.gradle）搭配 Kotlin 插件（kotlin-maven-plugin 或 org.jetbrains.kotlin.jvm）。
• Kotlin 插件： 若使用 JPA，啟用 kotlin-jpa 插件，讓實體類別自動成為 open，無需額外樣板程式碼。
• Starters： 照常使用 Spring Boot starters（例如 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 來建立不可變、型別安全的設定物件。
• 設定檔： 使用 Spring Profiles（application-dev.yml、application-prod.yml）管理不同環境的設定。
• 機密管理： 切勿將機密寫死在程式碼中。應使用環境變數或專用的機密管理工具，例如 HashiCorp Vault 或 AWS Secrets Manager。

Web 層（控制器）

• RESTful API： 設計清晰且一致的 RESTful 端點。
• DTO 的資料類別： 對所有 DTO 使用 Kotlin data class。這會自動提供 equals()、hashCode()、toString() 和 copy()，並促進不可變性。
• 驗證： 在 DTO 資料類別上使用 Java Bean Validation（JSR 380）的註解（@Valid、@NotNull、@Size）。
• 錯誤處理： 使用 @ControllerAdvice 和 @ExceptionHandler 實作全域例外處理器，以提供一致的錯誤回應。

服務層

• 商業邏輯： 將商業邏輯封裝在 @Service 類別中。
• 無狀態： 服務應為無狀態。
• 交易管理： 在服務方法上使用 @Transactional。在 Kotlin 中，可應用於類別或函式層級。

資料層（儲存庫）

• JPA 實體： 將實體定義為類別。請注意它們必須是 open。強烈建議使用 kotlin-jpa 編譯器插件來自動處理此問題。
• 空值安全： 利用 Kotlin 的空值安全（?）在型別層級清楚定義實體欄位為可選或必填。
• Spring Data JPA： 透過繼承 JpaRepository 或 CrudRepository 來使用 Spring Data JPA 儲存庫。
• 協程： 對於反應式應用程式，可利用 Spring Boot 對資料層中 Kotlin 協程的支援。

日誌記錄

• 伴生物件的 Logger： 宣告 logger 的慣用方式是在伴生物件中。

  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 來管理協程的生命週期。