Hibernate HQL/原生SQL參數綁定完全指南：三種方式對比與最佳實踐

參數綁定三大方式速覽

1. 命名參數：HQL首選，清晰不易錯

// 單值參數
String hql = "from User u where u.name = :name and u.age > :age";
Query q = session.createQuery(hql);
q.setParameter("name", "ZhangSan");
q.setParameter("age", 25);

// 集合參數（IN子句專用）
List<Integer> ids = Arrays.asList(1, 2, 3);
String hql2 = "from User u where u.id in (:ids)";
Query q2 = session.createQuery(hql2);
q2.setParameterList("ids", ids); // 自動展開為 (?, ?, ?)

// 原生SQL同理支持
String sql = "select * from users where name = :name";
SQLQuery sq = session.createSQLQuery(sql);
sq.setParameter("name", "LiSi");

優勢：參數順序無關、名稱自文檔、重複參數無需多次設置、集合參數自動處理IN子句展開。

2. 位置參數：原生SQL常用，須嚴格對應順序

// 單值
String hql = "from User u where u.name = ? and u.age > ?";
Query q = session.createQuery(hql);
q.setParameter(0, "WangWu"); // 索引從0開始
q.setParameter(1, 30);

// 批量設置（需手動指定Type）
Object[] values = { "ZhaoLiu", 28 };
Type[] types = { StandardBasicTypes.STRING, StandardBasicTypes.INTEGER };
q.setParameters(values, types);

// 原生SQL位置參數
String sql = "select * from users where name = ? and age > ?";
SQLQuery sq = session.createSQLQuery(sql);
sq.setParameter(0, "SunQi");
sq.setParameter(1, 35);

注意：HQL位置參數索引從0開始；JDBC原生PreparedStatement索引從1開始，切勿混淆。

3. 實體參數：關聯查詢的類型安全利器

// 假設Order關聯Customer，Customer主鍵為Long
Order order = ...;
String hql = "from Order o where o.customer = :cust";
Query q = session.createQuery(hql);
q.setEntity("cust", order.getCustomer()); // 自動提取主鍵值綁定

// 復合主鍵實體同理適用
CompositeKeyEntity entity = ...;
q.setEntity("entity", entity);

適用於關聯屬性為實體類型的查詢條件，Hibernate自動解析實體標識符（單一或復合主鍵）生成SQL，避免手動拼裝主鍵字段。

4. 進階：原生SQL結果集映射（補充）

參數綁定後，結果映射常用模式：

// 映射到實體
SQLQuery sq = session.createSQLQuery("select * from users where id = ?")
    .addEntity(User.class)
    .setParameter(0, 1L);
User u = (User) sq.uniqueResult();

// 映射到VO (AliasToBean)
SQLQuery sq2 = session.createSQLQuery(
    "select id as \"id\", name as \"name\" from users where id = ?")
    .addScalar("id", StandardBasicTypes.LONG)
    .addScalar("name", StandardBasicTypes.STRING)
    .setResultTransformer(Transformers.aliasToBean(UserVO.class))
    .setParameter(0, 1L);
UserVO vo = (UserVO) sq2.uniqueResult();

最佳實踐總結

1. HQL/JPQL首選命名參數：可讀性最高、重構安全、集合參數原生支持。
2. 原生SQL推薦命名參數：同樣享受可讀性優勢，避免位置參數順序易錯。
3. 實體關聯條件用setEntity：類型安全、復合主鍵透明處理。
4. 批量位置參數慎用：必須手動構建Type[]，維護成本高，僅用於動態構建SQL的極少數場景。
5. 參數值不可為null直接綁定：若參數可能為null，需顯式setParameter("name", null, StandardBasicTypes.STRING)指定類型，否則Hibernate無法推斷類型報錯。
6. 防止SQL注入：參數綁定機制天然防注入，**嚴禁字符串拼接SQL/HQL**。