MyBatis流式查询实战：解决海量数据查询内存溢出难题

在实际 Java 后端开发中，处理海量数据查询是一个绕不开的挑战。很多开发者都遇到过这样的场景：一个看似简单的SELECT * FROM large_table查询，在测试环境可能运行正常，一旦部署到生产环境，面对百万甚至千万级别的数据，应用服务器内存会在瞬间飙升，最终抛出OutOfMemoryError，导致服务崩溃。这背后的根本原因，是传统的 JDBC 结果集处理方式会将所有查询结果一次性加载到 JVM 内存中。当数据量远超 JVM 堆内存容量时，内存溢出就成了必然结果。

本文要讨论的“流式查询”，正是为了解决这个问题而生的关键技术。它并非 MyBatis 独有的概念，而是 JDBC 规范提供的一种能力，允许应用程序像处理水流一样，逐条或逐批地从数据库服务器获取结果，而不是一次性全部载入。MyBatis 作为优秀的持久层框架，为我们封装和简化了使用流式查询的流程。掌握它，意味着你能在数据导出的后台任务、大数据量的报表生成、实时数据流处理等场景中，游刃有余地处理海量数据，而无需担心内存成为瓶颈。

本文将带你从原理到实践，彻底理解 MyBatis 流式查询。我们会先剖析传统查询导致内存溢出的根源，然后深入 JDBC 和 MyBatis 的流式查询机制。接着，通过一个完整的、可运行的示例项目，演示如何配置和编写流式查询代码。最后，我们会探讨在生产环境中使用流式查询时需要注意的陷阱、性能考量以及最佳实践。无论你是正在被大查询困扰的开发者，还是希望提前储备应对大数据场景技能的工程师，这篇文章都将提供清晰的路径和实用的代码。

1. 为什么一行查询代码就能挤爆内存？

在深入流式查询之前，我们必须先理解问题的根源。很多人认为OutOfMemoryError (OOM)只会在创建大量对象时发生，却忽略了数据库查询这个隐蔽的“内存杀手”。

1.1 传统 JDBC 结果集处理机制

当我们通过 JDBC 执行一条查询语句时，其背后的流程大致如下：

1. 应用层：执行Statement.executeQuery(“SELECT * FROM large_table”)。
2. 驱动层：JDBC 驱动通过网络将 SQL 发送给数据库服务器。
3. 数据库层：数据库执行查询，将符合条件的所有数据行准备好。
4. 传输与内存加载：数据库服务器通过网络将所有结果数据发送给 JDBC 驱动。驱动接收到数据后，会将其全部缓存在内存中，并封装成一个ResultSet对象返回给应用程序。
5. 应用层遍历：应用程序通过ResultSet.next()和getXxx()方法遍历这个已经在内存中的结果集。

关键在于第4步：所有数据在应用程序开始遍历之前，就已经被完整地加载到了 JVM 堆内存中。这个ResultSet默认的类型是ResultSet.TYPE_FORWARD_ONLY和ResultSet.CONCUR_READ_ONLY，但它并不是“流式”的，数据早已就位。

让我们用一个简单的代码片段来直观感受这个过程可能带来的内存压力：

// 这是一个危险的传统查询示例 public List<User> getAllUsers() { try (Connection conn = dataSource.getConnection(); Statement stmt = conn.createStatement(); ResultSet rs = stmt.executeQuery("SELECT id, name, email, content FROM user")) { // 假设 content 是 TEXT 大字段 List<User> userList = new ArrayList<>(); while (rs.next()) { User user = new User(); user.setId(rs.getLong("id")); user.setName(rs.getString("name")); user.setEmail(rs.getString("email")); user.setContent(rs.getString("content")); // 大字段 userList.add(user); } return userList; // 当 user 表有 100 万行时，这个 List 将极其庞大 } catch (SQLException e) { throw new RuntimeException(e); } }

