JPA/Hibernate 模式
用於 Spring Boot 中的資料建模、Repository 與效能調校。
啟用時機
- 設計 JPA 實體與資料表對映
- 定義關聯（@OneToMany、@ManyToOne、@ManyToMany）
- 最佳化查詢（N+1 預防、擷取策略、投影）
- 設定交易、審計或軟刪除
- 配置分頁、排序或自訂 Repository 方法
- 調校連線池（HikariCP）或第二層快取
實體設計
@Entity
@Table(name = "markets", indexes = {
@Index(name = "idx_markets_slug", columnList = "slug", unique = true)
})
@EntityListeners(AuditingEntityListener.class)
public class MarketEntity {
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, length = 200)
private String name;
@Column(nullable = false, unique = true, length = 120)
private String slug;
@Enumerated(EnumType.STRING)
private MarketStatus status = MarketStatus.ACTIVE;
@CreatedDate private Instant createdAt;
@LastModifiedDate private Instant updatedAt;
}
啟用審計功能：
@Configuration
@EnableJpaAuditing
class JpaConfig {}
關聯與 N+1 預防
@OneToMany(mappedBy = "market", cascade = CascadeType.ALL, orphanRemoval = true)
private List<PositionEntity> positions = new ArrayList<>();
- 預設使用延遲載入；需要時在查詢中使用
JOIN FETCH - 避免在集合上使用
EAGER；對讀取路徑使用 DTO 投影
@Query("select m from MarketEntity m left join fetch m.positions where m.id = :id")
Optional<MarketEntity> findWithPositions(@Param("id") Long id);
Repository 模式
public interface MarketRepository extends JpaRepository<MarketEntity, Long> {
Optional<MarketEntity> findBySlug(String slug);
@Query("select m from MarketEntity m where m.status = :status")
Page<MarketEntity> findByStatus(@Param("status") MarketStatus status, Pageable pageable);
}
- 使用投影進行輕量查詢：
public interface MarketSummary {
Long getId();
String getName();
MarketStatus getStatus();
}
Page<MarketSummary> findAllBy(Pageable pageable);
交易
- 在 Service 方法上標註
@Transactional - 對讀取路徑使用
@Transactional(readOnly = true)以進行最佳化 - 謹慎選擇傳播行為；避免長時間交易
@Transactional
public Market updateStatus(Long id, MarketStatus status) {
MarketEntity entity = repo.findById(id)
.orElseThrow(() -> new EntityNotFoundException("Market"));
entity.setStatus(status);
return Market.from(entity);
}
分頁
PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
Page<MarketEntity> markets = repo.findByStatus(MarketStatus.ACTIVE, page);
對於游標式分頁，可在 JPQL 中加入 id > :lastId 並搭配排序。
索引與效能
- 為常用篩選條件（
status、slug、外鍵）增加索引 - 使用符合查詢模式的複合索引（
status, created_at） - 避免
select *；只投影需要的欄位 - 使用
saveAll與hibernate.jdbc.batch_size進行批次寫入
連線池（HikariCP）
建議配置：
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.validation-timeout=5000
針對 PostgreSQL LOB 處理，請加入：
spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true
快取
- 第一級快取是每個 EntityManager 專屬；避免跨交易保留實體
- 對於讀取密集的實體，請謹慎考慮第二級快取；務必驗證驅逐策略
遷移
- 使用 Flyway 或 Liquibase；絕不在生產環境中依賴 Hibernate 自動 DDL
- 保持遷移的冪等性與增量性；避免未經計畫就移除欄位
測試資料存取
- 建議使用
@DataJpaTest搭配 Testcontainers 以模擬生產環境 - 透過日誌驗證 SQL 效率：設定
logging.level.org.hibernate.SQL=DEBUG以及logging.level.org.hibernate.orm.jdbc.bind=TRACE以檢視參數值
切記：保持實體精簡、查詢明確、交易簡短。使用擷取策略與投影預防 N+1，並根據讀寫路徑建立索引。