MyBatis流式查询实战：解决大数据查询内存溢出问题
你有没有遇到过这样的场景：一个看似简单的查询，只是数据量稍微大了一点，比如几十万条记录，程序运行几分钟后突然卡死，然后控制台无情地抛出一个OutOfMemoryError？你检查代码，发现就是一行普通的List<User> users = userMapper.selectList(queryWrapper);，怎么就“一行代码挤爆内存”了呢？
这绝不是危言耸听。在数据驱动的今天，处理海量数据导出、大数据分析、实时日志处理等场景时，传统的“一次性加载全部结果到内存”的查询模式，就像用脸盆去接消防水龙头的水，瞬间就会溢出。内存（OOM）问题，尤其是由大结果集查询引发的，是Java后端开发中一个隐蔽却杀伤力极强的“定时炸弹”。
今天，我们不谈空洞的理论，直接解决这个痛点。本文将深入剖析MyBatis流式查询（Streaming Query）——这个被很多开发者忽略，却能在关键时刻“救命”的特性。它允许你像打开水龙头一样，让数据一条一条地“流”过来处理，而不是一次性把整个水库的水都灌进内存。我们将从为什么需要它、它的核心原理、如何一步步实现，再到生产环境中的坑与最佳实践，为你彻底讲透。读完本文，你将能亲手将一个可能引发OOM的查询，改造为内存友好的流式处理，从容应对大数据挑战。
1. 这篇文章真正要解决的问题
本文的核心是解决“大结果集查询导致JVM内存溢出（OOM）”这一具体且高频的生产问题。很多开发者对MyBatis的认知停留在CRUD和动态SQL，当面对SELECT * FROM huge_table这类查询时，会不假思索地使用返回List的方法，这为系统埋下了巨大隐患。
问题的本质：传统查询方式（我们称之为“普通查询”或“全量查询”）的工作模式是：JDBC驱动从数据库获取全部结果，MyBatis将其全部映射为Java对象，并装入一个List集合中，最后返回给调用者。如果结果集有100万条记录，每条记录映射成一个对象占用1KB内存，那么仅仅为了存储这个列表，JVM堆内存就需要预留近1GB的空间。这还不算中间过程中可能产生的临时对象、字符串等开销。当并发量上来，或者单个结果集更大时，OOM几乎必然发生。
流式查询的价值：它改变了数据获取的“节奏”。不是等所有数据都准备好再给你，而是每从数据库取到一条（或一小批）数据，就立刻将其映射为对象并“推送”给你处理。处理完一条，就可以丢弃一条（或等待GC回收），内存中始终只保持少量数据。这就像用一根水管持续接水，而不是用一个巨型水桶去装。
谁最需要看这篇文章？
- 正在或即将开发数据导出、报表生成功能的开发者。
- 需要处理数据库中海量历史数据（如日志分析、数据迁移）的工程师。
- 遇到线上服务因数据查询导致内存飙升、频繁Full GC甚至崩溃的运维和开发同学。
- 希望深入理解MyBatis高级特性，优化系统稳定性的Java后端开发者。
接下来，我们将从概念到实战，拆解流式查询的每一个环节。
2. 基础概念与核心原理
在动手之前，必须搞清楚两个核心概念：普通查询与流式查询的根本区别，以及支撑流式查询的底层技术——数据库游标（Cursor）和JDBC ResultSet 的流式处理。
2.1 普通查询 vs. 流式查询
我们可以用一个简单的表格来对比：
| 特性 | 普通查询 (Default) | 流式查询 (Streaming) |
|---|---|---|
| 数据加载方式 | 一次性加载所有结果到应用内存。 | 逐条（或分批）从数据库传输到应用内存。 |
| 内存占用 | 高，与结果集大小成正比，易导致OOM。 | 低且恒定，只占用当前处理中的单条数据内存。 |
| 响应时间 | 所有数据就绪后才返回，首次响应慢。 | 第一条数据就绪后即可返回，首次响应快。 |
| 网络压力 | 集中在查询初期，可能造成网络瞬时高峰。 | 平摊在整个处理周期，网络流量平稳。 |
| 数据库连接占用 | 结果集全部传输完毕后即可释放连接。 | 连接必须保持打开，直到流关闭，长时间占用连接资源。 |
| 适用场景 | 结果集小（如 < 1000 条）、分页查询。 | 结果集巨大、需要逐条处理、数据导出、ETL。 |
| MyBatis接口 | 返回List<E>,Map, 单个对象等。 | 返回Cursor<E>。 |
关键洞察：流式查询并非性能银弹，它用更长的数据库连接持有时间，换取了更低的应用层内存消耗。这是一个典型的权衡（Trade-off）。错误地在需要快速释放连接的高并发场景使用流式查询，可能导致数据库连接池被耗尽。
2.2 核心原理：游标与JDBC FetchSize
流式查询的基石是数据库的游标（Cursor）。你可以把游标理解为一个指向数据库结果集的“指针”。当执行查询时，数据库并不会立刻把数据全部发送给客户端，而是先准备好结果集，并返回一个游标句柄。
- 传统方式：JDBC默认会通过游标，主动（或根据驱动配置）将结果集的所有数据“拉取”（Fetch）到客户端内存。
- 流式方式：我们需要告诉JDBC：“不要一次性全拉过来，我让你给我一条，你再给我一条”。这是通过设置
java.sql.Statement的fetchSize属性实现的。
fetchSize的作用：它指示JDBC驱动每次从数据库游标中获取多少行数据到网络缓冲区。设置为一个较小的值（如10, 100, 1000），可以实现分批流式获取。但请注意：fetchSize的行为高度依赖于具体的JDBC驱动和数据库。例如，Oracle、PostgreSQL对其支持良好，而MySQL Connector/J 需要结合useCursorFetch=true参数才能让fetchSize生效于流式场景。
MyBatis的封装：MyBatis的Cursor<E>接口，就是对这种底层JDBC流式读取机制的一个高级封装。它实现了Iterable<E>和Iterator<E>接口，让你可以用熟悉的for-each循环或者while(iterator.hasNext())的方式来遍历海量数据，而无需关心底层JDBC的复杂配置。
理解了这些，我们就知道，实现MyBatis流式查询，核心就是两件事：1. 让Mapper方法返回Cursor类型；2. 正确配置底层JDBC驱动以启用流式模式。
3. 环境准备与前置条件
在开始编写代码前，请确保你的环境符合以下要求。版本号是示例，请根据你的实际项目调整。
- Java版本：JDK 8 或更高版本。流式查询对Java版本无特殊要求，但推荐使用JDK 8+。
- MyBatis版本：MyBatis 3.4.0+。
Cursor接口在更早的版本中可能不存在或功能不全。本文基于 MyBatis 3.5.x。 - 数据库与JDBC驱动：以最常用的 MySQL 为例。
- 数据库：MySQL 5.7 或 8.0。
- JDBC驱动：MySQL Connector/J 8.0.x。关键点在于驱动配置。
- Spring Boot (可选)：如果你使用Spring Boot集成MyBatis（如通过
mybatis-spring-boot-starter），版本2.x或3.x均可。本文会涵盖纯MyBatis和Spring Boot集成两种场景。 - 一个测试用的大表：为了演示效果，你需要一张有足够多数据的表。可以自己创建，例如：
CREATE TAB