MyBatis流式查询实战：解决百万数据查询OOM问题

这次我们来看一个 Java 开发中非常实际的内存问题：当你的 MyBatis 查询返回海量数据时，如何避免一行代码就把内存撑爆。这个问题在数据导出、报表生成、大数据量分页等场景下频繁出现，直接导致 OOM（OutOfMemoryError），服务崩溃。

本文的核心是MyBatis 流式查询。它不是新概念，但很多开发者要么不知道，要么知道却用不对。我们将彻底拆解它的原理、适用场景，并给出从环境配置到代码实战的完整方案。如果你正在处理百万级数据查询，或者对ResultHandler、游标（Cursor）这些概念感到模糊，这篇文章可以直接收藏。

我们将重点关注：

1. 流式查询是什么：它与普通查询的本质区别，以及如何绕过 JVM 堆内存限制。
2. 两种实现方式：基于ResultHandler的“推”模式和基于Cursor的“拉”模式，各自的优缺点和适用场景。
3. 实战代码与避坑指南：提供可运行的 Spring Boot + MyBatis 示例，并指出事务管理、连接超时、ORM 映射等关键陷阱。
4. 性能与资源观察：如何监控查询过程中的内存和数据库连接占用，确保方案稳定。

本文适合所有使用 MyBatis 进行数据持久化的 Java 后端开发者，特别是那些需要处理大数据集，又受困于内存压力的同学。我们将从问题现象出发，一步步构建解决方案。

1. 核心能力速览：流式查询 vs 普通查询

在深入代码之前，我们先通过一个表格快速理解流式查询的核心价值，它决定了你是否需要以及何时需要使用它。

核心结论：如果你的查询可能返回超过内存承受能力的数据量，并且你需要对每条数据执行后续操作（如写入文件、发送消息、汇总计算），那么流式查询是你的必选项。它用稍高的代码复杂度，换取了系统的稳定性和处理能力的质变。

2. 适用场景与使用边界

流式查询是一把利器，但并非所有场景都适用。明确边界能避免误用和性能倒退。

2.1 最适合的场景（强烈推荐使用）

1. 数据导出：这是最经典的场景。将数据库中的百万条记录导出为 CSV 或 Excel 文件。使用流式查询，可以边读边写，内存中只保留少量数据。
2. 批量数据处理（ETL）：从源数据库读取大量数据，经过转换后写入目标数据库或数据仓库。流式查询可以避免在转换过程中内存爆掉。
3. 大数据分析与统计：需要对全表数据进行遍历计算（如求和、计数、去重统计），但不需要在内存中同时持有所有对象。可以通过流式读取逐条累加。
4. 消息队列数据灌入：从数据库读取历史数据，逐条或分批发送到 Kafka、RocketMQ 等消息中间件。
5. 日志/流水记录的后台处理：处理用户操作日志、交易流水等随时间累积的海量数据。

2.2 不适合的场景（不要使用）

1. 需要随机访问或多次遍历数据：流式查询像水流，流过即消失。如果你需要反复访问列表中的第 N 条数据，或者需要对全部数据排序、分组后再处理，则必须先将所有数据加载到内存中。流式查询不提供这种能力。
2. 分页查询：分页查询（LIMIT offset, size）本身就是为了避免大数据量。数据库已在服务器端完成了数据裁剪，返回的数据量很小，使用普通查询即可。流式查询在此场景无优势，反而增加复杂度。
3. 实时交互式小列表：管理后台的表格、下拉列表等，数据量通常很小，直接使用List返回是最佳实践。
4. 事务中混合了其他非流式查询：流式查询对数据库连接有特殊要求（后续会详述），在复杂事务中混用可能导致连接持有时间过长或意外关闭。

使用边界与合规提醒：

