Hibernate 5中Query、createCriteria废弃后如何正确编写JPQL查询

1. Query接口及相关方法替换 #

Hibernate 5.2之后，原有org.hibernate.Query接口、list()方法、无类型的createQuery(String hql)重载均被标记废弃，需替换为JPA标准实现：

通用DAO层createQuery方法改造 #

新增泛型返回值，指定结果类型，避免类型转换告警：

protected <T> TypedQuery<T> createQuery(String hql, Class<T> resultClass) {
    return getSession().createQuery(hql, resultClass);
}

业务查询方法改造 #

• HQL中索引参数需带序号后缀（如?1代表第一个参数），也可使用命名参数提升可读性
• 参数绑定统一使用setParameter方法
• list()替换为getResultList()

改造后的findByName方法如下：

// 按用户名查询用户
public List<User> findByName(String name){
    TypedQuery<User> q = getSession().createQuery("from User where lower(nome) like lower(:name)", User.class);
    q.setParameter("name", "%" + name +"%");
    return q.getResultList();
}

2. createCriteria方法替换 #

原有Hibernate专属createCriteria API已废弃，需替换为JPA标准Criteria API：

通用DAO层改造示例 #

protected CriteriaQuery<T> createCriteriaQuery() {
    CriteriaBuilder criteriaBuilder = getSession().getCriteriaBuilder();
    return criteriaBuilder.createQuery(this.clazz);
}

通用查询示例（查询当前实体类所有数据） #

public List<T> findAll() {
    CriteriaQuery<T> criteriaQuery = createCriteriaQuery();
    Root<T> root = criteriaQuery.from(this.clazz);
    criteriaQuery.select(root);
    return getSession().createQuery(criteriaQuery).getResultList();
}

注意事项 #

• 若项目使用Java EE规范（Spring Boot 2.x及更早版本），将所有jakarta.persistence包名替换为javax.persistence即可
• 新Criteria API为JPA标准实现，可跨ORM框架兼容，维护性优于原有Hibernate专属实现
• 推荐优先使用命名参数代替索引参数，避免参数顺序错误导致的查询异常

内容的提问来源于stack exchange，提问作者Joel Menezes