SpringBoot3迁移后Hibernate的coalesce()参数未解析致SQL异常

问题原因 #

• Hibernate 6.x对Criteria API中函数参数的绑定逻辑做了调整，和5.x版本的处理方式存在兼容性差异。旧版本会自动替换coalesce()里的参数占位符，而6.x中如果参数传递方式不符合新逻辑，就会导致占位符?未被解析。
• H2数据库从1.4.x升级到2.x后，SQL语法校验更严格，未被替换的占位符会直接触发JDBC异常，这也是旧版本组合没问题但新版本报错的核心原因之一。

解决办法 #

• 显式声明并绑定参数：使用CriteriaBuilder的parameter()方法明确声明参数，再在查询执行时手动绑定值，示例代码：

// 声明参数
ParameterExpression<LocalDate> refDateFromParam = cb.parameter(LocalDate.class, "refDateFrom");
ParameterExpression<LocalDate> refDateToParam = cb.parameter(LocalDate.class, "refDateTo");

// 构建coalesce条件
Predicate datePredicate = cb.between(
    root.get("refDate"),
    cb.coalesce(root.get("startDate"), refDateFromParam),
    cb.coalesce(root.get("endDate"), refDateToParam)
);

// 执行查询时绑定参数
List<YourEntity> result = entityManager.createQuery(query.where(datePredicate))
    .setParameter("refDateFrom", pRefDateFrom)
    .setParameter("refDateTo", pRefDateTo)
    .getResultList();

• 升级Hibernate版本：Hibernate 6.2.x的部分早期版本存在这类兼容性bug，升级到6.2.21.Final及以上的修复版本，大概率能直接解决该问题。
• 切换到JPQL/原生SQL：如果Criteria API的兼容性问题难以快速适配，可以改用Spring Data JPA的@Query注解编写JPQL，绕过Criteria的参数处理逻辑，示例：

@Query("SELECT e FROM YourEntity e WHERE e.refDate BETWEEN COALESCE(e.startDate, :refDateFrom) AND COALESCE(e.endDate, :refDateTo)")
List<YourEntity> findByDateRange(
    @Param("refDateFrom") LocalDate refDateFrom,
    @Param("refDateTo") LocalDate refDateTo
);

• 用value()包装参数：不要直接把外部参数传入coalesce()，而是通过CriteriaBuilder的value()方法包装，比如cb.coalesce(root.get("startDate"), cb.value(pRefDateFrom))，注意这种方式存在SQL注入风险，仅适用于参数为安全常量或已做严格校验的场景。

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