在这段代码中，即使我们使用了try-with-resources确保资源关闭，但内存问题在executeQuery返回ResultSet的那一刻就已经埋下了。数据库驱动会把百万行数据，包括可能很大的content字段，全部加载到 JVM 内存。随后，在遍历ResultSet构建User对象并加入ArrayList时，我们又创建了百万个User对象和内部的字符串，这相当于在内存中存储了两份完整数据（一份在ResultSet内部缓存，一份在List<User>中），对堆内存的消耗是指数级增长的。

1.2 内存消耗分析与 OOM 触发条件

我们可以粗略估算一下内存占用。假设user表有 100 万行数据，每行数据（包括所有字段）平均大小为 2KB。那么：

• 数据库驱动缓存的结果集：100 万 * 2KB ≈ 2GB
• 应用程序构建的List<User>：至少也需要 2GB（对象本身还有开销）

这意味着，处理这个查询，JVM 堆内存至少需要 4GB 以上的空闲空间。如果应用堆内存设置为-Xmx2g，那么内存溢出几乎必然发生。

触发 OOM 的时机可能有两个：

1. 在executeQuery后，驱动尝试缓存巨大结果集时，直接抛出OutOfMemoryError。
2. 或者在遍历结果集构建List的过程中，因为创建大量对象而触发 GC，最终 GC 也无法回收足够空间而抛出 OOM。

1.3 MyBatis 默认映射机制下的内存问题

MyBatis 简化了 JDBC 操作，但其默认行为并没有改变底层的内存模型。当你在 Mapper 中写一个如下的查询：

<select id="selectAllUsers" resultType="com.example.model.User"> SELECT id, name, email, content FROM user </select>

对应的 Java 方法调用：

List<User> users = userMapper.selectAllUsers();

MyBatis 在底层依然会执行传统的 JDBC 查询，将全部结果映射为User对象后，装入一个List返回。所以，使用 MyBatis 并不意味着自动获得了处理海量数据的能力，它只是封装了步骤，内存瓶颈依然存在。

理解了问题的严重性，我们就能明白，要安全地处理海量数据查询，必须改变“一次性加载”这个默认行为。这就是流式查询登场的原因。

2. 流式查询的核心原理与 JDBC 基础

流式查询的思想是“按需索取，即用即弃”。它改变了数据从数据库传输到应用的模式，从“批发”变成了“零售”。

2.1 JDBC 流式查询的底层支持

JDBC 规范本身提供了支持流式查询的能力，主要通过Statement的两个关键设置实现：

1. setFetchSize：这个参数指示 JDBC 驱动每次从数据库网络连接中获取多少行数据。将其设置为一个较小的值（如 50, 100, 1000），意味着驱动不会一次性拉取所有数据，而是分批拉取。
2. 游标（Cursor）：在数据库层面，当使用流式查询时，数据库会为查询结果维护一个游标。应用每次请求数据（调用ResultSet.next()），驱动会通过网络从数据库游标处获取下一批（fetchSize指定的大小）数据。这要求数据库和 JDBC 驱动都支持这种“服务端游标”或“可滚动结果集”的特性。

重要区别：setFetchSize并不直接等同于流式查询。在默认情况下，即使设置了fetchSize，某些驱动（如旧版本的 MySQL 驱动）可能仍然会一次性获取所有数据到客户端内存，这被称为“客户端游标”模式。真正的流式查询需要驱动工作在“服务端游标”模式。对于 MySQL，需要结合连接参数useCursorFetch=true和setFetchSize来启用。

2.2 MyBatis 如何封装流式查询

MyBatis 提供了两种方式来实现流式查询，让开发者无需直接操作底层的 JDBCStatement和ResultSet。

方式一：使用ResultHandler这是 MyBatis 原生支持的方式。你可以在 Mapper 接口中定义一个返回值为void的方法，并增加一个ResultHandler参数。MyBatis 会在获取到每一行数据并完成对象映射后，立即调用ResultHandler的handleResult方法。你可以在该方法中处理当前行数据（例如写入文件、发送到消息队列等），然后将其丢弃，从而避免在内存中累积。

