Hibernate原生SQL查詢結果映射到VO的多種實戰方案

場景痛點：原生SQL查詢結果如何優雅映射到值對象

在Hibernate開發中，常遇到需執行原生SQL（如複雜報表查詢、存儲過程調用、跨庫關聯）並將結果映射到非持久化實體（Value Object, VO）的場景。本文系統梳理Hibernate提供的多種映射機制，按「依賴程度」從高到低、靈活度從低到高對比講解，助你根據業務複雜度選擇最優方案。

方案一：構造函數注入（HQL專用，類型安全）

// VO需提供對應參數的構造函數
public class Person {
    private Long id;
    private String name;
    private Long age;
    // 全參構造函數
    public Person(Long id, String name, Long age, Long phone, String address) {...}
    // 部分字段構造函數
    public Person(Long id, String name, Long age) {...}
    // getter/setter省略
}

HQL查詢：

List<Person> list = session.createQuery(
    "select new com.example.Person(id, name, age) from PersonEntity"
).list();

• ✅ 編譯期類型檢查，IDE重構友好
• ❌ 僅支持HQL，不支持原生SQL
• ❌ 字段組合變化需新增構造函數，易導致參數順序衝突（如id,name,age vs id,name,phone）

方案二：addScalar + addEntity（需實體映射存在）

List<Object[]> list = session.createSQLQuery(
    "select id, name, phone from person"
)
.addScalar("id", StandardBasicTypes.LONG)
.addScalar("name", StandardBasicTypes.STRING)
.addScalar("phone", StandardBasicTypes.LONG)
.addEntity(PersonEntity.class) // 需存在實體映射
.list();

• ✅ 支持原生SQL，可精確控制字段類型
• ❌ 強依賴實體映射，不適用於純VO場景
• ❌ 返回Object[]或實體對象，仍需手動轉換為VO

方案三：ResultTransformer + AliasToBean（推薦用於純VO映射）

核心代碼：

List<Person> list = session.createSQLQuery(
    "select id as \"id\", name as \"name\", phone as \"phone\" from person"
)
.addScalar("id", StandardBasicTypes.LONG)
.addScalar("name", StandardBasicTypes.STRING)
.addScalar("phone", StandardBasicTypes.LONG)
.setResultTransformer(Transformers.aliasToBean(Person.class))
.list();

關鍵點：

• SQL別名必須與VO屬性名完全一致（區分大小寫），Oracle查詢結果預設大寫，需顯式別名轉小寫
• VO只需提供無參構造函數與setter/getter，無需構造函數重載
• 完全解耦實體映射，適用於純POJO/DTO場景

提示：若字段較多，可封裝通用工具方法自動生成別名SQL與Scalar定義，減少樣板代碼。

方案四：映射到集合類型（無VO類也能用）

映射到Map<String, Object>

List<Map<String, Object>> list = session.createSQLQuery(
    "select * from person"
)
.setResultTransformer(Transformers.ALIAS_TO_ENTITY_MAP)
.list();
// 每個Map的key為列別名（或列名），value為字段值

映射到List<Object>（按選列順序）

List<List<Object>> list = session.createSQLQuery(
    "select id, name, phone from person"
)
.setResultTransformer(Transformers.TO_LIST)
.list();

• ✅ 零領域模型依賴，極致靈活
• ❌ 丟失語義信息，調用方需約定索引/Key含義，維護成本高
• ⚠️ 僅建議用於極簡單臨時查詢或通用報表導出組件

進階擴展：自定義ResultTransformer

繼承BasicTransformerAdapter實現transformTuple(Object[] tuple, String[] aliases)，可實現：

• 巢狀對象構建（如Order含List<OrderItem>）
• 枚舉/本地日期類型自動轉換
• 計算字段填充

public class NestedVoTransformer extends BasicTransformerAdapter {
    @Override
    public Object transformTuple(Object[] tuple, String[] aliases) {
        // 自定義組裝邏輯
        return buildComplexVo(tuple, aliases);
    }
}

方案選型決策表

最佳實踐總結

1. 優先使用AliasToBean：平衡了靈活度與代碼清晰度，是原生SQL映射VO的標準姿勢。
2. 封裝基礎DAO方法：將addScalar、setResultTransformer等樣板代碼封裝在基類或工具類中，業務代碼只需傳SQL與VO Class。
3. 注意Oracle大寫列名：統一在SQL中使用column as "propertyName"指定小寫別名。
4. 避免濫用Map/List：除非是通用報表組件，業務代碼應面向強類型VO編程。