1. 从一次“诡异”的查询说起：为什么list.contains在 MyBatis 里不是你想的那样
那天下午，我正对着一个看似简单的需求挠头。后端接口接收一个用户ID列表List<Long> userIds，需要从数据库里查询出所有在这个列表中的用户信息。这太常见了，不就是个IN查询嘛。我熟练地在 MyBatis 的 XML 映射文件里写下了这样的 SQL：
<select id="selectUsersByIds" resultType="User"> SELECT * FROM user WHERE id IN <foreach collection="userIds" item="id" open="(" separator="," close=")"> #{id} </foreach> </select>看起来完美无缺。然而，测试同学跑过来告诉我：“这个接口传空列表[]的时候，查出来是空，没问题；但是如果不传这个参数（null），整个接口直接报 500 错误了。” 我一看日志，经典的MyBatisSystemException，嵌套的异常信息指向了 SQL 语法错误，生成的 SQL 片段变成了WHERE id IN，后面直接没了，导致 SQL 不完整。
这个问题让我意识到，在 MyBatis 的动态 SQL 世界里，处理集合参数，尤其是判断一个List是否包含有效元素，远不是调用一个list.contains()那么简单。我们面对的不是 Java 集合 API，而是 MyBatis 的 OGNL 表达式和动态 SQL 标签的混合体。直接写if test=“list != null and list.contains(xxx)”大概率会掉坑里。真正的需求是：如何安全、优雅地在 MyBatis 的动态 SQL 中，根据一个List参数是否为空、是否包含元素来动态构造WHERE条件。这背后涉及到参数传递、OGNL 表达式求值、动态 SQL 标签的嵌套使用，以及最重要的——对null集合和空集合的区分处理。这也是很多从 JPA 或原生 JDBC 转过来的开发者容易困惑的地方。
2. 核心困境解析：<foreach>的“软肋”与动态判断的缺失
MyBatis 的<foreach>标签是处理集合参数的利器，但它有一个默认的“坏脾气”：当传入的集合参数为null时，它会直接忽略整个标签内容，导致IN ()这样的片段消失，从而引发 SQL 语法错误。而一个空的集合（如new ArrayList<>()）经过<foreach>渲染后，会生成IN ()，这在大多数数据库（如 MySQL）中执行会返回空结果集，虽然语法正确但逻辑可能不符合预期（我们可能希望此时查询全部数据）。
所以，我们真正的目标是在使用<foreach>之前，先做一层“守卫判断”。这个判断逻辑需要满足：
- 判空：检查集合对象本身是否为
null。 - 判有元素：检查集合是否包含至少一个元素。
- 集成到动态 SQL：将上述判断与
<foreach>标签无缝结合，只在条件满足时才生成IN子句。
在 Java 代码里，这很简单：if (list != null && !list.isEmpty()) { ... }。但在 MyBatis 的 XML 里，我们需要使用 OGNL (Object-Graph Navigation Language) 表达式写在<if>标签的test属性中。这里就是第一个坑：OGNL 中判断集合是否为空，不能直接用!list.isEmpty()，更不能用list.contains()来间接判断非空。OGNL 有它自己的一套语法。
2.1 OGNL 表达式中的集合判断
在 MyBatis 的动态 SQLtest条件中，我们可以这样判断一个集合：
list != null: 判断对象引用是否为空。这是安全的起点。list.size() > 0: 这是最直观、最推荐的方式。size()是 JavaCollection接口的标准方法，OGNL 可以正确调用。!list.isEmpty():理论上可以，但强烈不推荐。虽然isEmpty()也是标准方法，但在某些 MyBatis 版本或特定的 OGNL 环境下，可能会遇到解析问题。为了最大的兼容性和可读性，使用size() > 0是更稳妥的选择。list:单独使用集合对象作为条件。这是一个容易被误解的写法。在 OGNL 中，一个非空集合对象本身会被求值为true。但是，请注意！如果list是null，这个表达式会抛出空指针异常，导致动态 SQL 判断出错。因此，绝对不能单独用list作为test的条件，必须结合!= null。
所以，一个安全的、判断集合是否有元素的 OGNL 表达式是：list != null and list.size() > 0。
注意：这里的关键是理解
test属性中的表达式是 OGNL，不是 Java 代码。你不能写list != null && !list.isEmpty()（虽然有时也能工作），OGNL 的逻辑运算符是and,or,not。
2.2 错误示范与后果分析
让我们看看几种常见的错误写法及其后果：
错误1：仅判断非空，不判断大小
<select id="selectByList" resultType="Demo"> SELECT * FROM demo_table <if test="idList != null"> WHERE id IN <foreach collection="idList" item="id" open="(" separator="," close=")"> #{id} </foreach> </if> </select>- 后果：当
idList是一个空列表[]时，<if>条件成立，<foreach>会生成WHERE id IN ()。在 MySQL 5.7+ 中，这会执行成功但返回空结果。在某些严格模式的数据库或版本中，这可能直接报语法错误。更重要的是，这通常不符合业务逻辑——空列表应该意味着“不限制”，返回所有数据，而不是返回空。
错误2：试图用contains判断存在性（偏离主题）
<if test="idList != null and idList.contains(someValue)">- 后果：这完全误解了需求。
list.contains(someValue)是检查集合中是否包含某个特定值。而我们当前的需求是判断集合本身是否有任何元素，这是两个完全不同的操作。前者用于构建诸如WHERE column = someValue的动态条件，后者用于决定是否启用IN子句。
错误3：参数名错误
<if test="ids != null and ids.size() > 0"> <foreach collection="userIds" ... >- 后果：
<if>判断的是ids，但<foreach>使用的collection属性是userIds。两者不一致，导致运行时 MyBatis 在userIds这个参数上可能找不到对应的值（除非你的接口参数使用了@Param(“userIds”)注解且恰好有个ids属性），最终抛出Parameter ‘userIds‘ not found异常。
3. 实战方案：构建健壮的动态 IN 查询
理解了核心问题后，我们来构建一个生产环境可用的方案。假设我们有一个 Mapper 接口方法：
List<User> selectUsersByIdList(@Param(“userIdList”) List<Long> userIdList);我们的目标是：当userIdList为null或空时，查询全部用户；当userIdList有元素时，查询 ID 在列表中的用户。
3.1 方案一：<if>+<foreach>标准组合
这是最清晰、最常用的写法。
<select id="selectUsersByIdList" resultType="User"> SELECT * FROM user <where> <if test="userIdList != null and userIdList.size() > 0"> id IN <foreach collection="userIdList" item="id" open="(" separator="," close=")"> #{id} </foreach> </if> <!-- 可以在这里添加其他动态条件，用 AND/OR 连接 --> </where> </select>关键点解析：
- 使用
<where>标签：它会智能地处理WHERE关键字。如果<where>标签内的所有条件都不成立，则不会生成WHERE子句；如果条件成立，它会自动去掉开头多余的AND或OR。这比手动写WHERE 1=1更优雅。 - 精确的 OGNL 判断：
test=“userIdList != null and userIdList.size() > 0”严格保证了只有非空且非空的集合才会进入条件块。 <foreach>的collection属性：必须与接口中@Param注解指定的名称（或参数名，如果编译时保留了参数名信息）完全一致，这里是“userIdList”。
这个方案的优点是直观、易于理解和维护。缺点是当userIdList为空时，查询的是全表数据，如果表很大，这可能是一个性能隐患，需要业务上确认是否可以接受。
3.2 方案二：使用<choose>进行多分支处理
如果业务逻辑更复杂，例如：空列表代表查询全部，null代表查询一个默认值（或抛出异常），有列表时进行IN查询。可以使用<choose>、<when>、<otherwise>标签。
<select id="selectUsersByIdList" resultType="User"> SELECT * FROM user <where> <choose> <when test="userIdList == null"> -- 当参数为null时，可以赋予一个默认条件，或者不添加条件（查全部） -- 例如：查询状态为激活的用户 status = 1 </when> <when test="userIdList.size() == 0"> -- 当参数为空列表时，查询全部，这里1=1保证语法正确，实际会被<where>标签优化掉 1 = 1 </when> <otherwise> -- 当参数既不为null也不为空列表时，执行IN查询 id IN <foreach collection="userIdList" item="id" open="(" separator="," close=")"> #{id} </foreach> </otherwise> </choose> </where> </select>这个方案提供了更精细的控制流，适合对null和空集合有不同业务含义的场景。
3.3 方案三：Java 层预处理（推荐用于复杂逻辑）
有时，将逻辑判断上移到 Java 层会使 XML 更简洁，也更容易进行单元测试。我们可以在调用 Mapper 方法前，对参数进行处理。
// Service 层 public List<User> getUsers(List<Long> idList) { // 如果idList为null或空，我们可能不想查询全部，而是返回空列表或抛出业务异常 if (idList == null || idList.isEmpty()) { return Collections.emptyList(); // 或 throw new BusinessException(“ID列表不能为空”); } // 这里还可以进行其他预处理，比如去重、排序、过滤无效ID等 List<Long> filteredIds = idList.stream().filter(id -> id != null && id > 0).distinct().collect(Collectors.toList()); if (filteredIds.isEmpty()) { return Collections.emptyList(); } // 调用Mapper，此时参数一定是非空且有有效元素的 return userMapper.selectUsersByIdList(filteredIds); } // Mapper XML 可以简化，甚至去掉<if>判断，因为Service层已经保证了 <select id="selectUsersByIdList" resultType="User"> SELECT * FROM user WHERE id IN <foreach collection="userIdList" item="id" open="(" separator="," close=")"> #{id} </foreach> </select>这个方案的优点是将业务逻辑（参数校验）与数据访问逻辑（SQL生成）分离，职责更清晰，XML 更干净，且避免了全表扫描的风险。缺点是增加了一层调用，对于简单的 CRUD 可能显得繁琐。
4. 进阶话题与避坑指南
4.1 超大列表 (IN子句长度限制)
IN子句中的元素数量，不同数据库有不同限制（例如，Oracle 早期版本有 1000 个的限制，MySQL 的max_allowed_packet也间接限制）。当传入的List非常大时（比如上万条），直接使用<foreach>拼接会导致 SQL 语句极长，性能下降，甚至触发数据库限制。
解决方案：分批查询。不要在 SQL 层面处理万级以上的IN列表。应该在 Java 服务层进行分批，多次调用 Mapper 方法，然后合并结果。或者，对于这种场景，考虑使用临时表关联或JOIN子查询（如果 ID 来自另一个查询结果）。
// 服务层分批处理示例 public List<User> getUsersByLargeIdList(List<Long> largeIdList) { List<User> result = new ArrayList<>(); int batchSize = 1000; // 根据数据库调整批次大小 List<List<Long>> batches = partitionList(largeIdList, batchSize); for (List<Long> batch : batches) { result.addAll(userMapper.selectUsersByIdList(batch)); } return result; }4.2 使用@Param注解明确参数名
这是一个至关重要的好习惯。在 Mapper 接口中，如果方法有多个参数，或者参数是Collection、List、Map等类型，务必使用@Param注解。
// 好习惯 List<User> selectByConditions(@Param(“name”) String name, @Param(“statusList”) List<Integer> statusList); // 在XML中，可以使用明确的名称 <if test=“statusList != null and statusList.size() > 0”> <foreach collection=“statusList” ...>如果不使用@Param，在 MyBatis 中你需要通过_parameter、param1、param2这样的默认名称来访问，这非常不直观且容易出错。
4.3<foreach>中的index属性
<foreach>除了item，还有一个index属性，代表当前迭代的索引（对于List或数组）或键（对于Map）。这在某些特定场景下有用，比如需要生成id=1 OR id=2这样的条件时。
<foreach collection=“idList” item=“id” index=“index” open=“(“ separator=“ OR ” close=“)”> id = #{id} </foreach>但请注意，index在 OGNL 表达式中使用时，需要根据上下文判断其类型（整数或字符串）。
4.4 关于list作为默认参数名
如果你的接口方法只有一个List类型的参数，并且没有使用@Param注解，那么在 XML 中，你可以使用list作为默认的集合参数名。
List<User> selectUsersByIdList(List<Long> userIdList); // 单参数，无@Param<if test=“list != null and list.size() > 0”> <foreach collection=“list” item=“id” ...>但是，我强烈反对这种写法。它使得 XML 与 Java 接口的耦合变得隐晦，可读性差，尤其是在方法重构或添加参数时极易出错。始终使用@Param赋予一个明确的名称是最佳实践。
4.5 调试动态 SQL
当动态 SQL 没有按预期工作时，如何调试？首先，开启 MyBatis 的 SQL 日志。在application.yml(Spring Boot) 中配置：
logging: level: com.xxx.mapper: debug # 将你的Mapper包路径设为debug级别或者使用 MyBatis 原生配置<setting name=“logImpl” value=“STDOUT_LOGGING”/>。
查看日志中打印出的最终 SQL 语句和参数，这是定位动态 SQL 问题的第一步。你会发现IN ()问题、条件未生效问题等一目了然。
5. 总结与最佳实践选择
回到我们最初的问题：“MyBatis 动态 SQL 判断 List Contains”。经过上面的拆解，我们应该清晰地认识到，这里的“Contains”并非指List.contains(Object)方法，而是指判断一个List集合参数是否包含有效元素，以便决定是否生成IN查询子句。
我的最佳实践建议如下：
- 首选方案一（
<if>+<foreach>）：对于大多数“有值则过滤，无值则不过滤”的查询场景，这是最平衡和通用的选择。结合<where>标签使用，干净利落。 - 明确业务含义：与产品经理或前端确认，
null和空列表[]在业务上是否代表相同的含义（通常应该代表“无限制”）。如果不同，采用方案二（<choose>）或方案三（Java层预处理）。 - 强制使用
@Param注解：为所有非简单类型的 Mapper 方法参数（特别是集合）添加@Param注解，让 XML 中的引用清晰无误。 - 警惕全表扫描：当
IN条件不生效时，你的 SQL 可能会退化为全表扫描。务必评估表数据量，如果数据量大，考虑在业务层拦截空参数，或者为查询添加其他必选条件（如时间范围、状态等）来限制结果集。 - 处理超大列表：对于可能传入大量 ID 的接口，在设计之初就要考虑分批策略或改用其他查询模式（如临时表），不要依赖动态 SQL 去拼接超长的
IN语句。
最后，记住 MyBatis 动态 SQL 的核心思想是“字符串拼接”。我们写的标签和表达式，最终都是为了生成一条合法的、符合业务逻辑的 SQL 字符串。理解 OGNL 的表达能力，清楚每个标签（<if>,<where>,<foreach>,<choose>）的渲染规则，就能组合出强大而稳健的动态查询，轻松应对List参数带来的各种边界情况。
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
