在实际 Java 后端开发中处理海量数据查询是一个绕不开的挑战。很多开发者都遇到过这样的场景一个看似简单的SELECT * FROM large_table查询在测试环境可能运行正常一旦部署到生产环境面对百万甚至千万级别的数据应用服务器内存会在瞬间飙升最终抛出OutOfMemoryError导致服务崩溃。这背后的根本原因是传统的 JDBC 结果集处理方式会将所有查询结果一次性加载到 JVM 内存中。当数据量远超 JVM 堆内存容量时内存溢出就成了必然结果。本文要讨论的“流式查询”正是为了解决这个问题而生的关键技术。它并非 MyBatis 独有的概念而是 JDBC 规范提供的一种能力允许应用程序像处理水流一样逐条或逐批地从数据库服务器获取结果而不是一次性全部载入。MyBatis 作为优秀的持久层框架为我们封装和简化了使用流式查询的流程。掌握它意味着你能在数据导出的后台任务、大数据量的报表生成、实时数据流处理等场景中游刃有余地处理海量数据而无需担心内存成为瓶颈。本文将带你从原理到实践彻底理解 MyBatis 流式查询。我们会先剖析传统查询导致内存溢出的根源然后深入 JDBC 和 MyBatis 的流式查询机制。接着通过一个完整的、可运行的示例项目演示如何配置和编写流式查询代码。最后我们会探讨在生产环境中使用流式查询时需要注意的陷阱、性能考量以及最佳实践。无论你是正在被大查询困扰的开发者还是希望提前储备应对大数据场景技能的工程师这篇文章都将提供清晰的路径和实用的代码。1. 为什么一行查询代码就能挤爆内存在深入流式查询之前我们必须先理解问题的根源。很多人认为OutOfMemoryError (OOM)只会在创建大量对象时发生却忽略了数据库查询这个隐蔽的“内存杀手”。1.1 传统 JDBC 结果集处理机制当我们通过 JDBC 执行一条查询语句时其背后的流程大致如下应用层执行Statement.executeQuery(“SELECT * FROM large_table”)。驱动层JDBC 驱动通过网络将 SQL 发送给数据库服务器。数据库层数据库执行查询将符合条件的所有数据行准备好。传输与内存加载数据库服务器通过网络将所有结果数据发送给 JDBC 驱动。驱动接收到数据后会将其全部缓存在内存中并封装成一个ResultSet对象返回给应用程序。应用层遍历应用程序通过ResultSet.next()和getXxx()方法遍历这个已经在内存中的结果集。关键在于第4步所有数据在应用程序开始遍历之前就已经被完整地加载到了 JVM 堆内存中。这个ResultSet默认的类型是ResultSet.TYPE_FORWARD_ONLY和ResultSet.CONCUR_READ_ONLY但它并不是“流式”的数据早已就位。让我们用一个简单的代码片段来直观感受这个过程可能带来的内存压力// 这是一个危险的传统查询示例 public ListUser getAllUsers() { try (Connection conn dataSource.getConnection(); Statement stmt conn.createStatement(); ResultSet rs stmt.executeQuery(SELECT id, name, email, content FROM user)) { // 假设 content 是 TEXT 大字段 ListUser 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内部缓存一份在ListUser中对堆内存的消耗是指数级增长的。1.2 内存消耗分析与 OOM 触发条件我们可以粗略估算一下内存占用。假设user表有 100 万行数据每行数据包括所有字段平均大小为 2KB。那么数据库驱动缓存的结果集100 万 * 2KB ≈ 2GB应用程序构建的ListUser至少也需要 2GB对象本身还有开销这意味着处理这个查询JVM 堆内存至少需要 4GB 以上的空闲空间。如果应用堆内存设置为-Xmx2g那么内存溢出几乎必然发生。触发 OOM 的时机可能有两个在executeQuery后驱动尝试缓存巨大结果集时直接抛出OutOfMemoryError。或者在遍历结果集构建List的过程中因为创建大量对象而触发 GC最终 GC 也无法回收足够空间而抛出 OOM。1.3 MyBatis 默认映射机制下的内存问题MyBatis 简化了 JDBC 操作但其默认行为并没有改变底层的内存模型。当你在 Mapper 中写一个如下的查询select idselectAllUsers resultTypecom.example.model.User SELECT id, name, email, content FROM user /select对应的 Java 方法调用ListUser users userMapper.selectAllUsers();MyBatis 在底层依然会执行传统的 JDBC 查询将全部结果映射为User对象后装入一个List返回。所以使用 MyBatis 并不意味着自动获得了处理海量数据的能力它只是封装了步骤内存瓶颈依然存在。理解了问题的严重性我们就能明白要安全地处理海量数据查询必须改变“一次性加载”这个默认行为。这就是流式查询登场的原因。2. 流式查询的核心原理与 JDBC 基础流式查询的思想是“按需索取即用即弃”。它改变了数据从数据库传输到应用的模式从“批发”变成了“零售”。2.1 JDBC 流式查询的底层支持JDBC 规范本身提供了支持流式查询的能力主要通过Statement的两个关键设置实现setFetchSize这个参数指示 JDBC 驱动每次从数据库网络连接中获取多少行数据。将其设置为一个较小的值如 50, 100, 1000意味着驱动不会一次性拉取所有数据而是分批拉取。游标Cursor在数据库层面当使用流式查询时数据库会为查询结果维护一个游标。应用每次请求数据调用ResultSet.next()驱动会通过网络从数据库游标处获取下一批fetchSize指定的大小数据。这要求数据库和 JDBC 驱动都支持这种“服务端游标”或“可滚动结果集”的特性。重要区别setFetchSize并不直接等同于流式查询。在默认情况下即使设置了fetchSize某些驱动如旧版本的 MySQL 驱动可能仍然会一次性获取所有数据到客户端内存这被称为“客户端游标”模式。真正的流式查询需要驱动工作在“服务端游标”模式。对于 MySQL需要结合连接参数useCursorFetchtrue和setFetchSize来启用。2.2 MyBatis 如何封装流式查询MyBatis 提供了两种方式来实现流式查询让开发者无需直接操作底层的 JDBCStatement和ResultSet。方式一使用ResultHandler这是 MyBatis 原生支持的方式。你可以在 Mapper 接口中定义一个返回值为void的方法并增加一个ResultHandler参数。MyBatis 会在获取到每一行数据并完成对象映射后立即调用ResultHandler的handleResult方法。你可以在该方法中处理当前行数据例如写入文件、发送到消息队列等然后将其丢弃从而避免在内存中累积。方式二返回CursorT接口从 MyBatis 3.4.0 开始提供了CursorT接口。它是对 JDBCResultSet的一个包装实现了IteratorT接口。你可以像使用迭代器一样遍历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 groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis Spring Boot Starter -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version3.0.3/version !-- 请使用与 Spring Boot 匹配的版本 -- /dependency !-- 数据库驱动这里以 MySQL 为例 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency !-- 其他工具依赖如 Lombok -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies关键版本说明MyBatis确保版本 3.4.0以支持CursorT接口。MySQL Connector/J建议使用 8.0 及以上版本对流式查询的支持更完善。5.x 版本也可用但需要注意参数。3.2 数据库连接配置关键步骤这是启用流式查询最核心的配置环节。你需要在数据源配置中为 JDBC URL 添加特定的参数以告知驱动使用服务端游标模式。在application.yml或application.properties中配置spring: datasource: url: jdbc:mysql://localhost:3306/your_database?useSSLfalseserverTimezoneUTCuseCursorFetchtrue # 关键参数 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关键参数解释参数值作用useCursorFetchtrue这是启用 MySQL 服务端游标的关键。设置为true后当Statement设置了fetchSizeJDBC 驱动会向 MySQL 发送COM_STMT_FETCH命令来分批获取数据而不是一次性拉取所有数据到客户端内存。serverTimezoneUTC设置服务器时区避免时间转换错误。根据你的数据库时区调整。useSSLfalse开发环境可禁用 SSL。生产环境应设置为true并提供证书。关于连接池的特别提醒流式查询会长时间占用一个数据库连接直到遍历结束或游标关闭。因此你需要确保连接池的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) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 插入测试数据例如使用存储过程或脚本插入 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(ResultHandlerUser handler); }接下来在对应的 XML 映射文件如UserMapper.xml中编写 SQL。这里不需要指定resultType或resultMap因为结果将由ResultHandler处理。?xml version1.0 encodingUTF-8 ? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespacecom.example.demo.mapper.UserMapper !-- 流式查询 - 使用 ResultHandler -- select idselectAllUsersStreaming fetchSize100 resultTypecom.example.demo.model.User SELECT id, name, email, content, create_time FROM user ORDER BY id !-- 对流式查询排序通常是个好习惯 -- /select /mapper关键点fetchSize100这是 MyBatis 中设置 JDBCStatement.fetchSize的方式。这里设置为 100意味着每次从数据库网络流中获取 100 行数据。这个值需要权衡太小会增加网络往返次数太大则可能失去流式意义占用较多客户端内存。通常设置在 100 到 1000 之间。resultTypecom.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 ResultHandlerUser handler new ResultHandlerUser() { 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 代码详解与关键注意事项Transactional注解这是必须的。流式查询依赖于一个活跃的数据库连接来保持游标。Transactional确保了在整个方法执行期间使用的是同一个数据库连接。如果不在事务中MyBatis 可能会在 Mapper 方法调用结束后就关闭连接导致ResultHandler在后续回调时连接已关闭而报错。ResultHandler实现handleResult方法会为查询结果中的每一行被调用一次。参数ResultContext包含了当前结果对象 (getResultObject()) 和一些上下文信息。你可以在这里进行任何业务处理比如写入文件、发送消息、累加统计等。资源管理我们在方法内使用了try-with-resources来管理文件写入流 (BufferedWriter)确保无论处理成功还是失败文件流都会被正确关闭。但请注意数据库连接和游标是由 MyBatis 和 Spring 事务管理器在事务边界方法结束时负责关闭的。性能与内存在handleResult中我们每处理 1000 条记录才刷新 (flush) 一次缓冲区而不是每行都刷新这能显著提升 I/O 性能。同时处理完一行数据后该行数据对应的User对象很快就不再被引用可以被垃圾回收器回收从而保持内存的平稳。错误处理在handleResult中发生的IOException被包装为RuntimeException抛出这会触发事务回滚并终止整个处理流程。这是一种合理的错误处理方式。你也可以选择记录错误并跳过当前行这取决于业务要求。提前终止可以通过调用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的方式给了我们最大的灵活性但代码略显繁琐。接下来我们看看更优雅的CursorT方式。
