1. 先搞清楚“内存挤爆”和“流式查询”到底在说什么如果你在Java项目里处理过大量数据查询尤其是用MyBatis从数据库里拉取几十万、上百万条记录大概率遇到过内存溢出OOM的报错。问题往往不是出在SQL写得不对而是默认的查询方式会把所有结果一次性加载到JVM内存里。数据量一大内存瞬间就被撑满程序直接崩溃。“流式查询”就是解决这个问题的核心思路。它不像传统查询那样把整个结果集像倒水一样全灌进内存这个大水缸里。而是像接水管打开一个持续的数据流应用程序可以一条一条地、或者一小批一小批地从数据库服务器读取数据处理完一条就释放一条的内存。这样无论查询结果有多大程序的内存占用都能保持在一个相对稳定、可控的低水平。所以这篇文章要解决的就是当你用MyBatis执行一个可能返回海量数据的查询时如何避免程序被内存撑爆以及如何正确、高效地使用流式查询来安全地处理这些数据。这不仅仅是写一句SQL的事更涉及到JDBC驱动、MyBatis配置、资源管理和异常处理等一系列细节。下面我会从问题复现、原理、配置到实战避坑完整拆解一遍。2. 复现问题为什么一行查询代码就能让内存飙升在深入解决方案前我们先看看问题是怎么发生的。很多人是在压测或者处理生产环境历史数据时突然遭遇OOM却对原因一知半解。2.1 一个典型的内存“挤爆”场景假设你有一个简单的用户表里面有上千万条记录。你用MyBatis写了一个常见的查询!-- UserMapper.xml -- select idselectAllUsers resultTypecom.example.entity.User SELECT id, name, email FROM user /select然后在Service层调用ListUser allUsers userMapper.selectAllUsers(); for (User user : allUsers) { // 处理每一条用户数据比如写入文件、发送消息等 processUser(user); }当user表只有几百几千条数据时这段代码运行良好。但当数据量达到百万级ListUser allUsers这一行执行时MyBatis底层是JDBC会尝试把所有记录对应的User对象都实例化并放入这个List中。每个User对象都会占用堆内存百万个对象瞬间就可能吃掉几百MB甚至上GB的内存。如果堆内存设置比如-Xmx不够大或者同时有多个这样的查询在执行JVM就会抛出java.lang.OutOfMemoryError: Java heap space。2.2 默认行为背后的JDBC与MyBatis机制问题的根源在JDBC的ResultSet默认行为上。默认情况下JDBC驱动执行查询后会创建一个ResultSet对象。这个ResultSet可能采用“客户端游标”或“服务器端游标”的方式但很多驱动如MySQL Connector/J的默认配置下它会将整个结果集从数据库服务器传输到客户端JVM的内存中以便进行遍历、滚动等操作。MyBatis的默认执行器比如SimpleExecutor或ReuseExecutor在接收到这个ResultSet后会通过反射创建对象并调用ResultSet.next()遍历所有行将每一行数据映射为一个Java对象并添加到返回的List集合中。这个过程是一次性且阻塞的必须等所有数据都映射完成selectAllUsers方法才会返回那个巨大的List。关键点在于数据从数据库网络传输到JVM内存和对象在JVM堆内实例化这两个过程都是同步且占用大量内存的。你的processUser(user)循环还没开始内存可能就已经被数据占满了。2.3 不只是“大列表”还有隐形的内存消耗即使你聪明地想到了用分页查询LIMIT offset, size在深度分页offset非常大时数据库的性能会急剧下降需要扫描并跳过大量数据。而且如果你需要处理全量数据分页查询意味着多次网络往返和重复的SQL解析效率低下。另一种情况是复杂对象映射包含集合的collection或association一次查询可能触发N1问题或产生巨大的对象图内存消耗是指数级增长的。所以当你的需求是顺序处理大量数据且不需要在内存中同时持有所有数据时流式查询就成了必选项。它改变了数据加载的“节奏”从“批发”变成了“零售”。3. MyBatis流式查询的核心如何正确地“打开水龙头”理解了问题我们来看解决方案。MyBatis本身并不直接发明流式查询它是对JDBC流式结果集能力的一层封装和适配。实现流式查询关键在于配置MyBatis和编写对应的Mapper方法。3.1 基于ResultHandler的流式处理这是MyBatis原生支持的一种方式。你不需要让Mapper方法返回一个集合而是提供一个回调接口ResultHandler。MyBatis在从ResultSet中获取每行数据并映射成对象后会立即调用这个回调你可以在回调方法中处理当前对象然后丢弃它。首先在Mapper接口中定义方法// UserMapper.java void selectAllUsersStreaming(ResultHandlerUser handler);对应的XML映射文件!-- UserMapper.xml -- select idselectAllUsersStreaming fetchSize-2147483648 resultTypecom.example.entity.User SELECT id, name, email FROM user /select注意这里的fetchSize-2147483648。这个特殊的负数值Integer.MIN_VALUE是触发MySQL JDBC驱动使用流式结果集的关键。对于其他数据库如PostgreSQL可能需要设置fetchSize为一个正数如100并结合resultSetTypeFORWARD_ONLY。然后在Service层调用Autowired private UserMapper userMapper; public void processAllUsersStreaming() { userMapper.selectAllUsersStreaming(new ResultHandlerUser() { Override public void handleResult(ResultContext? extends User resultContext) { User user resultContext.getResultObject(); // 处理当前用户对象 processUser(user); // 可以在此处根据条件停止处理 // if (someCondition) { // resultContext.stop(); // } } }); }这种方式的核心优势内存友好对象是逐个或按fetchSize指定的小批次被创建、处理和GC回收的内存中同时存在的对象数量很少。控制灵活你可以在handleResult方法里随时调用resultContext.stop()来终止数据流的读取。需要注意的坑点连接必须保持打开在整个流式处理过程中数据库连接Connection是不能关闭的。这意味着你不能在方法上使用Transactional注解后让方法一结束就自动关闭连接。连接必须持续到ResultHandler回调结束。通常需要手动管理连接或使用编程式事务。超时设置因为处理可能很慢需要确保数据库和JDBC驱动侧的查询超时netTimeoutsocketTimeout设置得足够长否则连接可能被中断。Mapper方法返回类型为void数据通过回调消费方法本身不返回结果列表。3.2 基于CursorT接口的流式处理更现代的方式MyBatis 3.4.0及以上版本提供了CursorT接口它实现了IterableT使用起来更像Java 8的Stream更符合直觉。首先在Mapper接口中定义返回Cursor的方法// UserMapper.java CursorUser selectAllUsersCursor();XML映射文件同样需要设置fetchSize!-- UserMapper.xml -- select idselectAllUsersCursor fetchSize-2147483648 resultTypecom.example.entity.User SELECT id, name, email FROM user /select在Service层你可以用try-with-resources语法来使用Cursor确保资源被正确关闭public void processAllUsersCursor() { try (CursorUser userCursor userMapper.selectAllUsersCursor()) { for (User user : userCursor) { // 这里遍历时才开始真正从数据库拉取数据 processUser(user); } } catch (IOException e) { // Cursor的close方法会抛出IOException throw new RuntimeException(Error closing cursor, e); } }或者使用Java 8 Stream API进行函数式处理public void processAllUsersCursorWithStream() { try (CursorUser userCursor userMapper.selectAllUsersCursor()) { userCursor.forEach(user - processUser(user)); // 或者使用Stream转换 // userCursor.stream().map(...).filter(...).forEach(...); } catch (IOException e) { throw new RuntimeException(Error closing cursor, e); } }Cursor方式的优势语法更简洁使用标准的迭代器或Stream API代码更清晰。资源自动管理结合try-with-resources可以确保Cursor及其底层的ResultSet、Statement被正确关闭。与Spring事务集成更好在某些配置下Cursor可以在Spring管理的Transactional方法内工作因为Cursor的遍历会保持连接打开直到遍历结束。但这一点需要谨慎测试因为连接关闭时机依然很关键。Cursor方式的坑点必须在事务范围内使用与ResultHandler类似遍历Cursor时数据库连接必须有效。通常这意味着调用Cursor遍历的方法必须处于一个活跃的事务中并且这个事务的边界要覆盖整个遍历过程。如果方法上没有事务或者事务在遍历结束前就提交/关闭了连接你会得到“流式结果集已关闭”之类的错误。不能多次遍历Cursor和Iterator一样遍历一次就结束了。异常处理Cursor.close()会抛出IOException需要妥善处理。4. 流式查询的实战配置与深度避坑指南知道了两种基本用法不代表就能在生产环境稳定运行。流式查询把数据拉取的耗时从“一次性等待”变成了“长时间流水线”这引入了新的复杂性。4.1 数据库驱动与连接池的配置这是最容易出问题的一环。流式查询对JDBC驱动和连接池的行为非常敏感。1. JDBC驱动参数以MySQL为例useCursorFetchtrue这个参数有时需要显式设置在JDBC连接URL中如jdbc:mysql://localhost:3306/db?useCursorFetchtrue。它告诉驱动使用服务器端游标来支持fetchSize。但注意它可能与fetchSize-2147483648这种客户端流式模式有交互具体行为需测试。defaultFetchSize可以在连接属性中设置默认的fetchSize。netTimeoutForStreamingResultsMySQL驱动的一个参数用于设置流式结果读取时的网络超时。对于处理时间很长的流式查询必须将这个值设置得足够大或者设置为0表示无限等待否则连接会在数据传输中途超时断开。2. 连接池配置如HikariCP, Druid连接泄漏风险流式查询长时间占用连接。如果应用程序在遍历Cursor或处理ResultHandler时发生异常导致连接没有正确归还给连接池就会造成连接泄漏。必须确保在finally块或try-with-resources中关闭资源。连接超时connectionTimeout连接池等待获取连接的最大时间。如果所有连接都被流式查询长时间占用新的业务请求可能获取不到连接而超时。空闲超时idleTimeout与最大生命周期maxLifetime连接池可能会回收空闲时间过长的连接。一个流式查询如果处理速度很慢连接虽然被占用但可能被连接池误判为“空闲”而回收导致查询中断。需要根据流式查询的最长预计耗时调整这些超时时间或者为执行流式查询的线程使用独立的、配置更宽松的连接池。验证查询connectionTestQuery一些连接池会在连接被借用时执行一个简单的验证查询如SELECT 1。如果连接正在用于流式查询这个验证查询可能会干扰结果集的读取。可以考虑为流式查询禁用自动验证或者使用不会干扰的验证方式。配置示例HikariCP在application.yml中spring: datasource: hikari: connection-timeout: 30000 # 获取连接超时30秒 idle-timeout: 600000 # 空闲连接10分钟后才回收给流式查询留足时间 max-lifetime: 1800000 # 连接最大生命周期30分钟 connection-test-query: SELECT 1 # 简单的测试查询注意潜在干扰 # 可以考虑为特定数据源/场景配置更长的超时4.2 事务管理的边界问题这是流式查询在Spring环境中最大的挑战。核心矛盾是Spring的声明式事务Transactional通常在方法返回后提交事务并关闭连接但流式查询需要在方法返回后继续使用这个连接。解决方案编程式事务推荐用于复杂场景使用TransactionTemplate手动控制事务边界确保事务和连接在流式处理完成后再提交。Autowired private TransactionTemplate transactionTemplate; public void processWithStreamingInTransaction() { transactionTemplate.execute(status - { // 在这个回调内事务是活跃的 try (CursorUser cursor userMapper.selectAllUsersCursor()) { cursor.forEach(this::processUser); } catch (IOException e) { status.setRollbackOnly(); throw new RuntimeException(e); } // 方法返回时事务提交连接关闭 return null; }); }调整Transactional的范围将包含流式遍历的整个处理逻辑都放在一个Transactional方法中。确保遍历Cursor的循环在方法体内完成而不是在方法调用返回的Cursor上在方法体外遍历。Transactional // 事务涵盖整个方法 public void processInTransactionalMethod() { CursorUser cursor userMapper.selectAllUsersCursor(); // 获取Cursor // 必须在方法体内完成遍历 for (User user : cursor) { processUser(user); } // 遍历结束后cursor会自动关闭在finally中然后方法返回事务提交。 }注意如果processUser方法内部又涉及其他数据库操作需要注意事务传播行为。使用TransactionSynchronizationManager更底层的做法注册一个事务同步回调在事务完成后afterCompletion再去关闭流式查询相关的资源。但这比较复杂容易出错。绝对要避免的做法在一个Transactional方法中获取Cursor然后将这个Cursor返回给调用者。调用者拿到Cursor时原方法的事务已经结束连接已关闭遍历必然失败。在异步线程中处理Cursor而事务在主线程中已经结束。4.3 性能调优与监控流式查询不是银弹它用更长的连接持有时间换取了更低的内存消耗。需要关注新的性能指标数据库服务器压力流式查询会在服务器端保持游标打开占用数据库资源如线程、内存、锁。大量并发的流式查询可能拖慢数据库。需要监控数据库的“打开游标数”、“长时间运行查询”。网络流量虽然内存压力小了但数据是持续缓慢传输的网络连接会保持较长时间。要确保网络稳定避免包重传导致性能下降。应用端处理速度如果应用端processUser处理得很慢会成为整个流水线的瓶颈导致数据库结果集发送被阻塞。可以考虑使用有界队列和消费者线程池将数据读取IO密集型和业务处理可能是CPU密集型解耦。// 简化的生产者-消费者模型示例 Transactional public void streamWithProducerConsumer() { int queueCapacity 1000; BlockingQueueUser queue new LinkedBlockingQueue(queueCapacity); ExecutorService processorPool Executors.newFixedThreadPool(4); // 生产者线程从Cursor读取数据放入队列 CompletableFuture.runAsync(() - { try (CursorUser cursor userMapper.selectAllUsersCursor()) { cursor.forEach(user - { try { queue.put(user); // 阻塞直到队列有空间 } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new RuntimeException(e); } }); } catch (IOException e) { throw new RuntimeException(e); } finally { // 放入结束标志 queue.offer(new PoisonPillUser()); } }); // 消费者线程从队列取数据处理 ListCompletableFutureVoid futures new ArrayList(); for (int i 0; i 4; i) { futures.add(CompletableFuture.runAsync(() - { while (true) { try { User user queue.take(); if (user instanceof PoisonPillUser) { // 重新放入毒丸让其他消费者也能结束 queue.put(user); break; } processUser(user); } catch (InterruptedException e) { Thread.currentThread().interrupt(); break; } } }, processorPool)); } // 等待所有消费者完成 CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join(); processorPool.shutdown(); }这个模式更复杂但能更好地平衡IO和CPU并控制内存中待处理对象的数量队列容量。监控与熔断为流式查询操作添加超时监控。如果某个流式查询处理时间异常长应有机制能中断它例如调用Cursor.close()或中断线程释放数据库连接避免雪崩。5. 什么时候该用什么时候不该用流式查询流式查询是一个强大的工具但并非所有大数据量场景都适用。选择前先做判断。适合使用流式查询的场景数据导出将数据库中的海量记录导出到CSV、Excel文件或发送到消息队列。ETL过程将数据从源数据库读取经过转换后写入目标数据库或数据仓库。批量处理需要对每一行数据执行一个相对独立且耗时的操作如调用外部API、复杂计算。内存严格受限的环境例如在容器中运行堆内存设置较小。不适合使用流式查询的场景需要随机访问或多次遍历结果集流式查询是单向、一次性的。需要基于全量数据在内存中进行复杂计算、排序、分组比如计算所有用户的平均年龄、生成复杂的报表汇总。这类操作需要所有数据在内存中才能完成。查询结果集本身很小可能只有几百条记录用传统方式一次性加载更简单性能开销也更小。数据库连接资源非常紧张流式查询会长时间占用连接。如果系统并发很高连接池大小有限长时间占用的连接可能成为瓶颈。决策 checklist数据量是否真的很大例如超过10万条业务逻辑是否是顺序处理每一条数据且处理完一条后就不再需要它应用是否有足够的内存一次性加载所有数据如果没有是否有条件增加内存有时候加内存比改代码更经济你的数据库和中间件连接池是否支持并正确配置了流式查询你的团队是否理解和能处理流式查询带来的事务、连接管理复杂性如果前两个问题的答案是“是”那么流式查询就是一个值得认真考虑的技术选项。它把内存溢出的风险转化为了对连接管理、超时设置和资源监控的更高要求。理解这种转换是用好它的前提。