多次插入后Spring Data JPA查询缺失命名参数问题求助

原因解释 #

这是Hibernate（Spring Data JPA默认底层实现）查询解析与缓存机制的bug导致的：

• 当命名参数仅出现在ORDER BY子句的CASE表达式中，未在WHERE子句中被引用时，Hibernate的查询计划缓存可能在特定数据场景下（比如插入多条包含相同param2/param3值的记录后），错误判定这些参数为"未使用"，进而将它们从查询参数列表中移除。
• 后续执行查询时，即便你正常传递了参数，但Hibernate缓存的查询计划里已经没有这些参数的定义，就会抛出参数缺失的异常。

你的临时修复本质是通过在WHERE子句添加无业务影响的伪条件，强制让param3/param4/param5出现在查询的WHERE部分，让Hibernate始终识别到这些参数的存在，避免被优化丢弃。

更优解决方案（无需伪条件） #

1. 禁用该查询的缓存 #

通过@QueryHints注解禁用当前查询的缓存，避免Hibernate错误缓存有问题的查询计划：

@Query("SELECT ft FROM Entity ft WHERE ft.someField1.param1 = :param1 AND ft.param2 = :param2 " +
        "ORDER BY " +
        "(CASE WHEN ft.param3 = :param3 THEN 0 ELSE 1 END), " +
        "(CASE WHEN ft.param3 = :param3 AND ft.param4 = :param4 AND ft.param5 = :param5 THEN 0 " +
        "     WHEN ft.param3 = :param3 AND (ft.param4 = :param4 OR ft.param5 = :param5) THEN 1 " +
        "     WHEN ft.param3 = :param3 THEN 2 " +
        "     WHEN ft.param4 = :param4 AND ft.param5 = :param5 THEN 3 " +
        "     WHEN (ft.param4 = :param4 OR ft.param5 = :param5) THEN 4 ELSE 5 END), " +
        "ft.updatedTimestamp DESC")
@QueryHints({
    @QueryHint(name = org.hibernate.annotations.QueryHints.CACHEABLE, value = "false")
})
Page<Entity> queryEntitiesWithCustomSorting(
        @Param("param1") String param1,
        @Param("param2") String param2,
        @Param("param3") String param3,
        @Param("param4") EnumA param4,
        @Param("param5") EnumB param5,
        Pageable pageable);

2. 升级Hibernate/Spring Boot版本 #

这个参数推断的bug在Hibernate 5.4.30+、6.x版本中已被修复。如果你使用Spring Boot，直接升级到2.6.x及以上版本（对应Hibernate 5.4.30+）即可从根源解决问题。

3. 将排序逻辑移出JPQL #

把复杂排序逻辑从JPQL中剥离，改用Spring Data JPA的Sort接口自定义排序规则（适合数据量不大的场景）：

// 先执行基础查询
List<Entity> allMatches = entityManager.createQuery("SELECT ft FROM Entity ft WHERE ft.someField1.param1 = :param1 AND ft.param2 = :param2", Entity.class)
        .setParameter("param1", param1)
        .setParameter("param2", param2)
        .getResultList();

// 自定义排序逻辑
allMatches.sort((a, b) -> {
    int rankA = calculateRank(a, param3, param4, param5);
    int rankB = calculateRank(b, param3, param4, param5);
    if (rankA != rankB) {
        return Integer.compare(rankA, rankB);
    }
    return b.getUpdatedTimestamp().compareTo(a.getUpdatedTimestamp());
});

// 手动分页
int start = (int) pageable.getOffset();
int end = Math.min((start + pageable.getPageSize()), allMatches.size());
Page<Entity> page = new PageImpl<>(allMatches.subList(start, end), pageable, allMatches.size());

对应的calculateRank方法实现原CASE逻辑：

private int calculateRank(Entity ft, String param3, EnumA param4, EnumB param5) {
    if (Objects.equals(ft.getParam3(), param3)) {
        if (Objects.equals(ft.getParam4(), param4) && Objects.equals(ft.getParam5(), param5)) {
            return 0;
        } else if (Objects.equals(ft.getParam4(), param4) || Objects.equals(ft.getParam5(), param5)) {
            return 1;
        } else {
            return 2;
        }
    } else {
        if (Objects.equals(ft.getParam4(), param4) && Objects.equals(ft.getParam5(), param5)) {
            return 3;
        } else if (Objects.equals(ft.getParam4(), param4) || Objects.equals(ft.getParam5(), param5)) {
            return 4;
        } else {
            return 5;
        }
    }
}

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