• 数据库连接资源：流式查询会长时间占用一个数据库连接，直到所有数据读取完毕。必须在代码中确保 finally 块或 try-with-resources 语句关闭游标，防止连接泄漏。
• 事务超时：长时间运行的流式查询可能触发事务超时。需要根据业务合理设置事务超时时间，或考虑在非事务环境下执行。
• 网络稳定性：在流式传输过程中，网络中断会导致查询失败。对于关键业务，需要设计重试机制。
• ORM 映射开销：尽管内存占用低，但 MyBatis 为每一行数据创建对象并进行属性映射的开销依然存在。如果单行数据列非常多、非常宽，这个 CPU 开销不可忽视。

3. 环境准备与前置条件

为了演示流式查询，我们需要一个标准的 Spring Boot + MyBatis 环境。以下是搭建最小化演示环境的步骤。

3.1 基础环境清单

3.2 项目初始化与依赖

使用 Spring Initializr 或手动创建一个 Maven 项目，核心依赖如下：

<!-- pom.xml --> <dependencies> <!-- Spring Boot Web (用于创建测试接口) --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- MyBatis 整合 Spring Boot --> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>2.3.0</version> <!-- 请使用与Spring Boot匹配的版本 --> </dependency> <!-- 数据库驱动 (以MySQL为例) --> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> <!-- 注意：8.x驱动类名和URL与5.x不同 --> </dependency> <!-- 方便测试，可选 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies>

关键点：mysql-connector-java驱动版本建议使用 8.0.x。对于 MySQL，确保在连接 URL 中设置了useCursorFetch=true参数以启用服务端游标支持（对于大数据量更高效），我们会在配置部分说明。

3.3 数据库与测试数据准备

创建一个简单的表并插入足够多的测试数据，以模拟大数据量查询。

-- 创建用户表 CREATE TABLE `user` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `name` varchar(255) DEFAULT NULL, `email` varchar(255) DEFAULT NULL, `age` int(11) DEFAULT NULL, `created_at` datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; -- 插入模拟数据 (例如，插入50万条) -- 可以使用存储过程或程序批量插入，这里示意性插入少量数据 INSERT INTO `user` (`name`, `email`, `age`) VALUES ('张三', 'zhangsan@example.com', 25), ('李四', 'lisi@example.com', 30); -- ... 实际测试需要更多数据

为了快速制造大量测试数据，可以在 MySQL 中运行一个简单的循环语句（注意在生产环境谨慎操作）：

DELIMITER // CREATE PROCEDURE generate_test_data() BEGIN DECLARE i INT DEFAULT 1; WHILE i <= 1000000 DO INSERT INTO `user` (`name`, `email`, `age`) VALUES (CONCAT('User-', i), CONCAT('user', i, '@test.com'), FLOOR(RAND() * 80) + 18); SET i = i + 1; END WHILE; END // DELIMITER ; -- 调用存储过程 CALL generate_test_data();

4. MyBatis 流式查询的两种实现方式

MyBatis 提供了两种主要的流式查询方式，它们底层都依赖于 JDBC 的ResultSet流式读取能力，但在 API 使用上截然不同。

4.1 方式一：ResultHandler（“推”模式）

在这种模式下，你定义一个处理器（ResultHandler），MyBatis 会在遍历结果集时，主动将每一条映射好的对象“推”给你的处理器。你无法控制遍历的节奏，但代码结构清晰。

1. 定义实体类和 Mapper 接口

// User.java @Data // 使用Lombok public class User { private Long id; private String name; private String email; private Integer age; private Date createdAt; }

// UserMapper.java @Mapper public interface UserMapper { // 普通查询方法，用于对比 List<User> selectAllUsers(); // 流式查询方法：使用 ResultHandler // 注意：返回类型必须是 void，结果通过 handler 参数传递 void selectAllUsersStreaming(ResultHandler<User> handler); }

2. 编写 Mapper XML

<!-- UserMapper.xml --> <?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="com.example.demo.mapper.UserMapper"> <!-- 普通查询 --> <select id="selectAllUsers" resultType="User"> SELECT id, name, email, age, created_at as createdAt FROM user </select> <!-- 流式查询：SQL 与普通查询完全一样，但配置了 fetchSize 和 resultSetType --> <select id="selectAllUsersStreaming" fetchSize="100" resultSetType="FORWARD_ONLY" resultType="User"> SELECT id, name, email, age, created_at as createdAt FROM user </select> </mapper>

