1. 背景与应用场景
1.1 foreach 标签的基本概念
在 MyBatis 的映射语句中，foreach 标签提供了对集合类型参数的高效遍历能力，使得对多条数据的处理可以以模板化的方式进行。核心作用是将集合中的每个元素映射为一份可执行的 SQL 片段，从而支持批量操作、动态拼接以及复杂条件的构造。
关键点包括对集合、集合中的元素、索引以及分隔符等属性的灵活配置，能够将单条 SQL 变成多条拼接或多值构造，降低代码重复性并提升可维护性。
1.2 常见应用场景
在实际项目中，foreach 标签常用于实现大规模 IN 查询、批量插入、批量更新与删除等场景。批量执行的核心收益是显著减少数据库往返，降低网络开销，并利用 JDBC 的批处理能力提升吞吐量。
下面这段场景描述展现了 foreach 的典型用法：通过一个集合参数，将多条 VALUES 语句拼成一条批量插入 SQL，从而一次性写入多条记录。
<insert id="batchInsert" parameterType="java.util.List<com.example.User>" >INSERT INTO t_user (id, name, age)VALUES<if test="list != null && !list.isEmpty()" ><foreach collection="list" item="user" index="idx" separator=", " >(#{user.id}, #{user.name}, #{user.age})</foreach></if>
</insert>
2. 语法全解析
2.1 基本语法与属性
foreach 标签的核心属性包括 collection、item、index、open、close、separator。collection 指定待遍历的集合名称，item 是集合中当前遍历的元素变量，index 提供当前索引，open 与 close 用于包裹最终 SQL 字符串，separator 用于在元素之间插入分隔符。
通过组合这些属性，可以把任意集合映射为一段符合 SQL 语法的文本块，且在运行时根据具体数据动态拼装出最终可执行的语句。
2.2 数据结构与映射形式的差异
对于 List、数组、Set 以及 Map 等不同数据结构，foreach 的行为有微妙差异。集合类型的兼容性决定了 item 的取值方式，以及在复杂对象场景中对属性的访问路径。常见做法是将复杂对象作为 list 的元素，通过 #{item.property} 访问字段。
在某些场景下，使用 Map 作为 collection 时，item 能直接作为 key 或 value；此时需要明确映射表达式，例如 #{item.key} 或 #{item.value}，以确保参数正确绑定。
2.3 典型 XML 语法示例
下面的 XML 片段演示了对一个简单对象集合的逐项绑定与分隔符控制，是理解 foreach 语法的直观示例。
<update id="updateStatusBatch" parameterType="java.util.List<com.example.Order>" >UPDATE ordersSET status = CASE id<foreach collection="list" item="o" index="idx" open="" close="" separator="" >WHEN #{o.id} THEN #{o.status}</foreach>ENDWHERE id IN<foreach collection="list" item="o" index="idx" open="(" close=")" separator="," >#{o.id}</foreach>
</update>
3. 与批量操作的结合
3.1 批量插入的实现思路
批量插入本质是把多条 INSERT 的值片段拼接成一个大 SQL，使用 foreach 的 separator 将每条记录的值用逗号分开，从而一次性提交到数据库。优势在于减少重复语句和网络往返，提升整体吞吐。
在设计时应关注数据库对单条 SQL 的长度限制以及 JDBC 端的批量提交能力，必要时结合 MyBatis 的缓存策略与数据库连接池设置进行调优。
<insert id="batchInsertUsers" parameterType="java.util.List<com.example.User>" >INSERT INTO t_user (id, name, age)VALUES<foreach collection="list" item="u" index="i" separator=", " >(#{u.id}, #{u.name}, #{u.age})</foreach>
</insert>
3.2 批量更新与删除的场景
批量更新通常采用两种方式：一种是将多个键值对以 CASE WHEN 的方式打包，另一种则是通过 IN 子句定位目标记录再统一更新。前者适用于逐条字段更新，后者适合简单字段统一替换。
批量删除则常见于 DELETE FROM ... WHERE id IN (...) 的形式，借助 foreach 将待删除的主键列表展开为一个逗号分隔的列表。
<delete id="batchDeleteUsers" parameterType="java.util.List<Long>" >DELETE FROM t_userWHERE id IN<foreach collection="list" item="id" open="(" close=")" separator="," >#{id}</foreach>
</delete>
4. 性能优化要点
4.1 使用合适的批量提交设置
开启 JDBC 的批量提交能力，并通过 MyBatis 的参数配置实现合理的批量尺寸。批量尺寸（batchSize）过大可能导致 SQL 语句过长、内存压力增大，过小则无法充分利用数据库的吞吐能力。建议结合具体数据库的最大包长度和连接池的容量进行调优。
在 MyBatis 配置或开发阶段，应通过日志观察实际生成的 SQL 及参数绑定情况，确保没有额外的数据库游离语句。
4.2 数据结构与对象映射的效率
将数据模型设计为扁平化、避免深层嵌套，可以减少 foreach 遍历时的属性访问成本。使用简单 DTO 或轻量对象来承载批量参数，能够降低序列化/反序列化的开销。
此外，尽量避免在 foreach 内部执行复杂的计算或调用，从而保持 SQL 片段的可预测性与可缓存性。
4.3 避免重复 sql 与合理的缓存策略
重复生成的 SQL 语句会影响数据库缓存命中率，因此应将可复用的 SQL 模板与动态参数分离，避免不必要的字符串拼接。合理使用 MyBatis 缓存和数据源层的二级缓存，可以进一步提升重复查询的响应速度与并发性能。
对于频繁发生的批量操作，建议在应用端对参数集合进行分批次切分，以维持稳定的执行计划与数据库执行资源。
<update id="updateStatusesInBatch" parameterType="java.util.List<com.example.Order>" >UPDATE ordersSET status = CASE id<foreach collection="list" item="o" index="idx" open="" close="" separator="" >WHEN #{o.id} THEN #{o.status}</foreach>ENDWHERE id IN<foreach collection="list" item="o" index="idx" open="(" close=")" separator="," >#{o.id}</foreach>
</update>
5. 调试与故障排除
5.1 常见问题与排查要点
常见问题包括：参数未正确绑定、生成的 SQL 与数据库端兼容性不符、以及 分隔符与 open/close 的使用错误等。排查时应关注日志输出中的 bound 参数、实际执行的 SQL 绑定，以及 foreach 的集合长度与元素类型是否匹配。
通过开启 MyBatis 的日志级别到 DEBUG，能清晰看到动态 SQL 的拼接过程，帮助快速定位问题。同时，确保传入的集合不为 null，且每个元素具备必须的字段。
5.2 调试示例与排查建议
结合日志，可以在 foreach 使用的集合上添加边界检查，确保不会因为空集合而生成无效的 SQL。下面是一段常见的调试姿态：首先在调用处输出集合大小，其次在 MyBatis 侧开启 SQL 日志。
// 调用端示例
List<User> batch = fetchUsersForBatch();
if (batch == null || batch.isEmpty()) {// 处理逻辑
}
随后在配置中开启日志：
<configuration><settings><setting name="logImpl" value="STDOUT_LOGGING"/></settings>
</configuration>
