1. 项目概述当MyBatis遇上千万级数据做后端开发尤其是处理数据报表、数据导出或者大数据量分析的场景你肯定遇到过这样的头疼时刻一个查询需要返回几十万甚至上百万条记录。如果直接用传统的ListT一次性加载到内存轻则接口响应缓慢内存飙升重则直接OutOfMemoryError服务挂掉。这时候MyBatis的流式查询Streaming Query就成了你的救命稻草。它允许你像打开一个水龙头一样从数据库里“流式”地、一条一条地获取数据而不是把整桶水都先搬到内存里。今天我就结合自己处理千万级数据导出的实战经验来彻底拆解MyBatis流式查询的原理、实现、坑点以及最佳实践。无论你是想优化现有的大数据查询接口还是为即将到来的海量数据处理做准备这篇内容都能给你一套可直接落地的方案。2. 流式查询的核心原理与为什么需要它2.1 传统查询的瓶颈全量加载之痛在深入流式查询之前我们必须先搞清楚传统方式为什么不行。当我们执行一个典型的MyBatis查询例如select idselectLargeData resultTypecom.example.User SELECT id, name, email FROM user WHERE create_time #{startTime} /select对应的Mapper接口方法返回一个ListUser。MyBatis或者说底层的JDBC驱动在执行这个查询时其默认行为是一次性将所有匹配的结果集从数据库服务器通过网络传输到应用服务器的内存中并封装成完整的List对象。这个过程存在几个致命问题内存压力假设一条User记录在内存中占用1KB1000万条数据就是约10GB。JVM堆内存很可能无法容纳直接导致OOM。网络与数据库压力数据库需要一次性准备并发送整个结果集这期间会长时间占用数据库连接和网络带宽可能导致数据库响应变慢影响其他查询。响应延迟应用必须等待所有数据都传输、反序列化完成后才能开始处理并返回给客户端。用户会经历漫长的等待体验极差。2.2 流式查询的工作机制细水长流流式查询改变了这个范式。它的核心思想是保持数据库游标Cursor打开然后让应用像迭代器Iterator一样一次从游标中获取一条或一小批记录进行处理处理完一条就丢弃一条或批量处理内存中始终只保持少量数据。其背后的技术栈是JDBC层面通过Statement.setFetchSize(Integer.MIN_VALUE)MySQL驱动或使用ResultSet.TYPE_FORWARD_ONLY和CONCUR_READ_ONLY模式并设置合适的fetchSize来告诉驱动我们想要流式获取结果。MyBatis层面提供了CursorT接口作为流式查询的返回类型。Cursor实现了IterableT和IteratorT你可以像遍历普通集合一样遍历它但每次next()调用才会驱动JDBC从网络连接中获取下一条数据。数据库层面以MySQL为例当使用流式结果集时数据库服务器会保持结果集和相关的连接、资源处于打开状态等待客户端逐条请求数据。关键区别类比传统查询就像点外卖餐厅数据库必须把所有菜数据都做好、打包好骑手网络一次性全部送到你家内存你才能开始吃。流式查询就像吃回转寿司厨师数据库不断地把做好的寿司数据放在传送带连接上你应用坐在旁边看到想吃需要处理的就拿下来吃完盘子就被收走内存释放。你永远不需要同时拥有所有的寿司。2.3 哪些场景必须使用流式查询不是所有查询都需要流式。引入流式查询会带来额外的复杂性如事务和连接管理。判断标准很简单数据量极大无法一次性装入内存这是最直接的信号。当你预计查询结果在数万条以上且每条记录字段较多、体积较大时就应该考虑流式。需要逐条或分批处理且处理逻辑可独立例如数据导出为CSV/Excel文件、数据清洗后写入另一个存储系统如Elasticsearch、另一个数据库、实时计算统计指标等。处理完的数据可以立即丢弃或转移。需要提供实时或渐进式响应比如一个大型报表生成你可以边查询边生成文件并即时提供下载链接或者通过WebSocket分批推送数据到前端提升用户体验。注意流式查询并非为了提升“查询速度”。实际上由于需要保持连接和游标整个处理过程的总耗时可能比一次性获取更长。它的核心价值在于用时间换空间以及提供渐进式处理的能力避免内存瓶颈。3. MyBatis流式查询的三种实现方式与选型MyBatis提供了不止一种方式来实现流式查询每种方式各有优劣和适用场景。理解它们之间的区别是正确选型的关键。3.1 方式一使用CursorT接口推荐这是MyBatis官方最直接、最现代的支持方式。你只需要将Mapper方法的返回值定义为CursorT类型。定义Mapper接口import org.apache.ibatis.cursor.Cursor; public interface UserMapper { CursorUser selectLargeDataStream(Param(startTime) Date startTime); }编写XML映射select idselectLargeDataStream resultTypecom.example.User SELECT id, name, email, create_time FROM user WHERE create_time #{startTime} ORDER BY id !-- 流式查询强烈建议排序保证顺序和可重复性 -- /select服务层调用与遍历Service Transactional // 事务至关重要 public class DataExportService { Autowired private UserMapper userMapper; public void exportLargeData(Date startTime, OutputStream outputStream) { try (CursorUser cursor userMapper.selectLargeDataStream(startTime)) { CSVWriter writer new CSVWriter(new OutputStreamWriter(outputStream)); // 写入表头 writer.writeNext(new String[]{ID, Name, Email, Create Time}); for (User user : cursor) { // 这里开始逐条遍历触发数据获取 // 处理每条数据例如写入CSV writer.writeNext(new String[]{ String.valueOf(user.getId()), user.getName(), user.getEmail(), user.getCreateTime().toString() }); // 可选每处理1000条刷新一次输出流避免内存堆积 if (cursor.getCurrentIndex() % 1000 0) { writer.flush(); } } writer.flush(); } catch (IOException e) { throw new RuntimeException(导出失败, e); } // Cursor在try-with-resources中会自动关闭确保资源释放 } }为什么推荐这种方式语义清晰CursorT类型明确表达了“这是一个流式查询”。资源管理方便Cursor实现了AutoCloseable配合try-with-resources语法可以确保数据库游标和连接被正确关闭避免资源泄漏。与Spring事务集成好在Transactional注解的方法内使用可以确保在整个遍历过程中数据库连接和事务保持一致。3.2 方式二使用ResultHandler更底层控制ResultHandler是一个回调接口。MyBatis在从数据库获取到每一行结果时都会调用这个接口的handleResult方法。这种方式将处理逻辑完全交给开发者控制粒度最细。定义ResultHandlerimport org.apache.ibatis.session.ResultHandler; public class UserExportResultHandler implements ResultHandlerUser { private final CSVWriter writer; private int count 0; public UserExportResultHandler(CSVWriter writer) { this.writer writer; writer.writeNext(new String[]{ID, Name, Email}); } Override public void handleResult(ResultContext? extends User resultContext) { User user resultContext.getResultObject(); // 处理单条记录 writer.writeNext(new String[]{ String.valueOf(user.getId()), user.getName(), user.getEmail() }); count; if (count % 1000 0) { writer.flush(); } // 你甚至可以根据条件停止处理 // if (count 10000) { // resultContext.stop(); // } } public int getCount() { return count; } }Mapper接口和XML定义Mapper接口方法返回值为void并增加ResultHandler参数。public interface UserMapper { void selectLargeDataWithHandler(Param(startTime) Date startTime, ResultHandlerUser handler); }XML映射文件不需要特殊改动和普通查询一样。服务层调用Service Transactional public class DataExportServiceV2 { Autowired private UserMapper userMapper; public void exportLargeData(Date startTime, OutputStream outputStream) throws IOException { try (CSVWriter writer new CSVWriter(new OutputStreamWriter(outputStream))) { UserExportResultHandler handler new UserExportResultHandler(writer); // 执行查询结果将通过handler处理 userMapper.selectLargeDataWithHandler(startTime, handler); writer.flush(); System.out.println(共处理数据: handler.getCount() 条); } } }适用场景与注意事项优点绝对的控制权可以在处理每条数据时做任何事甚至可以中途停止resultContext.stop()。缺点代码更复杂需要自己创建和管理ResultHandler实例。资源关闭的逻辑也需要更小心主要关闭SqlSession。适用当你需要对结果集进行非常复杂的、有状态的逐行处理时。3.3 方式三自定义ExecutorType为REUSE或BATCH误区澄清网上有些资料会提到在SqlSession上设置ExecutorType为REUSE或BATCH来实现“流式”或“批量”效果。这里必须澄清一个常见的误区ExecutorType.SIMPLE默认执行器。每次执行完语句就关闭Statement对象。ExecutorType.REUSE复用Statement对象。对于同一模式的SQL例如多次插入不同参数可以复用预编译的Statement提升效率。但它不改变结果集的获取方式。ExecutorType.BATCH批处理执行器。将多个更新操作INSERT, UPDATE, DELETE攒在一起一次性发送给数据库大幅提升批量写入性能。它只针对更新语句对SELECT查询无效。结论ExecutorType主要用于优化写入性能无法实现SELECT查询的流式读取。流式查询的核心在于对ResultSet的处理方式而不是Statement的执行方式。实现流式查询必须依靠Cursor或ResultHandler或者在JDBC层面直接设置fetchSize。3.4 选型决策指南特性CursorT方式ResultHandler方式易用性高。符合Java迭代器习惯代码简洁。中。需要实现回调接口代码稍显分散。控制粒度中。可以逐条处理也能获取当前索引。高。可以访问ResultContext能中途停止、跳过。资源管理优。支持try-with-resources自动关闭。需注意。需要在正确的作用域内确保SqlSession关闭。与Spring集成优。在Transactional中工作良好。良。同样需要事务上下文。推荐场景绝大多数流式查询场景如数据导出、批量转换。需要精细控制处理流程或提前终止的场景。对于90%的开发者首选CursorT方式。它平衡了易用性、安全性和功能性。4. 流式查询的实战配置、陷阱与深度优化知道怎么用只是第一步用得好、不出错才是关键。这部分是真正的干货来自大量实战踩坑后的总结。4.1 强制要求事务管理与连接持有这是流式查询最核心、也最容易出错的地方。流式查询的本质是保持一个数据库游标打开。而游标是依附于数据库连接Connection和事务Transaction的。错误示范// 没有事务注解 public void exportData() { CursorUser cursor userMapper.selectLargeDataStream(...); // 遍历cursor... // 问题方法执行过程中MyBatis可能会在每次cursor.next()时从连接池获取新连接 // 导致游标所在的连接被关闭抛出 Connection is closed 异常。 }正确做法必须确保整个遍历过程在一个数据库事务内从而保证始终使用同一个物理连接。Service public class ExportService { Transactional // 关键确保方法在一个事务内执行 public void exportWithTransaction() { try (CursorUser cursor mapper.selectLargeDataStream(...)) { for (User u : cursor) { // 处理数据 } } } }为什么Transactional会为这个方法创建一个事务上下文。Spring会为此上下文绑定一个独立的数据库连接。在整个方法执行期间所有数据库操作包括Cursor的遍历都使用这个连接游标得以保持。连接池注意事项常用的连接池如HikariCP、Druid都有连接回收机制。如果没有事务保护连接可能在Cursor未关闭时就被回收到池中造成状态混乱。事务阻止了连接被提前归还。4.2 数据库驱动与FetchSize的奥秘流式查询的行为高度依赖于JDBC驱动的实现。不同数据库、不同驱动版本配置可能不同。1. MySQL (mysql-connector-java)经典方式Statement.setFetchSize(Integer.MIN_VALUE)。这是告诉MySQL驱动使用流式结果集的“魔法值”。在MyBatis中可以通过在Mapper XML的select标签里配置fetchSize属性来实现。select idselectLargeDataStream fetchSize-2147483648 resultType... SELECT ... /select驱动版本的影响在较新的驱动版本如8.x中仅设置fetchSize为负值可能还不够。你可能还需要在JDBC连接字符串中显式指定使用流式读取spring.datasource.urljdbc:mysql://localhost:3306/db?useCursorFetchtrue设置useCursorFetchtrue后fetchSize的正值表示每次从服务器获取的行数实现了“客户端游标”式的分批流式获取对服务器更友好。2. PostgreSQLPostgreSQL的驱动对流式支持很好。通常只需要设置一个合理的正数fetchSize即可。select idselectLargeDataStream fetchSize1000 resultType... SELECT ... /select这里fetchSize1000意味着每次网络往返从服务器获取1000条记录。这是一个平衡内存和网络开销的常用值。3. OracleOracle JDBC驱动默认就是流式的fetchSize默认是10。对于海量数据你可以根据情况调大fetchSize比如5000来减少网络通信次数但要注意客户端内存。实操心得fetchSize没有银弹。Integer.MIN_VALUEMySQL流式或一个较小的正数如1000是安全的起点。对于超大数据量可以尝试调大fetchSize以减少网络延迟的影响但务必在测试环境中监控客户端内存使用。一定要查阅你所使用数据库驱动的最新官方文档。4.3 SQL语句的编写禁忌不是所有SQL都适合流式查询。必须排序ORDER BY流式处理通常意味着顺序处理。如果没有ORDER BY数据库可能以任意顺序返回数据。在多批次处理或中断重试时可能导致数据重复或丢失。强烈建议使用一个唯一或递增的字段如主键ID、创建时间进行排序。避免大字段BLOB, TEXT, CLOB流式查询解决的是“行数多”的问题而不是“单行数据大”的问题。如果单行记录包含一个几十MB的BLOB字段即使只流式获取一行也可能撑爆内存。对于包含大字段的表考虑分两次查询或者使用数据库特定的流式读取大对象API。使用覆盖索引确保你的WHERE条件和ORDER BY字段能被索引覆盖。流式查询虽然减轻了客户端压力但数据库服务器仍然需要执行完整的查询。一个全表扫描的流式查询对数据库同样是灾难。使用EXPLAIN分析你的SQL。4.4 资源泄漏你必须关闭CursorCursor背后是打开的数据库ResultSet和Statement。如果不关闭就会导致数据库游标泄漏消耗服务器资源。数据库连接无法及时释放回连接池可能导致连接池耗尽。关闭的最佳实践// 正确做法1: try-with-resources (Java 7) try (CursorUser cursor userMapper.selectLargeDataStream(...)) { for (User user : cursor) { // process } } // 无论是否异常cursor都会自动关闭 // 正确做法2: 在finally块中手动关闭 CursorUser cursor null; try { cursor userMapper.selectLargeDataStream(...); // ... 遍历处理 } finally { if (cursor ! null !cursor.isClosed()) { cursor.close(); } }绝对不要在遍历到一半时直接return而不关闭Cursor。4.5 超时与中断处理流式查询可能运行很长时间。你需要考虑超时和用户中断。查询超时可以在MyBatis的select标签中设置timeout属性单位秒或者在数据源连接字符串中配置socketTimeout。select idselectLargeDataStream timeout300 ... !-- 5分钟超时 --事务超时如果你使用了Spring的Transactional可以设置事务超时Transactional(timeout 300)。注意这个超时是从事务开始算起如果事务中还做了其他操作需要留有余地。用户中断在Web应用中如果用户取消了导出请求你需要有能力停止正在进行的流式查询。这通常需要将Cursor的遍历放在一个可中断的线程中。提供一个取消接口该接口设置一个中断标志。在遍历循环中定期检查这个中断标志如果被中断则调用cursor.close()并退出。 这是一个相对高级的特性需要结合具体的应用框架如Spring MVC的DeferredResult来实现。5. 性能调优与监控让千万级查询飞起来处理千万级数据光有流式查询还不够需要一套组合拳。5.1 分页 vs 流式查询如何选择很多人面对大数据查询第一反应是“分页”。但分页在处理超大数据量时存在严重问题深度分页性能极差LIMIT 1000000, 100这种查询数据库需要先扫描并跳过前100万条记录成本极高。数据一致性风险如果数据在分页过程中被增删可能导致某一页数据重复或丢失。决策指南使用流式查询当你的目的是处理全部数据如导出、ETL、计算总和且不需要将全部数据同时呈现给用户时。使用分页当你的目的是在UI上展示数据且用户只需要浏览其中一部分时。对于深度分页应使用“游标分页”或“seek method”即WHERE id last_id LIMIT 100利用索引避免偏移。两者结合有时可以先用流式查询处理数据将处理结果如聚合后的统计信息、生成的文件存储起来再通过分页提供给用户查看。这是非常成熟的架构模式。5.2 应用层批处理减少I/O开销即使使用流式查询逐条获取如果逐条写入文件或调用远程接口I/O效率也会极低。优化在应用层做批处理。try (CursorUser cursor userMapper.selectLargeDataStream(...)) { ListUser buffer new ArrayList(BATCH_SIZE); // 例如 BATCH_SIZE 1000 for (User user : cursor) { buffer.add(user); if (buffer.size() BATCH_SIZE) { // 批量处理写入文件、插入ES、发送消息等 batchWriteToCSV(buffer, writer); buffer.clear(); writer.flush(); // 定期刷新输出流 } } // 处理最后一批不满 BATCH_SIZE 的数据 if (!buffer.isEmpty()) { batchWriteToCSV(buffer, writer); } }通过内存缓冲区积累一定数量的记录后再进行批量I/O操作可以大幅减少系统调用或网络请求的次数提升整体吞吐量。5.3 JVM内存与GC优化流式查询的目标是降低内存压力但如果处理逻辑不当仍然可能引起GC问题。避免在遍历中积累数据最忌讳在遍历Cursor时又将所有数据添加到一个新的ArrayList中这就失去了流式的意义。及时释放对象引用对于每一条处理完的记录确保没有全局的或长时间存活的对象引用它。让垃圾回收器可以及时回收。调整JVM参数虽然流式查询降低了堆内存需求但频繁创建和丢弃大量短期对象User对象可能加剧Young GC。可以适当调整新生代大小-Xmn并考虑使用G1或ZGC这类低延迟垃圾收集器来应对这种“高分配速率”的场景。5.4 数据库层面的配合优化只查询需要的字段SELECT *是万恶之源。明确列出需要的字段减少网络传输和内存占用。使用只读事务对于纯粹的导出查询可以在Spring事务中设置只读属性Transactional(readOnly true)。这会给数据库一个提示可能触发一些优化。从库查询如果业务允许将这类消耗资源的分析型、导出型查询路由到只读从库避免影响主库的OLTP事务性能。6. 常见问题排查与实战案例实录这里记录了几个我在实际项目中遇到的典型问题及其解决方案。6.1 问题一遍历Cursor时抛出“Connection is closed”异常现象在for (User user : cursor)循环中处理到一部分数据后突然抛出异常提示数据库连接已关闭。根因分析缺少事务这是最常见的原因。没有Transactional注解MyBatis可能在使用完一次连接后比如执行完Mapper方法就将其归还给连接池。当遍历Cursor需要再次读取数据时使用的可能已经是另一个连接。事务传播行为不当如果方法被另一个没有事务的方法调用且事务传播行为是REQUIRED默认则不会开启新事务。需要检查调用链。连接池超时连接池如Druid设置了removeAbandonedTimeout或idleTimeout长时间未归还的连接被强制回收。流式查询耗时过长触发了这个机制。解决方案确保流式查询的整个遍历过程在一个Transactional方法内。检查并调大连接池的超时参数确保其大于流式查询处理的最大预估时间。对于超长任务考虑将连接池的testOnBorrow或validationQuery属性打开确保取出的连接是有效的。6.2 问题二流式查询速度比一次性查询还慢现象改用Cursor后处理完所有数据的总时间反而变长了。根因分析网络往返Round-Trip开销如果fetchSize设置过小比如默认是1每获取一条记录都需要一次网络通信延迟成为主要瓶颈。数据库端游标开销保持游标打开本身对数据库有一定资源消耗特别是当有大量并发流式查询时。客户端处理逻辑过重如果每处理一条记录都要进行复杂的计算或远程调用那么I/O等待时间会掩盖流式获取的优势。解决方案调整fetchSize根据网络状况调整。在局域网内可以设置为1000甚至更大。使用useCursorFetchtrueMySQL并设置一个合适的正数fetchSize。应用层批处理如前所述积累一定数量如1000条再批量处理减少I/O次数。优化SQL和索引确保查询本身是高效的。流式解决的是内存问题不解决慢查询问题。6.3 问题三内存使用仍然很高现象使用了Cursor但通过监控发现JVM堆内存使用率依然在持续上升。根因分析内存泄漏在遍历Cursor时无意中将处理的对象添加到了某个全局集合如Map、List中导致所有对象都无法被GC回收。大对象驻留处理的单条记录中包含大字段如长文本、Base64图片即使只存在一条在内存中也可能占用很大空间。框架或驱动缓存某些ORM框架或JDBC驱动可能有内部缓存机制。排查与解决使用jmap或VisualVM等工具做堆转储分析查看内存中数量最多的对象是什么。审查处理逻辑确保处理完的对象引用被及时清除。对于大字段考虑在SQL中不查询它们或者使用数据库特定的流式API来分段读取。6.4 一个完整的千万级数据导出案例需求将过去一年超过2000万的用户订单数据导出为CSV文件。技术栈Spring Boot MyBatis MySQL HikariCP实现步骤Mapper定义public interface OrderMapper { CursorOrderExportDTO streamOrdersForExport(Param(startDate) LocalDate startDate, Param(endDate) LocalDate endDate); }select idstreamOrdersForExport resultTypeOrderExportDTO fetchSize-2147483648 SELECT order_id, user_id, amount, status, create_time FROM orders WHERE create_time BETWEEN #{startDate} AND #{endDate} ORDER BY order_id ASC !-- 按主键排序保证顺序且利于数据库扫描 -- /selectService层Service Slf4j public class OrderExportService { private static final int BATCH_SIZE 2000; Transactional(readOnly true, timeout 7200) // 只读事务2小时超时 public void exportOrdersToCsv(LocalDate startDate, LocalDate endDate, Path outputPath) throws IOException { long start System.currentTimeMillis(); try (BufferedWriter writer Files.newBufferedWriter(outputPath, StandardCharsets.UTF_8); CSVPrinter csvPrinter new CSVPrinter(writer, CSVFormat.DEFAULT.withHeader(HEADERS)); CursorOrderExportDTO cursor orderMapper.streamOrdersForExport(startDate, endDate)) { ListOrderExportDTO batch new ArrayList(BATCH_SIZE); for (OrderExportDTO order : cursor) { batch.add(order); if (batch.size() BATCH_SIZE) { writeBatchToCsv(csvPrinter, batch); batch.clear(); csvPrinter.flush(); // 定期刷新缓冲区到磁盘 } } // 处理剩余数据 if (!batch.isEmpty()) { writeBatchToCsv(csvPrinter, batch); } csvPrinter.flush(); } long duration (System.currentTimeMillis() - start) / 1000; log.info(订单导出完成耗时: {} 秒, duration); } private void writeBatchToCsv(CSVPrinter printer, ListOrderExportDTO batch) throws IOException { for (OrderExportDTO order : batch) { printer.printRecord( order.getOrderId(), order.getUserId(), order.getAmount(), order.getStatus(), order.getCreateTime() ); } } }关键配置application.ymlspring: datasource: hikari: maximum-pool-size: 20 connection-timeout: 30000 idle-timeout: 600000 # 10分钟确保长事务连接不被回收 max-lifetime: 1800000 # 30分钟 url: jdbc:mysql://localhost:3306/order_db?useCursorFetchtrueserverTimezoneAsia/Shanghai mybatis: configuration: default-fetch-size: -2147483648 # 全局设置流式获取监控与告警在导出服务中集成Metrics记录导出速率行/秒、内存使用情况并设置耗时过长或内存异常的告警。通过这套方案我们成功将单次导出2000万条订单数据的内存占用从预期的数十GB如果全量加载降低到稳定的几百MB批处理缓冲区任务总耗时在可控范围内且对数据库主库的影响降到了最低。