关键配置解释：

• fetchSize=”100”： 提示 JDBC 驱动每次从数据库网络缓冲区获取的行数。这是一个性能调优参数，-1表示使用驱动默认值。设置为一个正数（如 100, 1000）可以在网络往返次数和内存占用间取得平衡。
• resultSetType=”FORWARD_ONLY”： 指定结果集类型为“仅向前”。这是流式查询的必要条件，它告诉数据库和驱动，结果集不会回滚或随机访问，从而允许驱动以流式方式传输数据。

3. 实现 ResultHandler 并调用

// 自定义ResultHandler @Component public class UserStreamHandler implements ResultHandler<User> { private static final Logger log = LoggerFactory.getLogger(UserStreamHandler.class); private int count = 0; @Override public void handleResult(ResultContext<? extends User> resultContext) { // 每获取到一条记录，该方法被调用一次 User user = resultContext.getResultObject(); count++; // 模拟处理：这里可以是写入文件、发送消息、累加计算等 // 例如，每处理1000条打印一次日志 if (count % 1000 == 0) { log.info("已处理 {} 条记录，当前用户: {}", count, user.getName()); // 重要：在此处可以手动触发垃圾回收，但不要频繁调用 // if (count % 10000 == 0) { System.gc(); } } // 关键：处理完的对象，在方法结束后即可被GC回收 // 此处不要将user添加到外部集合中，否则失去流式意义！ } public int getCount() { return count; } }

4. 在 Service 中调用

