在实际 Java 后端开发中处理海量数据查询是一个绕不开的挑战。很多开发者习惯性地使用ListT来接收数据库查询结果这在数据量不大时没有问题。然而当业务要求一次性导出几十万甚至上百万条记录时这种“全量加载到内存”的方式会瞬间成为性能瓶颈轻则导致长时间 GC 停顿重则直接引发OutOfMemoryError也就是我们常说的 OOM。这种问题在报表生成、数据同步、历史数据迁移等场景下尤为常见。MyBatis 作为 Java 生态中广泛使用的持久层框架除了提供便捷的 CRUD 映射也内置了应对大数据量查询的解决方案——流式查询。流式查询的核心思想是“边读边处理”它并非一次性将所有结果集加载到 JVM 内存中而是通过数据库驱动和框架的配合以“流”的形式逐条或分批将数据传递给应用程序进行处理从而将内存占用控制在极低的水平。理解并正确使用 MyBatis 的流式查询是避免因数据查询导致内存挤爆的关键技能。本文将深入探讨 MyBatis 流式查询的原理、两种核心实现方式Cursor接口与ResultHandler接口并通过对比分析帮助你根据实际场景做出合适的技术选型。1. 为什么“一行代码”就能挤爆内存在深入流式查询之前我们必须先理解传统查询方式的内存风险究竟从何而来。这并非 MyBatis 的缺陷而是由 JDBC 和常见编程模式共同决定的。1.1 传统查询的内存加载过程当你执行一个典型的 MyBatis 查询例如ListUser userList userMapper.selectAll();其背后的流程大致如下应用层调用MyBatis 执行器接收到查询请求。JDBC 执行通过PreparedStatement执行 SQL获取ResultSet。结果集全量加载默认情况下JDBC 驱动会将ResultSet中的所有数据一次性从数据库服务器通过网络传输到客户端即你的应用服务器并缓存在驱动层的内存中。ORM 映射MyBatis 遍历这个已缓存在本地的ResultSet为每一行数据创建实体对象如User对象并填充属性。集合封装所有创建好的对象被添加到一个ArrayList中。返回结果这个包含了所有数据的List被返回给调用者。问题就出在第 3 步和第 5 步。假设一条记录映射为对象后占用 1KB 内存查询 100 万条记录仅对象本身就需要约 1GB 的堆内存。这还不包括ArrayList内部数组的开销、字符串常量池的占用等。对于大多数配置为 2GB 或 4GB 堆内存的 JVM 来说这样一次查询就足以触发 Full GC甚至直接导致 OOM。1.2 OOM 的典型现象与排查当发生因大数据查询导致的 OOM 时通常会看到如下错误信息java.lang.OutOfMemoryError: Java heap space或者更具体的在 GC 日志中观察到老年代被迅速填满。使用 IntelliJ IDEA 或 Eclipse MAT 分析导出的heap dump文件.hprof 文件往往会发现某个ArrayList或HashMap对象占据了绝大部分内存其内部元素就是你的业务实体对象。这就是“一行代码挤爆内存”的直观证据——那行调用selectAll()或类似方法的代码。注意排查 OOM 时如果 .hprof 文件过大导致 IDE 无法打开可以尝试使用命令行工具jhatJDK 自带或功能更强的独立工具如 MAT 的独立版本进行分析。1.3 流式查询如何解决内存问题流式查询改变了上述流程的第 3 步。它通过配置让 JDBC 驱动以“流”的方式处理ResultSet。在这种模式下数据库端保持游标Cursor打开并等待客户端请求数据。驱动端不再缓存全部结果而是每次只从网络连接中读取有限条记录例如一次一行。应用端MyBatis 映射完一条数据后立即通过回调接口ResultHandler或迭代器Cursor将对象交给业务逻辑处理。处理完后该对象理论上就可以被垃圾回收如果未被其他引用持有内存得以释放。这样无论总数据量是 1 万条还是 1000 万条在应用服务器中同时存在于内存中的活动对象始终只有很少的一部分内存压力得以根本性缓解。2. 环境准备与依赖配置在开始编写流式查询代码之前需要确保你的项目环境正确配置。不同的数据库和 MyBatis 版本对流式查询的支持略有差异。2.1 项目与依赖要求首先你需要一个基于 Maven 或 Gradle 的 Java 项目。本文以 Maven 为例核心依赖如下1. MyBatis 依赖必须使用 MyBatis 3.4.1 及以上版本以获得对Cursor接口的稳定支持。建议使用较新版本。dependency groupIdorg.mybatis/groupId artifactIdmybatis/artifactId version3.5.10/version !-- 示例版本请使用最新稳定版 -- /dependency2. 数据库驱动以 MySQL 为例需要确保驱动版本支持流式读取。较新的版本通常都支持。dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version !-- 示例版本 -- !-- 注意对于 MySQL使用 com.mysql.cj.jdbc.Driver -- /dependency3. Spring Boot 集成可选如果你使用 Spring Boot可以通过mybatis-spring-boot-starter简化配置。dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.0/version !-- 示例版本 -- /dependency2.2 数据库连接配置关键参数流式查询能否生效严重依赖于 JDBC 连接的配置。必须在数据源配置中显式开启相关参数。对于 MySQL在application.yml或application.properties中配置数据源时需要添加关键的连接参数。spring: datasource: url: jdbc:mysql://localhost:3306/your_database?useSSLfalseserverTimezoneUTCuseCursorFetchtruedefaultFetchSize100 username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver关键参数解释useCursorFetchtrue这是启用 MySQL 流式查询服务端游标的关键参数。它告诉 MySQL 驱动使用Cursor方式逐条获取数据而不是默认的将全部结果加载到客户端内存。defaultFetchSize100设置默认的抓取大小。这个值不是一次传输的数据量上限而是一个提示值。设置为一个正整数如 100, 1000会促使驱动使用流式模式。注意如果设置为Integer.MIN_VALUE驱动会尝试以最逐行的方式流式传输但具体行为因驱动版本而异。对于 MySQL通常设置一个正整数值即可。对于 PostgreSQLspring: datasource: url: jdbc:postgresql://localhost:5432/your_database?defaultRowFetchSize100 username: postgres password: your_passwordPostgreSQL 驱动通常根据fetchSize参数决定是否使用流式查询。在代码中通过Statement.setFetchSize(50)设置或在连接 URL 中通过defaultRowFetchSize设置。警告不正确的连接参数是导致流式查询失效的最常见原因。务必根据数据库类型查阅官方驱动文档确认正确的参数名和值。2.3 示例数据模型与 Mapper为了后续演示我们定义一个简单的数据模型和 Mapper 接口。实体类User.javapublic class User { private Long id; private String name; private String email; private LocalDateTime createTime; // 省略构造函数、getter、setter和toString方法 }Mapper 接口UserMapper.javaMapper // 如果使用MyBatis-Spring集成 public interface UserMapper { // 传统查询方法 - 可能导致OOM ListUser selectAllUsers(); // 方法1返回Cursor的流式查询 CursorUser selectAllUsersStreamByCursor(); // 方法2使用ResultHandler的流式查询 void selectAllUsersStreamByHandler(ResultHandlerUser handler); }对应的 XML 映射文件UserMapper.xml?xml version1.0 encodingUTF-8 ? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespacecom.example.mapper.UserMapper select idselectAllUsers resultTypeUser SELECT id, name, email, create_time as createTime FROM user !-- 可能还有查询条件 -- /select !-- 流式查询Cursor方式resultType不变但MyBatis会特殊处理 -- select idselectAllUsersStreamByCursor resultTypeUser SELECT id, name, email, create_time as createTime FROM user /select !-- 流式查询ResultHandler方式不需要resultType通过parameterType指定处理器 -- select idselectAllUsersStreamByHandler resultTypeUser fetchSize100 SELECT id, name, email, create_time as createTime FROM user /select /mapper注意第二个和第三个查询在 SQL 层面看起来完全一样区别在于 Mapper 接口的返回类型和 XML 中的细微提示如fetchSize虽然它通常在驱动层配置更有效。3. 实现方式一使用 Cursor 接口Cursor接口是 MyBatis 3.4.1 引入的用于流式查询的官方方式。它实现了Iterable和Iterator接口允许你以类似迭代集合的方式遍历海量结果而无需一次性加载所有数据。3.1 Cursor 的基本用法首先在 Mapper 接口中定义返回CursorT的方法。CursorUser selectAllUsersStreamByCursor();对应的 XML 映射语句不需要特殊标签使用普通的select即可但确保 SQL 是正确的。在 Service 或 Controller 层你需要在一个数据库事务中打开并使用这个Cursor。这是因为流式查询依赖于一个打开的数据库连接和事务来保持游标有效。Service public class UserService { Autowired private UserMapper userMapper; Transactional // 关键必须在一个事务内操作Cursor public void processUsersWithCursor() { try (CursorUser cursor userMapper.selectAllUsersStreamByCursor()) { for (User user : cursor) { // 遍历Cursor // 处理每一条用户数据 processSingleUser(user); // 对象user在此次循环后如果没有被外部引用就可以被GC回收 } } catch (IOException e) { // Cursor实现了Closeable关闭时可能抛出IOException throw new RuntimeException(Error processing cursor, e); } // 事务结束后连接关闭游标也会被释放 } private void processSingleUser(User user) { // 模拟处理逻辑例如写入文件、发送消息、计算统计值等 System.out.println(Processing user: user.getName()); // 这里不要将user对象添加到外部的List中否则会失去流式意义 } }3.2 关键机制与原理事务边界Transactional注解至关重要。流式查询执行时MyBatis 会从连接池获取一个连接并执行查询。Cursor对象本身持有这个连接和对应的ResultSet。如果不在事务中方法执行完毕后MyBatis 可能会立即关闭连接导致Cursor无法读取后续数据甚至报错。事务保证了在整个遍历过程中连接始终有效。资源管理Cursor实现了Closeable接口因此使用try-with-resources语法是推荐做法。这能确保即使在遍历过程中发生异常数据库游标和连接也能被正确关闭避免资源泄漏。遍历过程for (User user : cursor)这行代码每次迭代时MyBatis 会通过 JDBC 驱动从数据库网络流中读取下一行或下一批取决于fetchSize数据将其映射为User对象然后返回。之前的User对象如果没有被强引用就会成为垃圾等待回收。3.3 使用 Cursor 的优缺点分析优点代码简洁使用方式与迭代普通集合 (List) 高度相似学习成本低。类型安全返回的是泛型CursorUser编译器能进行类型检查。易于集成可以方便地与 Java 8 Stream API 结合通过StreamSupport。缺点与注意事项强事务依赖必须在事务内使用这限制了其应用场景例如在非事务性的定时任务或异步处理中需要额外设计。连接占用时间长遍历百万级数据可能耗时很长这意味着一个数据库连接将被长时间占用可能影响连接池性能。需要评估对连接池max-active等参数的影响。无法在 Mapper 层直接复用Cursor作为返回值意味着数据处理逻辑遍历和消费必须紧跟在查询调用之后无法将Cursor传递给其他层进行灵活处理。4. 实现方式二使用 ResultHandler 接口ResultHandler是一个回调接口它允许你在 MyBatis 映射每一行结果时立即对其进行处理。这是 MyBatis 更早期、也更底层的流式查询支持方式。4.1 ResultHandler 的基本用法首先定义一个实现ResultHandlerT接口的类。通常我们使用匿名内部类或 Lambda 表达式。Mapper 接口定义void selectAllUsersStreamByHandler(ResultHandlerUser handler);注意方法返回类型是void结果通过回调接口传递。XML 映射文件与普通查询一样但可以显式设置fetchSize尽管驱动配置优先级更高。select idselectAllUsersStreamByHandler resultTypeUser fetchSize250 SELECT id, name, email, create_time as createTime FROM user /select在 Service 层调用Service public class UserService { Autowired private UserMapper userMapper; public void processUsersWithHandler() { // 不需要Transactional注解但查询执行过程本身仍在一个数据库会话中 userMapper.selectAllUsersStreamByHandler(new ResultHandlerUser() { Override public void handleResult(ResultContext? extends User resultContext) { User user resultContext.getResultObject(); // 处理单条数据 processSingleUser(user); // 可以通过resultContext控制是否继续处理 int count resultContext.getResultCount(); if (count 10000) { // 例如处理满10000条后主动停止 // resultContext.stop(); } } }); // 方法执行完毕连接会自动关闭 } // Java 8 可以使用Lambda表达式更简洁 public void processUsersWithHandlerLambda() { userMapper.selectAllUsersStreamByHandler(resultContext - { User user resultContext.getResultObject(); processSingleUser(user); }); } private void processSingleUser(User user) { System.out.println(Processing user: user.getName()); } }4.2 关键机制与原理回调模式MyBatis 在执行查询后不会将结果收集到列表而是为结果集的每一行调用一次handleResult方法。你在这个方法里拿到映射好的对象并立即处理。连接管理与Cursor不同使用ResultHandler时MyBatis 会在selectAllUsersStreamByHandler方法调用期间持有数据库连接并在方法返回前关闭连接。因此你通常不需要也不应该为这个方法添加Transactional除非它被嵌套在另一个需要事务的方法中。流程控制ResultContext对象提供了getResultCount()当前已处理的行数和stop()方法。你可以在处理一定数量数据后主动停止这在处理到满足条件的数据后提前退出时非常有用。线程模型handleResult方法是在执行查询的同一个线程中同步调用的。这意味着处理逻辑会阻塞数据库查询的推进。如果处理逻辑非常耗时整体执行时间会变长。4.3 使用 ResultHandler 的优缺点分析优点无事务约束不需要强制开启事务使用更灵活。连接占用可控连接在 Mapper 方法执行完毕后立即释放占用时间相对较短。可控制流程可以通过ResultContext.stop()提前终止处理。适用于复杂处理可以将处理逻辑封装在独立的ResultHandler实现类中实现更好的职责分离。缺点与注意事项代码侵入性稍强需要编写回调类或 Lambda代码结构与传统方式差异较大。异常处理如果handleResult方法中抛出异常整个查询和处理过程会中断需要做好异常捕获和处理。无法直接返回结果由于是回调模式处理结果无法像普通方法一样通过返回值传递。通常需要在外围准备一个收集器如写入文件、更新统计变量等。5. Cursor 与 ResultHandler 的对比与选型理解了两种方式的原理后我们可以从多个维度进行对比以便在实际项目中做出正确选择。特性维度CursorT接口ResultHandlerT接口代码风格声明式类似迭代集合更直观。命令式回调模式逻辑分散。事务要求必须在事务内使用。通常不需要事务由 MyBatis 管理连接会话。连接占用连接在整个遍历期间被占用时长与数据量和处理速度正相关。连接仅在 Mapper 方法执行期间被占用相对较短。资源管理需使用try-with-resources或手动关闭否则可能导致连接泄漏。由 MyBatis 自动管理连接关闭。流程控制可通过break终止循环控制力在消费者。可通过ResultContext.stop()终止控制力在处理器内部。结果传递返回Cursor对象可在方法间传递但受事务限制。无返回值结果通过回调即时消费难以传递。与 Stream API 集成容易集成StreamSupport.stream(cursor.spliterator(), false)。较难直接集成需要自行适配。适用场景需要在事务上下文中进行复杂遍历或希望以集合风格处理数据流。简单的逐行处理、数据导出、转换且不希望引入事务开销。性能影响长时间占用连接对连接池压力大。处理逻辑慢会拖慢整体。连接释放快。处理逻辑慢同样会拖慢整体但连接压力小。选型建议优先考虑ResultHandler如果你的场景只是简单的读取-处理如导出 CSV、数据清洗、发送消息并且处理逻辑可以写在一个地方ResultHandler是更轻量、约束更少的选择。它避免了事务的复杂性连接管理也更简单。当需要事务或灵活遍历时选择Cursor如果你的流式处理必须与其他数据库操作如更新状态在同一个事务中完成或者你希望将数据流传递给更上层的逻辑进行灵活控制例如结合业务规则进行过滤和分发那么Cursor是更好的选择。特别是与 Spring 的Transactional和 Java Stream API 结合时能写出非常清晰的代码。混合使用在某些复杂场景下也可以考虑混合使用。例如在一个事务方法内使用Cursor获取数据流然后对每条数据调用一个使用ResultHandler的 Mapper 方法进行子查询但这需要仔细设计以避免 N1 查询问题。6. 生产环境实践与常见问题排查将流式查询应用于生产环境除了正确使用 API还需要关注稳定性、性能和监控。6.1 配置清单与检查项在应用上线前请对照此清单进行检查检查项说明推荐做法数据库连接参数确保已正确启用流式模式。MySQL:useCursorFetchtruedefaultFetchSize100PostgreSQL: 在代码或URL中设置fetchSizeMyBatis 版本确保版本支持流式查询。 3.4.1数据库驱动版本旧版本驱动可能不支持或存在 Bug。使用较新的稳定版驱动。事务管理仅Cursor使用Cursor必须开启事务。在方法上添加Transactional。资源关闭必须关闭Cursor防止连接泄漏。使用try-with-resources语句。超时设置流式查询可能执行很久需调整超时。调整spring.datasource.hikari.connection-timeout或事务超时Transactional(timeout3600)。连接池配置长时间运行的流式查询会占用连接。适当增大连接池maximumPoolSize并监控连接使用情况。JVM 内存监控验证流式查询是否真的降低了内存占用。通过 JConsole、VisualVM 或 APM 工具观察 Old Gen 内存增长曲线。6.2 常见问题与排查路径即使配置正确在实际运行中也可能遇到问题。以下是典型的问题现象、原因及解决方案。问题现象可能原因排查步骤解决方案流式查询没有生效内存依然飙升1. 数据库连接参数未正确配置。2.fetchSize设置不正确如设为0或负值。3. 数据库驱动不支持或存在 Bug。1. 检查应用日志中打印的 JDBC URL。2. 在数据库监控中观察网络流量流式查询应是平稳持续流量而非瞬间高峰。3. 使用 JProfiler 等工具查看ArrayList或HashMap是否仍持有大量对象。1. 确认并修正连接参数。2. 将fetchSize设置为一个正整数值如 100-1000。3. 升级数据库驱动到最新稳定版。使用Cursor时报Connection is closed或游标错误1. 未在事务中使用Cursor。2. 事务提前结束如被标记为 rollback-only。3. 遍历Cursor的代码不在Transactional方法调用链中。1. 检查方法是否添加了Transactional。2. 检查事务传播行为确保流式查询在一个有效事务内执行。3. 查看日志中是否有异常导致事务回滚。1. 为使用Cursor的方法添加Transactional。2. 确保事务方法内没有抛出未捕获的异常。3. 考虑将遍历逻辑内嵌在事务方法中。流式查询速度非常慢1. 网络延迟高。2. 处理单条数据的逻辑 (processSingleUser) 太耗时阻塞了数据拉取。3. 数据库服务器端排序或过滤开销大。1. 监控数据库服务器和应用的 CPU、网络 IO。2. 分析processSingleUser方法的性能。3. 检查 SQL 语句是否有优化的空间如索引。1. 优化处理逻辑考虑异步或批量处理。2. 对 SQL 查询条件建立索引。3. 如果业务允许在数据库端进行一些预处理。内存泄漏即使使用流式查询内存仍缓慢增长1. 在ResultHandler.handleResult或Cursor迭代中将对象添加到了外部的全局集合中。2. 第三方库如某些 JSON 序列化工具、缓存框架无意中持有了对象引用。1. 审查代码确保没有在流式处理中积累数据。2. 使用内存分析工具查看堆积对象的 GC Root 路径。1. 修正代码确保处理完的对象及时解除引用。2. 检查并配置第三方库避免不必要的对象缓存。数据库连接池被耗尽多个流式查询并发执行每个都长时间占用一个连接。监控连接池活跃连接数看是否持续接近最大值。1. 增加连接池最大连接数是缓解非根治。2.优化限制流式查询的并发度或使用ResultHandler缩短连接占用时间。3. 优化查询和处-理逻辑减少单次查询耗时。6.3 性能优化建议合理设置fetchSize这个值不是越大越好。值太小会增加网络往返次数值太大则失去了流式的意义可能一次加载过多数据到驱动层内存。通常建议从 100 到 1000 开始测试根据网络延迟和处理速度找到一个平衡点。优化单条处理逻辑流式查询的整体速度受限于最慢的环节。如果processSingleUser方法中有 IO 操作如写文件、调用外部 API考虑引入批量写入或异步处理来提高吞吐量。使用索引确保流式查询的 SQL 语句使用了合适的索引避免全表扫描。即使内存问题解决了一个慢查询仍然会占用数据库资源很久。监控与告警对应用进行监控关注长时间运行的数据库查询、连接池使用率、JVM 内存变化等指标。设置合理的告警阈值。考虑分页的替代方案对于某些超大数据集如果业务允许有时采用“分段分页”根据自增ID或时间范围分段查询比单一流式查询更可控对数据库更友好。流式查询是 MyBatis 提供的一个强大工具能有效解决大数据量查询时的内存瓶颈。Cursor和ResultHandler两种方式各有适用场景核心在于理解其背后“边读边处理”的原理以及对数据库连接和事务的管理差异。正确配置数据库连接参数是生效的前提而将其应用于生产环境时则需要综合考虑事务、连接池、超时、监控和异常处理。避免 OOM 只是第一步构建一个稳定、高效的数据处理管道才是架构能力的体现。在下一篇中我们将探讨更复杂的场景例如在流式查询中嵌套其他数据库操作、与 Spring Batch 等批处理框架集成以及如何对流式查询进行单元测试。