1. 为什么一个in能让人折腾一下午做持久层开发的朋友大概都有过这种体验明明 SQL 在客户端工具里跑得好好的一放进代码里就报错或者查出来的结果莫名其妙少了几条。我印象特别深的一次是排查一个列表查询的问题业务逻辑翻来覆去看了三遍都没毛病最后定位到一行 HQL问题就出在in后面那个括号里——参数传了个集合但写法上踩了坑。这件事之后我养成了一个习惯凡是涉及in的查询写完必须单独跑一遍边界用例。这篇内容就围绕Hibernate 写 SQL 语句中in的写法展开。说得具体点是在 Hibernate 这个 ORM 框架里当我们用 HQL、原生 SQL、Criteria 或者 JPA 的 Query 去构造带in条件的查询时参数到底该怎么传、集合该怎么绑、有哪些看起来能跑其实埋雷的写法。它解决的核心问题是让in查询在 Hibernate 的各种调用方式下都能稳定、安全、可维护地工作而不是靠试错碰运气。适合谁来参考如果你正在用 Hibernate 或 JPA 做数据访问层写过where id in (:ids)却不确定参数该怎么塞或者遇到过in查询结果不对、参数绑定异常、集合为空时报错这类问题那这篇基本能覆盖你 90% 的场景。哪怕你是刚接触 Hibernate 的新手我也会把底层逻辑掰开讲清楚保证看完能直接抄作业。需要先说明一点Hibernate 版本差异比较大HQL 的解析器在不同大版本之间有过调整下面讲的内容以常见的 Hibernate 5.x 和 6.x 为主涉及差异的地方我会单独标出来。另外文中所有示例都是基于通用实践整理的具体项目里还要结合你自己的实体映射来验证。2. 先把in的几种写法分清楚2.1 HQL 里的in参数是集合不是拼接字符串很多人第一次写 HQL 的in脑子里想的是 SQL 那套字符串拼接于是写出类似where id in (:idList)然后试图把1,2,3这样的字符串塞进去。这么写大概率会报类型转换或者语法错误因为 HQL 的in期望的是一个集合类型的参数Hibernate 会把它展开成多个占位符。正确的姿势是这样String hql from User u where u.id in (:ids); ListLong ids Arrays.asList(1L, 2L, 3L); ListUser users session.createQuery(hql, User.class) .setParameterList(ids, ids) .list();注意这里用的是setParameterList而不是setParameter。这是 HQL 里in最关键的一个点。setParameterList会告诉 Hibernate这个参数是一个集合请按集合元素个数展开成对应数量的绑定参数。底层实际生成的 SQL 大致是where id in (?, ?, ?)然后依次绑定。为什么必须用setParameterList因为 Hibernate 在解析 HQL 时对in后面的参数有专门的语法处理。它需要知道这个参数是单值还是多值才能决定生成几个占位符。用setParameter传集合Hibernate 会把它当成单个对象处理类型对不上就抛异常即便某些版本侥幸没抛生成的 SQL 也不对。这个设计其实很合理——占位符数量必须在 SQL 预编译阶段确定而集合大小是运行时才知道的所以框架必须有一个显式的入口来接收这个信息。2.2 原生 SQL 里的in两种思路各有取舍原生 SQL 的in写法分两条路。第一条是继续用命名参数加setParameterList前提是你用的是 Hibernate 的createNativeQuery并且参数用命名方式String sql select * from t_user where id in (:ids); ListLong ids Arrays.asList(1L, 2L, 3L); ListUser users session.createNativeQuery(sql, User.class) .setParameterList(ids, ids) .list();这条路和 HQL 基本一致Hibernate 会帮你展开占位符。第二条路是自己拼占位符适合参数数量动态且你想完全掌控 SQL 形态的场景String placeholders ids.stream().map(i - ?).collect(Collectors.joining(,)); String sql select * from t_user where id in ( placeholders ); Query query session.createNativeQuery(sql, User.class); for (int i 0; i ids.size(); i) { query.setParameter(i 1, ids.get(i)); }自己拼占位符的好处是可控性强坏处是要自己处理空集合、参数顺序、类型推断这些琐事。我个人的取舍是能用setParameterList就用它只有在需要和复杂原生 SQL 混排、或者框架层封装要求统一占位符风格时才手动拼。手动拼的时候一定要用?占位符而不是直接拼值这是防注入的底线后面还会细说。2.3 Criteria 与 JPA 的inAPI 更友好但坑没少Criteria API 里in是通过CriteriaBuilder.in()或者直接给Path.in(Collection)来构造的CriteriaBuilder cb session.getCriteriaBuilder(); CriteriaQueryUser cq cb.createQuery(User.class); RootUser root cq.from(User.class); cq.where(root.get(id).in(ids)); ListUser users session.createQuery(cq).getResultList();JPA 的Query接口则和 HQL 类似用setParameter传集合在多数实现里也能工作因为 JPA 规范对集合参数有约定。但这里有个容易忽略的点不同 JPA 实现Hibernate、EclipseLink 等对空集合的处理策略不一样有的抛异常有的生成in ()这种非法 SQL有的干脆返回空结果。所以即便 API 看起来统一空集合的边界还是得自己兜住。2.4 一张表看清四种写法的差异写法参数绑定方式空集合行为适用场景HQLsetParameterList通常报错或生成非法 SQL面向实体的查询原生 SQL 命名参数setParameterList同上需要原生 SQL 但想省事原生 SQL 手动占位符循环setParameter自己控制可提前返回复杂 SQL、动态条件CriteriaPath.in(Collection)实现相关需兜底类型安全的动态查询这张表建议存下来下次写in之前扫一眼能省不少调试时间。接下来我会把每种写法背后的原理和实操细节展开讲尤其是那些文档里不写、但实际会咬人的地方。3. 参数绑定背后的机制搞懂了就不慌3.1setParameterList到底做了什么要理解setParameterList得先知道 Hibernate 处理查询的两个阶段解析阶段和绑定阶段。解析阶段Hibernate 把 HQL 编译成内部的可执行查询结构这时候它看到in (:ids)会记录“这里有一个多值参数名字叫 ids”。绑定阶段你调用setParameterList(ids, list)Hibernate 拿到集合大小 N就把那个多值参数展开成 N 个位置占位符然后逐个绑定。这个机制解释了几个常见现象。第一为什么集合大小变化会导致执行计划缓存命中率下降——因为占位符数量变了SQL 文本就变了数据库那边就是一条新语句。第二为什么超大集合会出问题——比如传进去一万个 idHibernate 要展开一万个占位符SQL 文本长度爆炸数据库解析开销剧增甚至超过参数个数上限。第三为什么空集合会炸——N 等于 0展开成零个占位符in ()不是合法 SQL。所以用setParameterList的时候心里要有一根弦集合大小是有代价的。我一般会在业务层对集合大小做个上限保护比如超过 1000 个 id 就分批查询再合并而不是一股脑塞进去。3.2 为什么不能直接拼字符串进 HQL有人图省事把 id 列表拼成1,2,3直接字符串拼进 HQLfrom User u where u.id in ( idStr )。这么写能跑但有两个致命问题。一是 SQL 注入只要 idStr 的来源不完全可信就是敞开的门。二是执行计划无法复用每次 id 组合不同HQL 文本就不同Hibernate 的查询计划缓存和数据库的语句缓存全部失效高并发下性能会明显劣化。HQL 的字符串拼接还有个隐蔽的坑如果 idStr 里混进了非数字内容HQL 解析器可能在解析阶段就抛异常错误信息往往指向一个莫名其妙的位置排查起来很费劲。相比之下参数绑定把“值”和“结构”彻底分开结构固定、值可变既安全又高效。这也是为什么我一直强调in的参数永远走绑定不走拼接。3.3 集合元素类型与占位符类型的匹配setParameterList展开占位符时需要推断每个占位符的类型。多数情况下 Hibernate 能从实体映射或者集合元素类型推断出来但有些场景会失手。比如实体主键是Long你传了个ListInteger某些版本会报类型不匹配再比如用原生 SQL 查一个没有实体映射的列类型推断可能落到默认的序列化类型上导致绑定失败。我的经验是集合的泛型类型尽量和实体属性类型严格一致别依赖自动装箱拆箱的宽容。如果确实需要转换在传参前显式转好而不是指望框架兜底。原生 SQL 场景下如果类型推断有问题可以在createNativeQuery之后用addScalar明确声明结果列类型或者在绑定参数时用带类型的重载方法把类型说清楚。3.4 版本差异Hibernate 6 的变化点Hibernate 6 对 HQL 解析器做了较大重构in的语法支持更贴近 SQL 标准同时对参数类型的检查更严格。实际表现是一些在 5.x 里“能跑但不太对”的写法在 6.x 里会直接报错。比如把字符串当集合传、或者集合元素类型和属性类型不一致6.x 的报错会更明确这其实是好事但升级时要有心理准备。另外 6.x 对setParameterList的替代方案更丰富JPA 的setParameter传集合的支持也更完善。如果你的项目还在 5.x建议保持setParameterList的写法如果已经上 6.x可以逐步向标准 JPA 写法靠拢减少对 Hibernate 私有 API 的依赖。这个迁移不是必须的但方向上是更可移植的。4. 完整实操从零写一个稳的in查询4.1 场景设定与实体准备假设有一个用户表实体叫User主键id是Long还有一个status字段。需求是给定一批用户 id查出其中状态为启用status1的用户。这个需求简单到不能再简单但正好把in的各个要点都覆盖到。实体映射大致是这样省略 getter/setterEntity Table(name t_user) public class User { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; private Integer status; private String name; }4.2 HQL 版本的完整实现先写 HQL 版本这是最常用的public ListUser findEnabledByIds(Session session, ListLong ids) { if (ids null || ids.isEmpty()) { return Collections.emptyList(); } String hql from User u where u.id in (:ids) and u.status :status; return session.createQuery(hql, User.class) .setParameterList(ids, ids) .setParameter(status, 1) .list(); }这段代码有几个刻意的设计。第一入口处对空集合直接返回空列表不让它流到 Hibernate 层去触发异常。第二setParameterList和setParameter混用说明多值参数和单值参数可以共存绑定顺序无所谓靠名字匹配。第三status用参数绑定而不是硬编码进 HQL保持结构稳定。这里补一个细节如果ids里可能有重复元素in本身不影响结果正确性但会浪费占位符。如果集合来源不可控可以在传参前distinct一下减少无谓的展开。这个优化很小但在大集合场景下有意义。4.3 原生 SQL 版本的完整实现原生 SQL 版本我推荐命名参数加setParameterList的组合public ListUser findEnabledByIdsNative(Session session, ListLong ids) { if (ids null || ids.isEmpty()) { return Collections.emptyList(); } String sql select * from t_user where id in (:ids) and status :status; return session.createNativeQuery(sql, User.class) .setParameterList(ids, ids) .setParameter(status, 1) .list(); }如果因为某些原因必须手动拼占位符写法要更小心public ListUser findEnabledByIdsManual(Session session, ListLong ids) { if (ids null || ids.isEmpty()) { return Collections.emptyList(); } String placeholders String.join(,, Collections.nCopies(ids.size(), ?)); String sql select * from t_user where id in ( placeholders ) and status ?; QueryUser query session.createNativeQuery(sql, User.class); int index 1; for (Long id : ids) { query.setParameter(index, id); } query.setParameter(index, 1); return query.list(); }手动拼的时候参数顺序必须和占位符顺序严格对应这是最容易出错的地方。我的做法是把所有参数按出现顺序收集到一个列表里最后统一循环绑定避免手数下标。另外Collections.nCopies生成占位符比流式拼接更直观也不容易写错分隔符。4.4 分批查询的封装前面提到大集合要分批这里给一个可复用的封装思路public ListUser findEnabledByIdsInBatches(Session session, ListLong ids, int batchSize) { if (ids null || ids.isEmpty()) { return Collections.emptyList(); } ListUser result new ArrayList(); for (int i 0; i ids.size(); i batchSize) { ListLong batch ids.subList(i, Math.min(i batchSize, ids.size())); result.addAll(findEnabledByIds(session, batch)); } return result; }batchSize取多少合适这取决于数据库的参数个数上限和单次查询的合理耗时。常见数据库对单条语句的参数个数有上限具体数值各产品不同保守起见取 500 到 1000 之间比较稳妥。分批之后要注意结果去重和排序问题——如果业务要求按传入 id 的顺序返回分批查询天然打乱了顺序需要在合并后重新排序这一点很容易被忽略。4.5 参数选择的计算过程为什么batchSize不能拍脑袋定可以简单算一笔账。假设单条 SQL 文本里每个占位符加逗号大约占 2 个字符1000 个占位符就是 2000 字符左右的 SQL 文本增量这对数据库解析来说不算大。但如果取到 10000文本增量到 20000 字符解析开销和网络传输都上来了而且很可能撞上参数个数上限直接报错。所以 500 到 1000 是一个在“减少往返次数”和“控制单语句开销”之间的平衡点。实际取值还要看你的数据库类型和驱动版本建议在测试环境压一下再定。5. 那些年踩过的坑与排查实录5.1 空集合最常见的翻车点空集合是in查询的头号杀手。表现五花八门有的报 SQL 语法错误有的报参数绑定异常有的静默返回全表数据这个最吓人。根因都一样——in ()不是合法 SQL而框架在展开占位符时对零元素没有统一处理。排查思路很直接在调用查询之前打印集合大小确认是不是空。解决方式就是在业务层入口做空集合短路返回空结果。这个判断成本极低但能挡掉一大类问题。我见过有团队在 DAO 基类里统一做了这个拦截所有in查询自动受益这个做法值得借鉴。注意空集合短路返回的是空列表不是 null。返回 null 会让调用方多一层判空容易引发空指针统一返回空集合是更稳妥的约定。5.2 集合里有 null 元素集合非空但里面混了 null同样会出问题。in (?, ?, ?)里某个占位符绑定 nullSQL 语义上id in (1, null, 3)不会匹配 null 行但某些数据库或驱动会在绑定阶段就报错。更隐蔽的是如果集合来自上游某个可能产生 null 的转换问题会延迟到运行时才暴露。处理方式是在传参前过滤 nullids.stream().filter(Objects::nonNull).collect(...)。过滤后如果集合变空回到上一条的空集合短路逻辑。这个过滤要不要做取决于数据来源的可信度但只要集合来自外部输入或者多表关联结果我都建议加上成本可以忽略。5.3 类型不匹配的报错定位类型不匹配的报错信息往往不友好可能只说“无法转换参数”而不告诉你哪个参数。定位方法是把查询拆开先只保留in条件跑一次确认是不是它的问题再逐步加回其他条件。如果确认是in的类型问题检查集合泛型和实体属性类型是否一致特别注意Integer和Long、String和枚举这类常见错配。还有一种情况是原生 SQL 查询的列没有实体映射Hibernate 推断不出类型。这时候用addScalar显式声明或者在绑定参数时用setParameter(name, value, Type)把类型说死。多花一行代码省下半小时排查。5.4 常见问题速查表现象可能原因排查动作解决方式报 SQL 语法错误提示in ()集合为空打印集合大小入口短路返回空列表参数绑定异常类型转换失败集合元素类型与属性不符检查泛型声明统一类型或显式转换查询结果比预期少集合含 null 或重复检查集合内容过滤 null、去重高并发下变慢集合大小波动导致计划缓存失效观察 SQL 文本变化分批、固定批次大小升级后原写法报错版本对参数检查更严对比版本文档改用标准 JPA 写法这张表是我自己排查时总结的基本覆盖了in相关问题的常见形态。遇到新问题先往表里对对不上再往下深挖。5.5 一个容易被忽略的性能细节in查询的集合如果来自另一个查询的结果比如“先查出某类用户的所有 id再用这些 id 去查订单”这种两步走在大数据量下会很慢。更好的做法是用子查询把两步合成一步where o.userId in (select u.id from User u where ...)。HQL 和原生 SQL 都支持子查询形式的in这样数据库优化器有机会把两步合并执行避免把大量 id 在应用和数据库之间来回搬。当然子查询不是万能的如果子查询本身很复杂或者结果集很大合并执行未必更快。判断标准是看执行计划而不是凭感觉。我的习惯是id 数量在几百以内两步走没问题上千了优先考虑子查询或者关联查询。6. 写in查询的几条硬规矩6.1 参数永远走绑定绝不拼值这条没有例外。不管是 HQL、原生 SQL 还是 Criteriain后面的值一律通过参数绑定传入。字符串拼接值不仅带来注入风险还破坏执行计划复用是双重损失。手动拼占位符可以但拼的只能是?或者命名占位符不能是具体的值。这个界限要划清楚。6.2 空集合和 null 元素在入口处理把防御逻辑放在查询方法的最前面而不是指望框架或者数据库兜底。空集合返回空列表null 元素过滤掉这两步加起来不到五行代码却能挡掉大部分运行时异常。我现在的习惯是任何接收集合参数的查询方法第一段代码就是这两个判断形成肌肉记忆。6.3 大集合分批批次大小有依据不要等出了问题才想起分批。集合大小超过几百就考虑分批批次大小根据数据库参数上限和实测性能来定别拍脑袋。分批之后记得处理结果顺序和去重这两点前面都提过但实际项目里还是经常被漏掉。6.4 优先用子查询替代两步查询当in的集合来自另一个查询时先想想能不能用子查询合并。能合并就合并让数据库去做优化。合并之后如果性能不理想再退回两步走并且用分批控制单次数据量。这个决策顺序比反过来更合理因为子查询的写法通常更简洁维护成本更低。6.5 版本升级前先跑一遍in的用例Hibernate 大版本升级时in相关的行为变化是重点检查项。升级前把项目里所有in查询的边界用例空集合、单元素、大集合、含 null跑一遍记录行为差异再决定要不要调整写法。这个准备工作花不了多少时间但能避免升级后线上出问题再回头排查的被动局面。7. 我个人在实际操作中的体会写了这么多年持久层代码我对in这个看似简单的语法有一个越来越深的感受它的复杂度不在语法本身而在边界。正常路径下setParameterList一调就完事谁都会写。真正拉开差距的是空集合、null 元素、大集合、类型不匹配这些边角情况处理好了系统就稳处理不好就是定时炸弹。我现在写任何带in的查询都会条件反射地先问自己三个问题集合会不会为空里面会不会有 null最大可能有多大这三个问题答完代码结构基本就定了。这个方法不复杂但确实帮我省了很多排查时间。如果你也在维护数据访问层不妨把这个习惯带走比记住某个具体 API 更有用。