Hibernate 註解定義命名查詢與原生 SQL 映射詳解

前言

Hibernate 允許在實體類別上以註解方式預先定義靜態查詢 (Named Query) 與原生 SQL 查詢 (Named Native Query)，這些查詢在 SessionFactory 建立時即被解析並載入記憶體，全系統可重複使用，提升維護性與效能。

HQL/JPQL 命名查詢 (@NamedQuery)

單一查詢定義

@Entity
@NamedQueries({
    @NamedQuery(name = "query1", query = "select a from A a")
})
public class A { ... }

多查詢與參數綁定

@Entity
@NamedQueries({
    @NamedQuery(name = "query1", query = "select c from A c where c.id = :id"),
    @NamedQuery(name = "query2", query = "select c from C c where c.id = :id")
})
public class A { ... }

進階 Hint 設定

透過 hints 屬性可指定查詢行為：

@NamedQuery(
    name = "query2",
    query = "select c from A c where c.id = ?",
    hints = @QueryHint(name = "timeout", value = "20")
)

常用 Hint 參數：

呼叫方式

Query q = session.getNamedQuery("query1");
q.setParameter("id", 123);
List list = q.list();

原生 SQL 查詢 (@NamedNativeQuery + @SqlResultSetMapping)

基本映射整個實體

@Entity
@NamedNativeQueries({
    @NamedNativeQuery(
        name = "nativesql1",
        query = "select * from b where id > 1",
        resultSetMapping = "sql1mapping"
    )
})
@SqlResultSetMappings({
    @SqlResultSetMapping(
        name = "sql1mapping",
        entities = @EntityResult(entityClass = B.class)
    )
})
public class B { ... }

僅映射特定欄位

使用 fields 屬性指定欄位對應：

@Entity
@NamedNativeQueries({
    @NamedNativeQuery(
        name = "nativesql1",
        query = "select bname from b where id > 1",
        resultSetMapping = "sql1mapping"
    )
})
@SqlResultSetMappings({
    @SqlResultSetMapping(
        name = "sql1mapping",
        entities = @EntityResult(
            entityClass = B.class,
            fields = @FieldResult(name = "bname", column = "bname")
        )
    )
})
public class B { ... }

呼叫與注意事項

Query q = session.getNamedQuery("nativesql1");
List list = q.list();
for (B b : list) {
    System.out.println(b.getBname()); // 正常
    // System.out.println(b.getId()); // 拋出異常：Column 'id1_0_' not found
}