---
name: springboot-patterns
description: Spring Boot 架構模式，涵蓋 REST API 設計、分層服務、資料存取、快取、非同步處理及紀錄。適用於 Java Spring Boot 後端開發。
---

# Spring Boot 開發模式 (Spring Boot Development Patterns)

用於建構具備可擴展性、生產等級服務的 Spring Boot 架構與 API 模式。

## 何時啟用

- 使用 Spring MVC 或 WebFlux 建立 REST API。
- 規劃 Controller → Service → Repository 的分層架構。
- 配置 Spring Data JPA、快取 (Caching) 或非同步處理 (Async)。
- 添加資料驗證 (Validation)、例外處理 (Exception Handling) 或分頁功能。
- 為開發/測試/生產環境設置不同的 Profiles。
- 實作基於事件驅動的模式（使用 Spring Events 或 Kafka）。

## REST API 結構範例

```java
@RestController
@RequestMapping("/api/markets")
@Validated
class MarketController {
  private final MarketService marketService;

  MarketController(MarketService marketService) {
    this.marketService = marketService;
  }

  @GetMapping
  ResponseEntity<Page<MarketResponse>> list(
      @RequestParam(defaultValue = "0") int page,
      @RequestParam(defaultValue = "20") int size) {
    Page<Market> markets = marketService.list(PageRequest.of(page, size));
    return ResponseEntity.ok(markets.map(MarketResponse::from));
  }

  @PostMapping
  ResponseEntity<MarketResponse> create(@Valid @RequestBody CreateMarketRequest request) {
    Market market = marketService.create(request);
    return ResponseEntity.status(HttpStatus.CREATED).body(MarketResponse.from(market));
  }
}
```

## Repository 與 Service 模式

- **Repository**：繼承 `JpaRepository` 並利用 Spring Data JPA 的方法命名約定或 `@Query`。
- **Service**：處理業務邏輯，並使用 `@Transactional` 確保資料一致性。

## 例外處理 (Global Exception Handling)

使用 `@ControllerAdvice` 統一收斂系統異常，並回傳格式化後的錯誤回應 (如 `ResponseEntity<ApiError>`)。

## 快取與非同步處理

- **快取**：在配置類標註 `@EnableCaching`，並在 Service 方法上使用 `@Cacheable` 或 `@CacheEvict`。
- **非同步**：標註 `@EnableAsync`，使用 `@Async` 標註方法並回傳 `CompletableFuture`。

## 紀錄 (SLF4J)

優先使用構造函數注入 Logger 或使用 Lombok 的 `@Slf4j`。確保在關鍵業務節點紀錄階段性資訊，並在 Catch 塊中記錄完整堆疊 (Stack Trace)。

## 速率限制 (Rate Limiting)

使用 Filter 結合 Bucket4j 實作。
**安全性提醒**：若應用部署在反向代理（如 Nginx, AWS ALB）後方，必須配置 `server.forward-headers-strategy` 以正確獲取客戶端真實 IP，避免 Rate Limiter 被偽造的 `X-Forwarded-For` 繞過。

## 生產環境最佳實踐

- **依賴注入**：優先採用構造函數注入 (Constructor Injection)，避免欄位注入 (Field Injection)。
- **資料庫連接池**：根據負載調整 HikariCP 參數。
- **事務管理**：對於純查詢方法，使用 `@Transactional(readOnly = true)`。
- **回應格式**：Spring Boot 3+ 建議啟用 `spring.mvc.problemdetails.enabled=true` 以符合 RFC 7807 標準。
- **可觀察性**：整合 Micrometer、Prometheus 與 OpenTelemetry 進行指標監控與鏈路追蹤。

---

**核心原則**：保持 Controller 輕量、Service 職責明確、Repository 邏輯單純，並將錯誤處理機制中心化。