Spring Data JPA 批量更新性能優化：EntityManager 周期管理與 @PersistenceContext

問題現場

• 循環 userRepository.save(user) 更新 6000 條 → **4-5 分鐘**，極慢。
• 改用 EntityManager.merge() + 手動 flush()/clear() → **空指針異常 (NPE)**：em 為 null。

NPE 根因：缺少 @PersistenceContext 注入

// ❌ 錯誤：私有字段無注解，Spring 不會注入
private EntityManager em;

// ✅ 正確：標準 JPA 注入方式
@PersistenceContext
private EntityManager em;

完整優化版 Service 代碼

@Service
@Transactional
public class UserServiceImpl implements UserService {

    @PersistenceContext
    private EntityManager em;

    @Override
    public void updateUsers(List<User> users) {
        int batchSize = 30; // 與 Hibernate jdbc.batch_size 一致
        for (int i = 0; i < users.size(); i++) {
            em.merge(users.get(i)); // 合併托管狀態

            // 定期 flush + clear，釋放一級緩存，防止 OOM
            if (i % batchSize == 0 && i > 0) {
                em.flush();   // 同步到數據庫
                em.clear();   // 清空持久化上下文
            }
        }
        // 最後剩餘數據 flush
        em.flush();
    }
}

關鍵參數調優（application.yml）

spring:
  jpa:
    properties:
      hibernate:
        jdbc:
          batch_size: 30          # 批量發送 SQL 數量
          batch_versioned_data: true  # 允許帶版本號實體批量更新
        order_inserts: true       # 按實體類型排序 INSERT，提升批次合並率
        order_updates: true       # 同上針對 UPDATE
        generate_statistics: false # 生產關閉統計，提升性能

為什麼 merge() 比 save() 快？

進階：原生批量更新 SQL（極致性能）

@Modifying
@Query("UPDATE User u SET u.name = :name WHERE u.id IN :ids")
int batchUpdateName(@Param("name") String name, @Param("ids") List<Long> ids);

• **單條 SQL 完成所有更新**，性能最高。
• **缺點**：繞過 JPA 生命周期（實體监听器、緩存、樂觀鎖失效），需謹慎使用。

避坑清單

• ❌ @Autowired EntityManager → **錯誤**，需 @PersistenceContext。
• ❌ 忘記 em.clear() → 一級緩存累積導致 **OOM**。
• ❌ 批次太大（>100） → 數據庫鎖升級、事務日誌膨脹，反而變慢。
• ❌ 實體無 @Version 卻開啟 batch_versioned_data → 異常。

總結

1. 注入 EntityManager **必加 @PersistenceContext**。
2. 批量更新核心模式：**merge → 計數 → flush + clear**。
3. 配置 hibernate.jdbc.batch_size 與代碼中 batchSize 保持一致。
4. 極致性能場景可用 @Modifying @Query 直寫 SQL，但需權衡 JPA 特性損失。

從「幾分鐘」到「幾秒」，只差一個 @PersistenceContext 和正確的批量提交節奏。