Hibernate 3.2 升級遷移指南：API 變更、類型兼容與新特性

核心破壞性變更：聚合函數返回類型統一為 Long

Hibernate 3.2 為兼容 JPA 規範，將 count()、sum() 等聚合函數的唯一返回值從 Integer 改為 Long。直接升級會導致 ClassCastException。

解決方案一：註冊經典函數（保持舊行為）

Configuration classicCfg = new Configuration();
classicCfg.addSqlFunction("count", new ClassicCountFunction());
classicCfg.addSqlFunction("avg", new ClassicAvgFunction());
classicCfg.addSqlFunction("sum", new ClassicSumFunction());
SessionFactory classicSf = classicCfg.buildSessionFactory();

解決方案二：代碼層面兼容寫法（推薦）

// ❌ 舊代碼：升級後拋 ClassCastException
int count = ((Integer) q.uniqueResult()).intValue();

// ✅ 新代碼：兼容 3.0/3.1/3.2 所有版本
int count = ((Number) q.uniqueResult()).intValue();
// Number 是 Integer/Long/Double 等的父類，安全轉型

其他關鍵變更清單

新特性：ResultTransformer 靈活映射

AliasToBean 映射 DTO

// 返回非受管的 CatDTO 列表
List<CatDTO> dtos = sess.createSQLQuery(
    "SELECT NAME, BIRTHDATE FROM CATS"
).setResultTransformer(Transformers.aliasToBean(CatDTO.class))
 .list();

// 或使用顯式構造器
.setResultTransformer(new AliasToBeanResultTransformer(CatDTO.class))

注意：每個查詢列必須對應 DTO 屬性名，建議在 SQL 中用別名 SELECT name AS name, birthdate AS birthDate。

AliasToMap 返回 Map 列表

List<Map> results = s.createQuery(
    "select e.student.name as studentName, " +
    "e.course.description as courseDescription " +
    "from Enrolment as e"
).setResultTransformer(Transformers.ALIAS_TO_MAP)
 .list();

for (Map row : results) {
    String name = (String) row.get("studentName");
    String desc = (String) row.get("courseDescription");
}

適用於 Criteria、HQL、Native SQL，避免 Object[] 索引訪問的脆弱性。

setResultTransformer vs addEntity 關鍵差異

• Transformer：支援任意列選擇 SELECT a, b FROM ...
• addEntity：要求 SELECT * 或 SELECT {a.*}, {b.*} FROM a, b ... 完整實體列

遷移檢查清單

1. 全局搜尋 (Integer) q.uniqueResult() 替換為 (Number) q.uniqueResult()
2. 升級 ehcache-1.2.x.jar 並更新配置文件結構
3. 清理 SQL 查詢中冗餘的 addScalar() 調用
4. 利用 executeUpdate() 簡化批量更新/刪除代碼
5. 評估引入 ResultTransformer 替換手動 Object[] 映射邏輯
6. 運行完整測試套件，重點驗證報表、統計類聚合查詢

總結

Hibernate 3.2 的核心變更集中在 JPA 兼容性（返回類型統一）與 API 現代化（ResultTransformer、簡化標量查詢）。採用 Number 統一轉型策略可零成本兼容舊版本，新特性則能顯著減少樣板代碼。建議在升級前備份配置與依賴，分模塊驗證核心查詢邏輯。