如何向JPA named native query中传入字符串列表并解决参数异常

报错核心原因 #

JPA 原生查询的IN子句需要对应多值占位符，低版本JPA实现默认不支持直接传入集合类型参数，参数类型不匹配就会抛出invalid query parameter exception异常。

标准实现步骤 #

1. 定义命名原生查询 #

@NamedNativeQuery的SQL语句中IN子句直接使用命名占位符即可，不需要额外加引号或处理括号，示例：

@Entity
@NamedNativeQuery(
    name = "YourEntity.queryByStrList",
    query = "SELECT * FROM your_table WHERE biz_field IN (:strList)",
    resultClass = YourEntity.class
)
public class YourEntity {
    // 实体字段定义
}

2. 调用查询传递参数 #

JPA 2.0及以上版本、Hibernate 5.2及以上版本直接调用setParameter传入字符串列表即可：

// 构造待传入的字符串列表
List<String> strList = List.of("val1", "val2", "val3");
// 创建命名查询
Query query = entityManager.createNamedQuery("YourEntity.queryByStrList");
// 传入参数
query.setParameter("strList", strList);
// 执行查询获取结果
List<YourEntity> resultList = query.getResultList();

低版本Hibernate兼容方案 #

如果使用Hibernate <5.2版本，需要unwrap为Hibernate原生Query对象调用setParameterList方法：

Query jpaQuery = entityManager.createNamedQuery("YourEntity.queryByStrList");
org.hibernate.query.Query hibernateQuery = jpaQuery.unwrap(org.hibernate.query.Query.class);
hibernateQuery.setParameterList("strList", strList);
List<YourEntity> resultList = hibernateQuery.list();

常见问题排查 #

• 检查占位符名称与setParameter传入的参数名完全一致，无拼写错误
• 不要手动给IN子句的占位符加引号，错误写法示例：IN '(:strList)'
• 传入的字符串列表不能为empty，空列表会生成IN ()的非法SQL语法，需要提前做逻辑分支处理
• 确认实体类上的@NamedNativeQuery的resultClass属性与返回结果类型匹配

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