@Service @Slf4j public class UserService { @Autowired private UserMapper userMapper; @Autowired private UserStreamHandler userStreamHandler; /** * 普通查询 - 可能导致OOM */ public List<User> getAllUsersNormal() { return userMapper.selectAllUsers(); // 数据量大时，这里直接返回List，内存暴涨 } /** * 流式查询 - 使用ResultHandler */ @Transactional // 注意事务边界！流式查询必须在一个事务内，或者关闭自动提交。 public void processUsersStreaming() { // 重置计数器（如果Handler是单例） // userStreamHandler.resetCount(); log.info("开始流式处理用户数据..."); long startTime = System.currentTimeMillis(); // 调用Mapper方法，传入handler userMapper.selectAllUsersStreaming(userStreamHandler); long endTime = System.currentTimeMillis(); log.info("流式处理完成。总计处理 {} 条记录，耗时 {} ms", userStreamHandler.getCount(), (endTime - startTime)); } }

ResultHandler模式特点：

• 优点：代码逻辑集中，处理流程清晰。MyBatis 负责遍历和映射，你只关心处理逻辑。
• 缺点：控制权在 MyBatis 手中，你无法暂停、跳过，或者以非顺序方式处理数据。如果handleResult方法中的处理逻辑很慢，会阻塞整个结果集的获取。

4.2 方式二：Cursor（“拉”模式）

在这种模式下，Mapper 方法返回一个Cursor<T>对象。你可以像使用Iterator一样，主动地、按需地“拉取”数据，控制权在你手中。

1. 修改 Mapper 接口

// UserMapper.java @Mapper public interface UserMapper { // 返回 Cursor 的流式查询方法 Cursor<User> selectAllUsersByCursor(); }

2. 编写 Mapper XML

<!-- UserMapper.xml --> <select id="selectAllUsersByCursor" fetchSize="100" resultSetType="FORWARD_ONLY" resultType="User"> SELECT id, name, email, age, created_at as createdAt FROM user </select>

XML 配置与ResultHandler模式完全一致，都需要fetchSize和resultSetType。

3. 在 Service 中调用 Cursor

@Service @Slf4j public class UserService { @Autowired private UserMapper userMapper; /** * 流式查询 - 使用Cursor */ @Transactional // 至关重要！Cursor必须在一个数据库事务中打开和使用。 public void processUsersByCursor() { log.info("开始使用Cursor流式处理用户数据..."); long startTime = System.currentTimeMillis(); int count = 0; // 关键：使用 try-with-resources 确保 Cursor 被关闭，从而释放数据库连接 try (Cursor<User> cursor = userMapper.selectAllUsersByCursor()) { for (User user : cursor) { // Cursor 实现了 Iterable 接口 count++; // 模拟处理业务 if (count % 1000 == 0) { log.info("已处理 {} 条记录，当前用户: {}", count, user.getName()); } // 处理完的user对象在循环结束后可被GC } } catch (Exception e) { log.error("流式处理数据失败", e); throw new RuntimeException(e); } long endTime = System.currentTimeMillis(); log.info("Cursor流式处理完成。总计处理 {} 条记录，耗时 {} ms", count, (endTime - startTime)); } }

Cursor模式特点：

• 优点：控制灵活。你可以决定何时调用next()获取下一条数据，可以在循环中根据条件break，也可以将游标传递给其他方法处理。更符合传统的“拉取”编程模型。
• 缺点：需要手动管理资源（必须用try-with-resources或finally块关闭Cursor）。如果忘记关闭，会导致数据库连接泄漏，这是严重的 Bug。

5. 关键配置与深度调优

仅仅使用fetchSize和resultSetType可能还不够，为了流式查询稳定高效，必须关注以下配置。

5.1 数据库连接配置（以 MySQL 为例）

在application.yml或application.properties中配置数据源：

# application.yml spring: datasource: url: jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&useCursorFetch=true # 关键参数 username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver hikari: # 连接池配置，根据流式查询特点调整 maximum-pool-size: 20 minimum-idle: 5 connection-timeout: 30000 # 连接超时时间，流式查询可能耗时较长 idle-timeout: 600000 max-lifetime: 1800000

关键参数useCursorFetch=true：

• 对于 MySQL，这个参数指示驱动使用服务端游标（Server-side Cursor）。默认情况下，JDBC 驱动会一次性将所有结果集拉取到客户端内存中（即“普通查询”）。启用此参数后，驱动会告诉 MySQL 服务器“我要流式读取”，服务器会按fetchSize分批发送数据，极大地减少客户端内存压力。这是 MySQL 流式查询生效的核心开关。
• 注意：并非所有数据库都需要或支持类似参数。PostgreSQL 默认行为就更适合流式，通常无需特殊配置。

5.2 MyBatis 配置

可以在全局配置中设置默认的fetchSize，避免在每个 Mapper XML 中重复写。

# application.yml mybatis: configuration: default-fetch-size: 100 # 全局默认fetchSize，会被XML中的配置覆盖 # 其他配置...

5.3 事务管理配置（极其重要！）

流式查询，尤其是Cursor模式，必须在一个有效的事务中执行。原因在于：为了保持结果集的可读性，数据库连接（Connection）在结果集遍历完成前不能被关闭或归还到连接池。而 Spring 的声明式事务@Transactional正是管理连接生命周期的最佳工具。

@Service public class UserService { @Transactional // 必须添加事务注解 public void processUsersByCursor() { try (Cursor<User> cursor = userMapper.selectAllUsersByCursor()) { // ... 遍历 cursor } } @Transactional // 同样需要事务 public void processUsersStreaming() { userMapper.selectAllUsersStreaming(handler); } }

如果没有事务：MyBatis 在执行完 Mapper 方法后，会立即关闭SqlSession，进而关闭底层的数据库连接。此时，Cursor还未遍历完，连接就被关闭了，后续遍历会抛出Connection is closed异常。

事务超时设置：流式处理百万数据可能耗时几分钟甚至更久。默认的事务超时时间可能不够。你需要根据业务情况调整。

@Transactional(timeout = 600) // 单位：秒，设置10分钟超时 public void processLargeDataByCursor() { // ... }

非事务场景：如果你的处理逻辑就是一次性读取全部数据并处理，且不允许失败回滚，也可以考虑在非事务环境下，但需要手动管理连接会话。这非常复杂且容易出错，不推荐。

6. 功能测试与效果验证：模拟 OOM 与流式拯救

现在，让我们通过一个简单的测试来直观感受普通查询的 OOM 风险和流式查询的稳定性。

6.1 测试准备：制造内存压力

首先，确保你的测试数据量足够大（例如 50 万条以上）。然后，调整 JVM 启动参数，故意设置一个较小的堆内存，以便快速触发 OOM，方便观察。

在 IDE 的启动配置或命令行中添加：

-Xmx256m -Xms256m -XX:+HeapDumpOnOutOfMemoryError

这会将最大堆内存限制在 256MB。

6.2 测试用例1：普通查询（预期：OOM）

@RestController @Slf4j public class TestController { @Autowired private UserService userService; @GetMapping("/test/normal") public String testNormalQuery() { log.info("开始普通查询测试..."); long start = System.currentTimeMillis(); try { List<User> users = userService.getAllUsersNormal(); // 这里会加载所有数据到List long end = System.currentTimeMillis(); log.info("普通查询成功，获取 {} 条数据，耗时 {} ms", users.size(), (end - start)); return "Success. Count: " + users.size(); } catch (Exception e) { log.error("普通查询发生异常: ", e); return "Failed: " + e.getClass().getName() + " - " + e.getMessage(); } } }

预期结果：当数据量超过 JVM 堆内存容量时，在userService.getAllUsersNormal()执行过程中，你会看到java.lang.OutOfMemoryError: Java heap space错误。服务可能崩溃或无响应。

6.3 测试用例2：Cursor 流式查询（预期：成功）

@RestController @Slf4j public class TestController { @Autowired private UserService userService; @GetMapping("/test/cursor") public String testCursorStreaming() { log.info("开始Cursor流式查询测试..."); long start = System.currentTimeMillis(); try { userService.processUsersByCursor(); // 内部使用Cursor遍历 long end = System.currentTimeMillis(); log.info("Cursor流式查询处理完成，耗时 {} ms", (end - start)); return "Cursor Streaming Process Success."; } catch (Exception e) { log.error("Cursor流式查询发生异常: ", e); return "Failed: " + e.getClass().getName() + " - " + e.getMessage(); } } }

预期结果：即使 JVM 堆内存很小（如 256MB），这个接口也能成功处理百万级数据。通过监控工具（如 JConsole、VisualVM）观察，你会看到堆内存使用率是一条平稳的波浪线，而不是直线上升直至爆掉。因为内存中始终只持有少量User对象。

6.4 测试用例3：ResultHandler 流式查询（预期：成功）

@GetMapping("/test/handler") public String testHandlerStreaming() { log.info("开始ResultHandler流式查询测试..."); long start = System.currentTimeMillis(); try { userService.processUsersStreaming(); long end = System.currentTimeMillis(); log.info("ResultHandler流式查询处理完成，耗时 {} ms", (end - start)); return "Handler Streaming Process Success."; } catch (Exception e) { log.error("ResultHandler流式查询发生异常: ", e); return "Failed: " + e.getClass().getName() + " - " + e.getMessage(); } }

预期结果：与 Cursor 模式类似，内存占用平稳，处理成功。

成功判断标准：

1. 接口返回成功信息，无 OOM 异常。
2. 应用日志显示处理了预期数量的记录。
3. JVM 堆内存监控图表显示内存使用率平稳，无持续飙升。
4. 数据库连接数稳定，处理完成后连接被正确释放。

7. 资源占用与性能观察

理解了原理并跑通测试后，我们需要关注流式查询在真实场景下的表现。

7.1 如何观察资源占用？

1. JVM 内存监控：

