Hibernate 6.0.0移除QBE相关类 原Example接口代码无法编译问题咨询

问题原因 #

Hibernate Core 6.0版本正式移除了原有内置的Example、Criterion等专有的QBE（Query By Example）API，该类API在5.x版本中已经被标记为废弃，因此升级后原有代码会编译失败。

解决方案 #

方案一：迁移至JPA标准QBE实现（长期推荐） #

JPA 3.0及以上版本已标准化QBE能力，Hibernate 6.x完整支持该标准API，无需依赖Hibernate专有实现，后续版本兼容性更稳定。
示例代码如下：

import jakarta.persistence.criteria.CriteriaBuilder;
import jakarta.persistence.criteria.CriteriaQuery;
import jakarta.persistence.criteria.Root;
import jakarta.persistence.criteria.Example;

// 原有业务逻辑
Session session = (Session) em.unwrap(Session.class);
// 构造标准QBE查询
CriteriaBuilder cb = session.getCriteriaBuilder();
CriteriaQuery<你的实体类> query = cb.createQuery(你的实体类.class);
Root<你的实体类> root = query.from(你的实体类.class);
// 使用样例实体构造查询条件
Example<你的实体类> example = Example.of(entityFrom);
query.where(cb.equal(root, example));
// 执行查询获取结果
List<你的实体类> resultList = session.createQuery(query).getResultList();

如果你的项目使用Spring Data JPA，可直接调用JpaRepository内置的findAll(Example<S> example)方法完成QBE查询，无需手动构造Criteria。

方案二：引入legacy兼容模块，无需修改原有代码 #

如果暂时不想改造现有QBE逻辑，可以引入Hibernate官方拆分出的遗留Criteria API兼容模块，原有代码可直接复用：
Maven依赖配置如下：

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-legacy-criteria</artifactId>
    <version>6.0.0.Final</version>
    <!-- 注意版本号要和你引入的hibernate-core版本完全一致 -->
</dependency>

引入依赖后原有Example.create()等写法无需修改即可正常编译运行。注意该模块仅做兼容使用，官方不会再迭代新功能，长期使用建议迁移到标准JPA API。

注意事项 #

Hibernate 6.x已全面迁移到Jakarta EE规范，所有原javax.persistence包下的类需要替换为jakarta.persistence包下的对应类。

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