Hibernate 命名查詢完全指南：四種定義方式與最佳實踐詳解

什麼是命名查詢？

在映射文件（.hbm.xml）中預定義 HQL 或 SQL 查詢語句，賦予名稱，業務代碼通過名稱調用，實現查詢邏輯與業務代碼分離，提升可維護性與可讀性。

四種定義方式對比

方式一：映射文件根節點下定義（推薦）

<hibernate-mapping>
  <class name="com.test.bean.Student" table="student" catalog="users">
    <id name="id"><generator class="identity"/></id>
    <property name="name"/>
    <property name="age"/>
    <property name="sex"/>
  </class>

  <query name="findStudentByName">
    <![CDATA[from Student where name = :name]]>
  </query>
</hibernate-mapping>

調用：session.getNamedQuery("findStudentByName")

方式二：class 節點內部定義

<class name="com.test.bean.Student" ...>
  ...
  <query name="findStudentByName">
    <![CDATA[from Student where name = :name]]>
  </query>
</class>

調用：session.getNamedQuery("com.test.bean.Student.findStudentByName")（需全限定名）

方式三：原生 SQL 查詢（返回實體）

<sql-query name="findStudentByName">
  <return alias="s" class="com.test.bean.Student"/>
  <![CDATA[select {s.*} from student s where s.name = :name]]>
</sql-query>

• {s.*}：占位符，自動展開實體所有映射列；
• 必須查詢所有列，否則報「列名無效」。

方式四：原生 SQL 查詢（返回標量/部分字段）

<sql-query name="findStudentByName">
  <return-scalar column="name" type="string"/>
  <return-scalar column="age" type="integer"/>
  <![CDATA[select s.name, s.age from student s where s.name = :name]]>
</sql-query>

調用返回：List<Object[]>，或配合 Transformers.aliasToBean(Student.class) 轉實體。

關鍵技術點

1. CDATA 區塊：避免 XML 特殊字符（<、>、&）轉義，保持 SQL/HQL 原樣；
2. 參數綁定：:name 命名參數，防止 SQL 注入，支援類型安全；
3. 緩存友好：命名查詢可被 Hibernate 內部緩存，解析效率高於動態拼接 HQL；
4. 複雜查詢支援：聯合查詢、子查詢、存儲過程調用均可封裝。

Java 調用統一範例

public List<Student> queryByName(String name) {
    Session session = HibernateSessionFactory.getSession();
    Query q = session.getNamedQuery("findStudentByName"); // 或全限定名
    q.setString("name", name);
    return q.list();
}

最佳實踐建議

• 優先使用 方式一，統一管理，調用簡潔；
• 複雜報表類查詢使用 方式四，僅選取所需列，減少網絡傳輸；
• 避免在 Java 代碼中拼接 HQL/SQL，杜絕注入風險；
• 命名規範：findBy[Condition]、countBy[Condition]、update[Entity]By[Condition]。