Hibernate 5.2 Query的setHint方法已废弃 可用替代方案是什么

Hibernate 5.2版本对查询接口做了重构对齐JPA规范，org.hibernate.Query接口自定义的setHint(String, Object)方法被标记废弃，官方推荐的替代方式按使用场景分为三类：

• 优先使用Hibernate提供的类型安全原生方法设置查询属性
  大部分常用的查询提示都有对应的专属方法，不需要通过传字符串hint名的方式配置，能避免硬编码拼写错误，常见配置对应关系：
  • 开启/关闭查询缓存：setCacheable(boolean)
  • 指定查询缓存分区：setCacheRegion(String)
  • 设置查询缓存模式：setCacheMode(CacheMode)
  • 设置查询超时时间：setTimeout(int)
  • 设置查询只读模式：setReadOnly(boolean)
  • 设置Flush刷新模式：setFlushMode(FlushMode)
• 配置JPA标准规范定义的查询提示时，直接调用JPAQuery接口的setHint方法即可
  org.hibernate.Query本身就继承了对应版本的JPA Query接口（Hibernate 5.x对应javax.persistence.Query，Hibernate 6+对应jakarta.persistence.Query），父接口上定义的setHint是JPA规范标准方法，没有被标记废弃，可以直接调用。
• 配置无对应专属方法的Hibernate原生提示、第三方扩展提示时，同样通过JPA接口的setHint方法传入即可，不需要额外做实现类转换。

代码示例 #

旧的废弃写法：

org.hibernate.Query query = session.createQuery("from User u where u.id = :uid");
// 以下调用的是Hibernate自定义的废弃setHint方法
query.setHint("org.hibernate.cacheable", true);
query.setHint("org.hibernate.timeout", 3);

对应推荐写法：

org.hibernate.Query query = session.createQuery("from User u where u.id = :uid");
// 用类型安全的原生方法替代
query.setCacheable(true);
query.setTimeout(3);

// JPA标准提示直接调用继承自JPA接口的setHint即可
query.setHint("jakarta.persistence.query.timeout", 3000);

官方废弃该方法的核心原因是消除Hibernate自定义方法和JPA父接口同名方法的签名歧义，同时引导开发者优先使用类型安全的配置方式，降低配置出错概率。

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