SpringBoot 3.1.0（JDK17）升级后JPA HQL LIKE查询异常求助

问题场景 #

将项目从Spring Boot 3.0.6升级至3.1.0（搭配JDK17）后，原本正常运行的带命名参数的HQL LIKE查询出现运行时错误，触发条件为字符串列LIKE语句中使用%:参数名%的写法。开启logging.level.org.hibernate.orm.query.hql=DEBUG配置后必现该问题，旧版本Spring Boot（<3.0.6）无此异常。

示例出错代码：

@Query("SELECT m FROM Movie m WHERE m.title LIKE %:title%")
List<Movie> searchByTitleLike(@Param("title") String title);

报错原因 #

从错误栈可以定位到问题根源：开启HQL的DEBUG日志后，Hibernate使用String.format输出日志内容，但HQL语句中的%符号被误判为格式化占位符，后续的'被识别为无效的转换格式符，最终抛出UnknownFormatConversionException。这是Spring Boot 3.1.0升级带来的Hibernate版本变更引发的日志格式化bug。

解决方案 #

方案1：修改HQL写法，避免直接在语句中写% #

推荐将通配符拼接逻辑转移到参数或HQL内置函数中：

• 方式A：使用CONCAT函数拼接通配符

@Query("SELECT m FROM Movie m WHERE m.title LIKE CONCAT('%', :title, '%')")
List<Movie> searchByTitleLike(@Param("title") String title);

• 方式B：在调用方法时传入带通配符的参数

@Query("SELECT m FROM Movie m WHERE m.title LIKE :title")
List<Movie> searchByTitleLike(@Param("title") String title);
// 调用时传入格式如："%关键词%"的参数

方案2：调整HQL日志级别 #

如果不需要HQL翻译的DEBUG日志，可修改配置降低日志级别以规避该bug：

logging.level.org.hibernate.orm.query.hql=INFO

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