方式二：返回Cursor<T>接口从 MyBatis 3.4.0 开始，提供了Cursor<T>接口。它是对 JDBCResultSet的一个包装，实现了Iterator<T>接口。你可以像使用迭代器一样遍历Cursor，每次next()只会从数据库获取下一批数据（受fetchSize控制）。这种方式代码更简洁，更符合 Java 集合操作的习惯。

两种方式的核心都是延迟加载和逐行处理。数据不会在内存中构建成一个完整的List，而是在遍历过程中动态地从数据库流入、被处理、然后被 GC 回收。

2.3 流式查询的适用与不适用场景

流式查询是解决特定问题的利器，但并非万能。

非常适合的场景：

• 数据导出：将数据库中的海量数据导出为 CSV、Excel 文件。
• ETL 处理：读取大量数据，进行转换后写入另一个数据存储（如另一个数据库、数据仓库、搜索引擎）。
• 批量消息发送：读取每行数据，将其作为消息发送到消息中间件（如 Kafka、RocketMQ）。
• 报表生成：需要遍历所有数据来计算汇总指标的离线报表任务。

不适用或需谨慎的场景：

• 需要随机访问或多次遍历结果集：流式查询是单向、向前的，你无法回头获取之前的数据，也无法跳转到指定行。
• 事务非常长：因为流式查询需要保持数据库连接和游标打开，直到遍历结束。长时间持有连接会占用数据库资源，增加连接池压力，在并发高时可能成为瓶颈。
• 网络不稳定：流式查询依赖于一个长期稳定的数据库连接。如果网络中断，游标可能失效，导致后续数据无法获取。
• 结果集本身很小：对于只有几百、几千条数据的查询，使用流式查询带来的复杂性收益很低，直接使用List返回更简单高效。

理解了原理和场景，我们就可以开始动手实践了。

3. 环境准备与 MyBatis 流式查询配置

在开始编写代码前，确保你的项目环境已正确配置，这是流式查询能生效的前提。

3.1 项目依赖与环境要求

以一个标准的 Spring Boot + MyBatis 项目为例，你需要以下核心依赖（以 Maven 为例）：

<dependencies> <!-- Spring Boot Starter --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- MyBatis Spring Boot Starter --> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>3.0.3</version> <!-- 请使用与 Spring Boot 匹配的版本 --> </dependency> <!-- 数据库驱动，这里以 MySQL 为例 --> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <!-- 其他工具依赖，如 Lombok --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies>

关键版本说明：

• MyBatis：确保版本 >= 3.4.0，以支持Cursor<T>接口。
• MySQL Connector/J：建议使用 8.0 及以上版本，对流式查询的支持更完善。5.x 版本也可用，但需要注意参数。

3.2 数据库连接配置（关键步骤）

这是启用流式查询最核心的配置环节。你需要在数据源配置中，为 JDBC URL 添加特定的参数，以告知驱动使用服务端游标模式。

在application.yml或application.properties中配置：

spring: datasource: url: jdbc:mysql://localhost:3306/your_database?useSSL=false&serverTimezone=UTC&useCursorFetch=true # 关键参数 username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver hikari: # 连接池配置，对于流式查询很重要 maximum-pool-size: 20 connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 1800000

关键参数解释：

关于连接池的特别提醒：流式查询会长时间占用一个数据库连接，直到遍历结束或游标关闭。因此，你需要确保连接池的max-lifetime（连接最大存活时间）和数据库的wait_timeout（非交互连接超时时间）设置合理，避免连接在流式查询过程中被意外回收导致错误。通常，max-lifetime应略小于数据库的wait_timeout。

3.3 数据模型与测试数据准备

为了演示，我们创建一个简单的数据表并插入一批测试数据。这里我们故意插入较多数据来模拟海量数据场景。

-- 创建用户表 CREATE TABLE `user` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `name` varchar(100) DEFAULT NULL, `email` varchar(100) DEFAULT NULL, `content` text COMMENT '模拟一个大文本字段', `create_time` datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; -- 插入测试数据（例如，使用存储过程或脚本插入 50 万条数据） -- 这里提供一个插入示例，实际测试时可根据需要调整数量 DELIMITER $$ CREATE PROCEDURE generate_test_data() BEGIN DECLARE i INT DEFAULT 1; WHILE i <= 500000 DO INSERT INTO `user` (`name`, `email`, `content`) VALUES (CONCAT('User_', i), CONCAT('user', i, '@example.com'), REPEAT('This is a large content field. ', 50)); SET i = i + 1; END WHILE; END$$ DELIMITER ; -- 调用存储过程 CALL generate_test_data();