   • 工具：JConsole, VisualVM, JDK Mission Control, 或应用性能管理（APM）工具如 SkyWalking, Prometheus + Grafana。
   • 观察指标：Heap Memory Usage。流式查询下，该图表应呈现锯齿状或平稳状，峰值远小于堆最大值。

2. 数据库连接监控：

   • 工具：数据库自身的监控（如 MySQLSHOW PROCESSLIST），或连接池监控（如 HikariCP 的spring-boot-starter-actuator端点）。
   • 观察指标：活跃连接数、连接持有时间。流式查询会长时间占用一个连接，这是正常的。但要确保处理完成后连接被关闭。

3. 系统资源监控：

   • 工具：top,htop,docker stats。
   • 观察指标：进程的 CPU 使用率和物理内存（RSS）。流式查询的 CPU 使用率可能较高（因为持续进行对象映射和业务处理），但物理内存应保持稳定。

7.2 性能影响因素与调优

1. fetchSize参数：

   • 太小（如 10）：增加网络往返次数，降低整体吞吐量。
   • 太大（如 10000）：单次网络传输数据包过大，可能在客户端驱动层缓冲较多数据，轻微增加内存压力，但减少了网络次数。
   • 建议：从默认值或 100-1000 开始测试，根据网络延迟和单行数据大小调整。可以通过 JMeter 或单元测试对比不同fetchSize下的总耗时。

2. JDBC 驱动与数据库版本：

