JPQL查询中集合参数含Null时IN表达式匹配可空实体属性失效的技术咨询

首先，这个问题的核心在于SQL本身的NULL语义，以及JPA规范未明确覆盖的厂商实现细节：
SQL中NULL的比较是特殊的——任何与NULL的比较（包括IN）都会返回UNKNOWN，而非TRUE或FALSE。JPQL的IN表达式最终会被Hibernate翻译成对应的SQL，当你的参数集合包含null时，生成的SQL类似：

SELECT e FROM my_entity e WHERE e.status IN (?, ?)

其中第二个参数是NULL，但e.status IN (1L, NULL)在SQL中等价于(e.status = 1L) OR (e.status = NULL)，而后者永远不会为真，所以自然查不到status为NULL的实体。

JPA 2.2规范确实没有明确规定当IN参数集合包含NULL时的处理逻辑，这属于各厂商的实现细节，Hibernate这里选择严格遵循SQL的语义，所以不会自动帮你处理NULL的匹配情况。

针对这个场景，有几种优雅的处理方式，既可以通过参数控制是否包含NULL匹配，又不需要硬编码死逻辑：

1. 动态拼接查询条件（推荐） #

通过检查参数集合中是否包含NULL，动态在JPQL中添加OR e.status IS NULL的条件，同时移除参数集合中的NULL值（避免无效的IN条目）。这种方式完全符合JPA标准，兼容性最好：

List<Long> statuses = Arrays.asList(null, 1L);
List<Long> nonNullStatuses = statuses.stream()
    .filter(Objects::nonNull)
    .collect(Collectors.toList());
boolean needsNullMatch = statuses.contains(null);

// 构建动态JPQL
StringBuilder jpqlBuilder = new StringBuilder("SELECT e FROM MyEntity e WHERE ");
if (!nonNullStatuses.isEmpty()) {
    jpqlBuilder.append("e.status IN :statuses");
    if (needsNullMatch) {
        jpqlBuilder.append(" OR e.status IS NULL");
    }
} else if (needsNullMatch) {
    // 只有NULL匹配的情况
    jpqlBuilder.append("e.status IS NULL");
} else {
    // 空集合，返回无结果
    jpqlBuilder.append("1 = 0");
}

// 执行查询
TypedQuery<MyEntity> query = entityManager.createQuery(jpqlBuilder.toString(), MyEntity.class);
if (!nonNullStatuses.isEmpty()) {
    query.setParameter("statuses", nonNullStatuses);
}
List<MyEntity> actual = query.getResultList();

2. 使用COALESCE统一处理NULL值 #

通过COALESCE函数将实体的status和参数中的NULL都映射到一个业务中不存在的特殊值，从而让IN表达式可以正常匹配：

List<Long> statuses = Arrays.asList(null, 1L);
// 将参数中的NULL替换为特殊值（比如-1L，确保不会与业务有效值冲突）
List<Long> adjustedStatuses = statuses.stream()
    .map(s -> s == null ? -1L : s)
    .collect(Collectors.toList());

List<MyEntity> actual = entityManager.createQuery(
    "SELECT e FROM MyEntity e WHERE COALESCE(e.status, -1L) IN :adjustedStatuses",
    MyEntity.class
)
.setParameter("adjustedStatuses", adjustedStatuses)
.getResultList();

注意：这种方式需要确保你选择的特殊值（比如-1L）永远不会出现在正常的status数据中，否则会导致错误匹配。

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