对应的 Java 实体类：

package com.example.demo.model; import lombok.Data; import java.time.LocalDateTime; @Data public class User { private Long id; private String name; private String email; private String content; // 大字段 private LocalDateTime createTime; }

环境与数据准备就绪后，我们就可以开始编写两种不同风格的流式查询代码了。

4. 实战：使用ResultHandler进行流式处理

ResultHandler是 MyBatis 经典的流式处理方式。它要求 Mapper 方法返回void，并通过参数接收一个处理器。

4.1 创建 Mapper 接口与 XML

首先，在 Mapper 接口中定义方法。注意返回类型是void，并增加ResultHandler参数。

package com.example.demo.mapper; import com.example.demo.model.User; import org.apache.ibatis.annotations.Mapper; import org.apache.ibatis.session.ResultHandler; @Mapper public interface UserMapper { /** * 流式查询所有用户，使用 ResultHandler 处理每一行 * @param handler 结果处理器 */ void selectAllUsersStreaming(ResultHandler<User> handler); }

接下来，在对应的 XML 映射文件（如UserMapper.xml）中编写 SQL。这里不需要指定resultType或resultMap，因为结果将由ResultHandler处理。

<?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"> <!-- 流式查询 - 使用 ResultHandler --> <select id="selectAllUsersStreaming" fetchSize="100" resultType="com.example.demo.model.User"> SELECT id, name, email, content, create_time FROM user ORDER BY id <!-- 对流式查询，排序通常是个好习惯 --> </select> </mapper>

关键点：

• fetchSize="100"：这是 MyBatis 中设置 JDBCStatement.fetchSize的方式。这里设置为 100，意味着每次从数据库网络流中获取 100 行数据。这个值需要权衡：太小会增加网络往返次数；太大则可能失去流式意义，占用较多客户端内存。通常设置在 100 到 1000 之间。
• resultType="com.example.demo.model.User"：虽然结果不直接返回，但 MyBatis 仍然需要知道如何将结果集的每一行映射成 Java 对象，然后再交给ResultHandler。所以这里必须配置。

4.2 实现业务逻辑与ResultHandler

现在，在 Service 层调用这个 Mapper 方法。我们需要实现一个ResultHandler。

package com.example.demo.service; import com.example.demo.mapper.UserMapper; import com.example.demo.model.User; import lombok.extern.slf4j.Slf4j; import org.apache.ibatis.session.ResultContext; import org.apache.ibatis.session.ResultHandler; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; import java.io.BufferedWriter; import java.io.FileWriter; import java.io.IOException; @Service @Slf4j public class UserExportService { private final UserMapper userMapper; public UserExportService(UserMapper userMapper) { this.userMapper = userMapper; } /** * 使用 ResultHandler 流式导出用户数据到 CSV 文件 * @param filePath 导出文件路径 */ @Transactional // 注意：流式查询需要在一个事务内，以保持数据库连接和游标 public void exportUsersToCsvWithHandler(String filePath) { long startTime = System.currentTimeMillis(); int count = 0; try (BufferedWriter writer = new BufferedWriter(new FileWriter(filePath))) { // 写入 CSV 表头 writer.write("ID,Name,Email,CreateTime"); writer.newLine(); // 定义 ResultHandler ResultHandler<User> handler = new ResultHandler<User>() { @Override public void handleResult(ResultContext<? extends User> resultContext) { User user = resultContext.getResultObject(); count++; // 处理每一行数据：写入文件 try { writer.write(String.format("%d,%s,%s,%s", user.getId(), escapeCsv(user.getName()), escapeCsv(user.getEmail()), user.getCreateTime())); writer.newLine(); // 可选：每处理一定数量记录，刷新一下缓冲区，而不是每行都 flush if (count % 1000 == 0) { writer.flush(); log.debug("已处理 {} 条记录", count); } } catch (IOException e) { // 处理 IO 异常，这里可以包装成运行时异常抛出，中断处理 throw new RuntimeException("写入文件失败", e); } // 可以通过 resultContext.stop() 来提前终止处理 // if (count >= 10000) { // resultContext.stop(); // } } }; // 执行流式查询，handler 会被自动回调 userMapper.selectAllUsersStreaming(handler); long endTime = System.currentTimeMillis(); log.info("流式导出完成。总处理记录数: {}，耗时: {} ms", count, (endTime - startTime)); } catch (IOException e) { log.error("创建或写入文件失败: {}", filePath, e); throw new RuntimeException("导出失败", e); } } // 简单的 CSV 字段转义（处理逗号和引号） private String escapeCsv(String field) { if (field == null) { return ""; } // 如果字段包含逗号、双引号或换行，需要用双引号括起来，并且内部的双引号要转义为两个双引号 if (field.contains(",") || field.contains("\"") || field.contains("\n")) { return "\"" + field.replace("\"", "\"\"") + "\""; } return field; } }

4.3 代码详解与关键注意事项

1. @Transactional注解：这是必须的。流式查询依赖于一个活跃的数据库连接来保持游标。@Transactional确保了在整个方法执行期间，使用的是同一个数据库连接。如果不在事务中，MyBatis 可能会在 Mapper 方法调用结束后就关闭连接，导致ResultHandler在后续回调时连接已关闭而报错。
2. ResultHandler实现：handleResult方法会为查询结果中的每一行被调用一次。参数ResultContext包含了当前结果对象 (getResultObject()) 和一些上下文信息。你可以在这里进行任何业务处理，比如写入文件、发送消息、累加统计等。
3. 资源管理：我们在方法内使用了try-with-resources来管理文件写入流 (BufferedWriter)，确保无论处理成功还是失败，文件流都会被正确关闭。但请注意，数据库连接和游标是由 MyBatis 和 Spring 事务管理器在事务边界（方法结束）时负责关闭的。
4. 性能与内存：在handleResult中，我们每处理 1000 条记录才刷新 (flush) 一次缓冲区，而不是每行都刷新，这能显著提升 I/O 性能。同时，处理完一行数据后，该行数据对应的User对象很快就不再被引用，可以被垃圾回收器回收，从而保持内存的平稳。
5. 错误处理：在handleResult中发生的IOException被包装为RuntimeException抛出，这会触发事务回滚并终止整个处理流程。这是一种合理的错误处理方式。你也可以选择记录错误并跳过当前行，这取决于业务要求。
6. 提前终止：可以通过调用resultContext.stop()来提前终止流式处理。这在只需要处理部分数据时非常有用。

4.4 编写测试 Controller

创建一个简单的 Controller 来触发导出任务。

package com.example.demo.controller; import com.example.demo.service.UserExportService; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/api/export") @Slf4j public class ExportController { private final UserExportService userExportService; public ExportController(UserExportService userExportService) { this.userExportService = userExportService; } @GetMapping("/csv/handler") public String exportViaHandler() { String filePath = "/tmp/users_export_handler.csv"; // 根据你的系统调整路径 log.info("开始通过 ResultHandler 流式导出到: {}", filePath); try { userExportService.exportUsersToCsvWithHandler(filePath); return "导出成功，文件位于: " + filePath; } catch (Exception e) { log.error("导出失败", e); return "导出失败: " + e.getMessage(); } } }

启动应用，访问http://localhost:8080/api/export/csv/handler，观察后台日志和内存使用情况（可以通过 JConsole、VisualVM 或 Arthas 等工具监控）。你应该能看到内存使用曲线平稳，没有出现持续飙升直至 OOM 的情况，同时日志会分批打印处理进度。

ResultHandler的方式给了我们最大的灵活性，但代码略显繁琐。接下来，我们看看更优雅的Cursor<T>方式。