做报表开发的人，十有八九都碰过这么个需求：用户在前台勾选了几个城市，点查询，后台就得把这几座城市的订单数据汇总成一张表。到了 JasperReports + iReport 这条技术栈里，这个“SQL 语句里有 IN，要动态赋值”就成了一个高频问题。经常有朋友在群里问，为什么我写WHERE id IN ($P{ids})预览直接报错，为什么用户的勾选项传进来以后查出来是空的，为什么换成$P!{ids}又有人说有注入风险。今天这篇就把这个场景彻底拆开，从参数机制讲到最终落地，把能踩的坑基本都踩一遍，看完你就能直接抄作业。
1. 场景拆解：动态 IN 为什么不能直接写$P{}
1.1 一回车就报错的根源：参数机制本身就不同
先说一个最容易踩的直觉陷阱。很多初学者拿到 JasperReports 以后，第一反应是把普通参数的写法搬到 IN 里：
SELECT * FROM order_info WHERE city_id IN ($P{cityIds})然后在 Java 端传一个"1,2,3"字符串进去，或者传一个Arrays.asList(1, 2, 3)进去。结果就是预览报错，或者运行时报错，日志里写着莫名其妙的一句Cannot cast from String to Collection之类。
这里面的根本原因，在于$P{}和$X{}的生成逻辑完全不是一回事。$P{param}在编译 SQL 时会被当成一个独立的 JDBC 参数占位符，也就是编译后的 SQL 形如city_id IN (?)。当你传进去的是 List 时，JDBC 驱动根本不知道该怎么把 List 绑定成一个 SQL 列表值，因为 JDBC 的PreparedStatement只支持单个标量值。当你传进去的是"1,2,3"字符串时，SQL 语义又变成了city_id IN ('1,2,3')，这不是你要的列表，而是只有一个元素、内容还是带逗号的字符串。这就是第一重坑。
$X{}则是 JasperReports 专门为这种“集合类条件”设计的表达式，它做的不是占位符绑定，而是在 SQL 编译阶段把集合展开成真正的列表文本。它拿到一个java.util.Collection参数，就能在最终执行的 SQL 里生成city_id IN (1, 2, 3)这样的字面量。所以归根结底一句话：只要 SQL 里出现IN，并且这个列表是动态的，就不要试图用$P{}硬扛。
1.2 这类需求背后的实际业务形态
动态 IN 在报表场景里可以说是绕不开的。我做过的项目里，这类需求基本集中在三种形态：
第一种是多选下拉过滤，比如报表页面上一个“区域”复选控件，用户选了华东、华北、华南，后台要把这三个区域编码作为列表传给报表，SQL 里就是region_code IN ($X{IN, region_code, regionList})。
第二种是批量主键查询，典型例子是用户从列表页勾选了十几条订单，点“打印汇总”，然后把订单号集合传进报表，WHERE 条件里要把这些主键挨个匹配。
第三种是子查询联动，比如先用一个子查询找出满足业务条件的客户 ID 集合，再作为 IN 列表过滤主查询。本质上集合还是那个集合，只是来源不同。
这三种形态的根本诉求是一致的：把运行时才知道的多值集合安全地注入到 SQL 的IN列表里。只要抓住“集合参数 + $X 语法”这个主线，它们都能统一解决。
2. 正解：$X{IN}语法 + Collection 参数
2.1$X{IN}的基本写法和参数类型设置
主推方案非常直接，JRXML 里的查询语句这样写：
<queryString> <![CDATA[ SELECT order_id, order_date, city_id, amount FROM order_info WHERE city_id IN ($X{IN, city_id, cityIds}) ]]> </queryString>注意$X{IN, city_id, cityIds}的三个部分：第一个是操作符类型IN，第二个是数据库表的列名，第三个是报表参数名cityIds。对应地，在 iReport 或者 Jaspersoft Studio 里新建参数时，参数名称必须和第三个参数名一致，参数类（Parameter Class）不要选默认的java.lang.String，要改成java.util.Collection。
如果是老版本的 iReport，参数类型下拉框里直接选java.util.Collection就行；如果是 Jaspersoft Studio，则在 New Parameter 对话框里的 Parameter Class 输入java.util.Collection，或者更具体地选java.util.List。两者都可以，核心是这个参数必须实现Collection接口。
2.2 Java 端到底应该传什么值
传值这一步是重灾区，这里值得写清楚。Java 调用报表填充时，参数 Map 里放的数据类型必须严格对得上：
Map<String, Object> params = new HashMap<>(); // 正确示范：传 List<Integer> List<Integer> cityIds = Arrays.asList(101, 102, 103); params.put("cityIds", cityIds); JasperPrint jasperPrint = JasperFillManager.fillReport( reportStream, params, connection);这里有个隐藏得很深的坑：如果报表列是字符串类型，比如region_code，而你手上拿到的是List<String>，那么$X{IN}会自动给每个元素加上单引号，生成region_code IN ('HD', 'HN', 'HB')。如果元素是数字类型，生成的就是不带引号的数字列表。这是 JasperReports 内部的类型判断和转义逻辑在起作用，比你自己拼字符串要安全得多。
如果是代码里原本就有的数组，比如int[] ids，可千万别直接Arrays.asList(ids)塞进去。Arrays.asList对基本类型数组的处理结果是List<int[]>，也就是整个数组变成了一个元素，执行时肯定对不上。正确做法是先转成包装类型：
int[] ids = new int[] {101, 102, 103}; List<Integer> cityIds = Arrays.stream(ids) .boxed() .collect(Collectors.toList()); params.put("cityIds", cityIds);提示：
$X{IN}要求参数必须是Collection的实例，不是数组。传数组进去一样会报类型转换错误。凡是看到报错里带cast字样的，八成就是类型这关没过。
2.3 空列表和单元素的边界行为
不要以为传一个长度大于 1 的 List 就万事大吉，实际业务里还有两种边界情况会被偷袭。
第一种是空列表。用户在界面上一个都没勾就点了查询，List 是空的。这时候如果你手写WHERE city_id IN ($X{IN, city_id, cityIds})，JasperReports 不会生成一个语法错误的city_id IN ()，而是会很聪明地生成一条恒真条件city_id IN (NULL)配合为空的集合？其实更准确地说，按不同版本实现，它可能生成类似(1 = 1)的恒真条件。这么做是为了让整条 SQL 即使条件为空也能正常执行，返回全部数据。这个行为在你需要“空集合=不限制”的业务语义时非常顺手；但如果业务要求“空集合就查不到数据”，那你需要在 Java 端提前判断，或者反过来用NOT IN的同类逻辑，这一点在 3.2 节我会再讲。
第二种是单元素列表。虽然IN (1)本身完全合法，但有些数据库对这种写法会有执行计划上的偏好差异。大部分场景都不用担心，MySQL 和 Oracle 都能正确处理单元素 IN；继续用$X{IN}即可，不要为此单独写一套=分支，纯属多余维护工作。
2.4$X还有哪些兄弟姐妹
既然说到这里，顺便把$X{}家族的其他操作符也列一下，因为实际项目里基本都能碰到。
| 表达式写法 | 作用 | 生成的 SQL 风格 |
|---|---|---|
$X{IN, col, param} | 集合匹配 | col IN (1, 2, 3) |
$X{NOT IN, col, param} | 集合排除 | col NOT IN (1, 2, 3) |
$X{BETWEEN, col, startParam, endParam} | 范围内查询 | col BETWEEN 1 AND 100 |
$X{LOWER, col, param} | 大小写不敏感匹配 | LOWER(col) = LOWER('A') |
其中NOT IN在空集合时生成的是一条恒假条件，比如(1 = 0)，意思就是“什么都不匹配”。这个细节做报表筛选时很容易被忽略，建议在需求阶段就和业务方确认清楚空集合到底代表“不过滤”还是“查不到”，然后再决定用哪个操作符。
3. 备选方案与坑位分析：字符串拼接和$P!{}
3.1 最土但很多人仍在用的$P!{}手工拼法
除了$X，还有一个$P!{}语法，它和$X的区别在于$P!{}是原样替换，也就是说无论参数里是什么字符串，它都会直接嵌入到 SQL 文本里。于是有人这么写：
<queryString> <![CDATA[ SELECT * FROM order_info WHERE city_id IN ($P!{cityIdStr}) ]]> </queryString>Java 端手动拼一个"101,102,103"传进去。这个方案能用吗？能用。但我不建议在一开始就选它，原因有两条。
第一是SQL 注入风险。$P!{}的定位就是“我真的需要把一段原始文本拼进去”，它不经过参数转义。如果传入内容里混入' OR 1=1 --，最终执行的就是被篡改后的 SQL。只有当你完全确信传入值来自可信内部系统、并且做过严格校验时，才适合用它。第二是引号和类型问题。字符串类型的列需要你手工加单引号，拼成"'A','B'"；数字列又不能用单引号包。明明是同一套报表模板，换一个列类型就得改 Java 拼接逻辑，这种维护成本会随着报表数量增长变得非常痛苦。
不过平心而论，$P!{}也不是一无是处。某些极端情况，比如 SQL 里需要动态替换的是一段完整的 AND 条件组合、或者一个动态排序字段，$X帮不上忙，这时候$P!{}反而是唯一解。我的经验是：能用$X解决的绝不碰$P!{}，$P!{}只留给真正需要全文本替换的场景。
3.2 另一种常见姿势：在 Java 里先把条件拼好
还有一种绕开 JasperReports 语法的做法，就是 Java 端先把 WHERE 子句完整拼好，作为参数传进去：
String condition = "city_id IN (101,102,103) AND status = 'PAID'"; params.put("condition", condition);SQL 写成：
SELECT * FROM order_info WHERE 1=1 AND $P!{condition}这种做法的优点是非常灵活，想拼什么拼什么；缺点是它把报表层的职责严重上移，条件逻辑全堆在 Java 里，模板基本退化成“直接执行一段传入 SQL”的空壳。项目初期看着方便，报表多了以后，每个报表的过滤逻辑都散落在不同的 Service 方法里，业务上要调整条件时，得改代码重新部署，而不是改模板，效率非常低。所以我的判断是：这个方案适合一次性的内部调度报表，不适合需要长期维护的业务报表体系。
3.3 数据库方言差异：Oracle 的 1000 上限
不管选$X还是$P!{}，只要底层是 Oracle，就绕不开一个问题：IN列表里的元素个数上限是 1000。超过 1000 个直接报ORA-01795: maximum number of expressions in a list is 1000。
处理思路有几种。如果集合来源是主键批次，优先把数据查询改为 JOIN 临时表的方式，绕开 IN 列表；如果确实必须用 IN，那就分片传参，比如把一个 3000 元素的 List 拆成 3 个 1000 元素的子列表，用col IN (第一片) OR col IN (第二片) OR col IN (第三片)。在 JasperReports 里实现分片，可以借助一个自定义函数或者直接在 Java 端把Condition拼出来再用$P!传进去，但更干净的做法是提前规划好主数据流，避免单张报表出现超过千级的动态列表。MySQL 没有 1000 这个硬限制，但过长的 IN 列表会影响解析和优化器的效率，所以即便在 MySQL 上也别太放飞。
4. 实操全流程：从新建参数到正式出报表
4.1 在 iReport / Jaspersoft Studio 里的具体步骤
如果你用的是 Jaspersoft Studio，完整操作流程是这样的：
- 打开 JRXML 报表文件，在左侧 Outline 面板里找到 Parameters 节点，右键选择 Create Parameter。
- 把参数名改成
cityIds，Parameter Class 选java.util.Collection。如果你更愿意用java.util.List也行，效果一样。 - 在属性面板的 Default Value Expression 里写
new java.util.ArrayList()。这一步不是必须的，但强烈建议写。它能让你在 iReport 自带的预览模式里不报空指针，也能保证空集合时的行为可控。 - 编辑查询语句，选中主数据集，把 SQL 粘贴到 Query Editor 里。用
$X{IN}写动态 IN 那个条件。 - 点击 Preview，在参数输入框里填值。要注意的是，这里不能直接输入
1,2,3这种字符串，因为 Collection 类型参数在预览界面里并不好直接手工录入。一个技巧是把默认值表达式临时改成java.util.Arrays.asList(1, 2, 3)，预览完再改回去。这一步是我做模板调试时最常用的办法，省得每次都去写 Java 测试类。
老版本 iReport 的操作路径类似，只是界面布局不一样，核心逻辑完全相同：建参数、选java.util.Collection、写$X{IN}、预览。
4.2 Java 端调用与动态值传入
模板设计好之后，Java 端的调用并不复杂，完整代码大概是：
public void exportReport(List<Integer> cityIds, OutputStream out) throws JRException { Map<String, Object> params = new HashMap<>(); params.put("cityIds", cityIds != null ? cityIds : Collections.emptyList()); try (Connection conn = dataSource.getConnection()) { JasperReport jasperReport = JasperCompileManager.compileReport(reportPath); JasperPrint jasperPrint = JasperFillManager.fillReport(jasperReport, params, conn); JasperExportManager.exportReportToPdfStream(jasperPrint, out); } catch (SQLException e) { throw new RuntimeException("获取数据库连接失败", e); } }这里有几个细节值得说：
Collections.emptyList()用于空集合兜底，配合$X{IN}的空集合恒真逻辑，就能实现“不选城市就查全部”。- 连接对象必须保持打开状态，
fillReport执行完再关闭；你要是提前把 Connection 关了，报表填充会直接抛SQLException。这个错我见过太多次了。 - 如果报表参数很多，建议把参数名常量收拢到一个常量类里，别在业务代码里裸写中文字符串。参数一多，拼写错误很难排查。
4.3 编译与部署中的经典坑
模板改完以后，记得在 Studio 里先 Build 一下，生成.jasper文件。很多人直接把.jrxml丢到服务器上，然后奇怪为什么改了没生效。JasperReports 运行时可以接受.jrxml并动态编译，但每次请求都重新编译，性能和稳定性都不划算。标准做法是发布前把.jasper编译产物和.jrxml源文件一起带上。
部署时还有个容易踩的坑：JRXML 里的 SQL 如果要动态拼接，必须确保整个查询被<![CDATA[]]>包裹。如果你忘了写 CDATA，SQL 里出现<或>符号时 XML 解析器会直接报错，比如时间比较条件create_date >= $P{startDate}里的>=就会莫名触发 XML 格式错误。所以新建查询模板时最先做的一件事，就是确认 CDATA 包裹完整。
5. 实战排查：常见报错与解决速查
5.1 一组高频报错对照表
把这类需求遇到过的高频问题整理成一张表，排查的时候对着看就行。
| 现象 | 原因 | 解决办法 |
|---|---|---|
预览或运行报<class> cannot be cast to java.util.Collection | Java 传参传的是String，比如"1,2,3" | 改成传List<Integer>或Set<Integer> |
SQL 执行报missing right parenthesis | 参数为空集合，且用了$P{}拼接 | 改用$X{IN}；或者给默认值new ArrayList() |
| 查出来数据为空，但 SQL 明明能查到 | 空集合传入后条件变成了恒真，再加上业务数据本身为空，或者集合元素类型和列类型不一致 | 用日志确认生成的 SQL；核对元素类型 |
| 字符串列查不到数据 | 手工拼$P!{}时忘记给字符串值加单引号 | 字符串集合一律交给$X{IN}处理 |
Oracle 报ORA-01795 | IN 列表超过 1000 个元素 | 拆分为多组 IN 用 OR 连接；或改用 JOIN 临时表 |
int[]数组传进去后参数始终为空 | 基本类型数组被Arrays.asList包装成了单元素 List | 用流式.boxed().collect(...)转成包装类型 List |
| 报表参数修改后不生效 | 服务器还在使用旧的.jasper缓存 | 重新编译并替换.jasper文件，重启相关服务 |
5.2 一条排查路径：先看日志里生成的 SQL
遇到疑难问题，最快的手段永远是看最终执行的 SQL 长什么样。在log4j或logback配置里，把net.sf.jasperreports.engine.query这个包名的日志级别调到DEBUG。这样报表填充时会把查询执行器拼接好的 SQL 打印出来。我排查过很多所谓“查不到数据”的问题，最后都发现是 SQL 里的参数值比自己以为的多了一对引号，或者日期参数格式化后与数据库的格式不一致。日志里看到的 SQL 是最终形态，比任何猜测都可靠。
另外，也可以在 Java 端临时用如下方式直接打印：
String sql = JasperCompileManager.compileReport(reportPath).getQuery().getText(); System.out.println(sql);把拼接前的模板 SQL 打出来看看$X和$P写法是否正确。配合日志里的最终 SQL，基本能定位九成问题。
5.3 排查时的几条记忆口诀
我自己在带新人时总结过几句口诀，在这里一并分享：
“IN 用$X，别用$P；传集合，别传串。”这是第一原则，任何IN需要动态赋值的地方，优先检查这两点。
“空集合，想清楚恒真还是恒假。”$X{IN}空集合生成恒真条件，意思是“查所有”；$X{NOT IN}空集合生成恒假条件，意思是“查不到数据”。业务要哪种，就得在模板层选对操作符。
“字符串列不加引号，数组记得转包装。”手工拼串方案里，引号永远是最容易出的错；基本类型数组必须转成包装类型 List 才能被$X正常展开。
这几条看起来简单，但每一条背后都对应着一种真实踩过的坑。报表开发里最花时间的往往不是写 SQL，而是这些边界条件和类型细节的处理。
5.4 性能层面的经验建议
动态 IN 在数据量不大时很灵活，但在报表主查询这种场景中一定要留意性能。IN 列表越长，数据库优化器需要评估的路径就越多。如果 IN 集合来自另一张表，通常被 JOIN 替代是更好的方案；如果集合来自应用层，可以考虑在传给报表前先做数量裁剪，比如限制最多勾选 500 项。
还有一个技巧是：不要在动态 IN 的条件列上直接对函数做运算，比如WHERE LOWER(code) IN (...)这种写法会杀掉索引。如果确实需要大小写不敏感，那就保证传入值的大小写规范，避免对列套函数。
6. 多值联动场景拓展
6.1 从固定参数到多选下拉控件
很多报表系统不止是 Java 端传参，还要在报表设计器里配置输入控件，让用户在预览或 Web 端自助选择多个值。这种场景下，输入控件的类型应选择Multi-Select Query或者Multi-Select List，数据源类型选 SQL，查询出可选值列表。输入控件的名称要和你报表里的 Collection 参数一致，最后运行时引擎会把多选值自动组装成 Collection 传给查询。
我当时做一个区域销售报表时，就是在 Studio 里建了一个返回全部区域的 SQL 数据源，再把输入控件和regionList参数绑定，模板 SQL 里用$X{IN}接收。这样用户在页面上勾选几个区域，报表就直接出这几个区域的数据，不需要写一行额外 Java 代码。配合刚才说的空集合恒真逻辑，用户不勾选时默认查全部，体验非常顺畅。
6.2 组合条件：多个 IN 同时存在
一个报表里出现多个动态 IN 也很常见，比如“选中几个区域 + 选中几种订单状态”。SQL 写法就是把两个$X{IN}同时放进去：
<queryString> <![CDATA[ SELECT * FROM order_info WHERE region_code IN ($X{IN, region_code, regionList}) AND status IN ($X{IN, status, statusList}) ]]> </queryString>这种写法的好处是每个条件互不干扰，参数名、Collection 类型各自独立，Java 端也只需要分别 put 两个 List 进去。要注意的是空集合和业务语义的对应关系——如果业务认为“状态没选就只查默认状态”，那就要在 Java 端判断空集合后补一个默认值，而不是依赖空集合查询全部。
6.3 数据量极大时的替代思路
最后补充一个大数据量场景的思考。如果某张报表要传的集合来自复杂规则计算，而且结果可能上万，那继续用 IN 列表已经不合适了。这种时候我会建议把集合先写入一张临时表，或者通过一个存储过程把筛选结果落到临时表，报表主查询改成 JOIN 临时表。这样既绕开了 Oracle 的 1000 个上限，也避免超长 SQL 带来的解析开销。虽然 JasperReports 语法解决不了 JOIN 的方案，但结合项目实际架构，这是比一味堆$X{IN}更稳妥的思路。
最后再分享一个小技巧：如果你经常要调试这类模板，建议在参数定义里统一加上默认值new ArrayList()，然后在预览里创建一个“测试用”的参数预设，里面用java.util.Arrays.asList填好示例值。这样以后每次改完 SQL，点一下预览就能立刻看到效果，不用反复走 Java 打包的流程。报表开发这个活儿，大多时候不是难在概念，而是难在日常一处处不起眼的边界上；把IN动态赋值这一关打通之后，很多组合查询的报表做起来都会顺手很多。