   • 确保使用较新版本的数据库驱动（如 MySQL Connector/J 8.0+），它们对流式查询的支持和性能优化更好。
   • 数据库服务器版本也可能影响流式传输效率。

3. 业务处理逻辑的耗时：

   • 流式查询的瓶颈往往不在“读数据”，而在“处理数据”。如果handleResult方法或Cursor循环体内的业务逻辑非常耗时（如复杂的计算、同步调用外部 API），整体处理时间会线性增长。
   • 优化方向：考虑将处理逻辑异步化、批量化，或者引入并行处理（但要注意线程安全和数据库连接限制）。

4. 网络带宽与延迟：

   • 如果应用与数据库跨机房或跨地域，网络延迟会显著影响流式查询的体验，因为每个fetchSize批次都可能有一次网络往返。
   • 优化方向：适当增大fetchSize，或者将处理程序部署到离数据库更近的位置。

8. 常见问题与排查方法

在实际使用流式查询时，你可能会遇到以下问题。这里提供排查思路。

9. 最佳实践与使用建议

1. 始终使用try-with-resources处理Cursor：这是防止数据库连接泄漏的最有效手段。

   try (Cursor<User> cursor = mapper.selectCursor()) { // 处理 cursor } // 自动调用 cursor.close()

2. 明确事务边界：为包含流式查询的方法添加@Transactional，并评估事务超时时间是否足够长。

3. 分离查询与处理：Mapper 只负责数据访问，复杂的业务处理逻辑应放在 Service 层。在 Service 层进行流式遍历和处理。

4. 谨慎处理异常：在流式处理循环中，单条数据的处理失败不应导致整个任务终止。应考虑捕获单条记录的异常并记录日志，然后继续处理下一条。

5. 性能测试与监控上线：在大数据量场景下，务必进行充分的性能测试，监控内存、CPU、数据库连接和慢查询日志。根据监控结果调整fetchSize、JVM 参数和连接池配置。

6. 考虑替代方案：对于极端大数据量（亿级），流式查询可能依然不够。需要考虑：

   • 分页批次处理：虽然“深分页”有性能问题，但如果是按主键ID等有序条件分批（WHERE id > ? LIMIT ?），则是非常高效的方案。
   • 数据库原生导出工具：如mysqldump,SELECT ... INTO OUTFILE。
   • 大数据平台：直接将数据同步到 Hive、Spark 等平台进行处理。

7. 代码可读性：流式查询代码比普通查询复杂。应在关键位置添加清晰的注释，说明为何使用流式查询、事务如何管理、资源如何关闭。

流式查询是 MyBatis 处理海量数据的神兵利器，它将你从 OOM 的恐惧中解放出来。核心在于理解其“逐条消耗”而非“一次性加载”的机制，并掌握ResultHandler和Cursor两种模式。成功的关键点可以总结为：正确的配置（fetchSize,resultSetType, 连接参数）、严格的事务管理、以及确保资源被可靠关闭。

在实际项目中，首次引入流式查询时，建议从一个非核心的、数据量大的导出功能开始试点。完整走通配置、编码、测试和监控的全流程，验证其稳定性和效果。一旦掌握了这套模式，你就可以 confidently 应对任何大数据量查询场景，再也不用担心一行代码就把内存挤爆了。