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 實體暴露給客戶端。
• 驗證： 使用 Java Bean Validation（JSR 380）搭配 DTO 上的註解（@Valid、@NotNull、@Size）來驗證請求負載。
• 錯誤處理： 實作全域例外處理器，使用 @ControllerAdvice 和 @ExceptionHandler 來提供一致的錯誤回應。

Service 層

• 商業邏輯： 將所有商業邏輯封裝在 @Service 類別中。
• 無狀態性： Service 應該是無狀態的。
• 交易管理： 在 Service 方法上使用 @Transactional 來宣告式地管理資料庫交易。在最細緻的必要層級上應用它。

資料層（Repository）

• Spring Data JPA： 透過繼承 JpaRepository 或 CrudRepository 來使用 Spring Data JPA Repository，進行標準的資料庫操作。
• 自訂查詢： 對於複雜查詢，使用 @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 等模擬框架，為 Service 和元件撰寫單元測試。
• 整合測試： 使用 @SpringBootTest 進行載入 Spring 應用程式上下文的整合測試。
• 測試切片： 使用測試切片註解，例如 @WebMvcTest（針對 Controller）或 @DataJpaTest（針對 Repository），來隔離測試應用程式的特定部分。
• Testcontainers： 考慮使用 Testcontainers，搭配真實資料庫、訊息代理等進行可靠的整合測試。

安全性

• Spring Security： 使用 Spring Security 進行身分驗證與授權。
• 密碼編碼： 一律使用強雜湊演算法（如 BCrypt）編碼密碼。
• 輸入清理： 使用 Spring Data JPA 或參數化查詢來防止 SQL 注入。透過適當編碼輸出，防止跨站腳本攻擊（XSS）。