 配 TaoToken：settings.json 骨架与验证)
1. 从一次内存告警说起Mybatis 游标到底解决了什么线上有个对账任务单表扫 300 万行做逐条比对。一开始用ListT接结果服务刚跑两分钟就 OOM堆内存曲线像坐火箭。后来把返回类型从List换成Cursor内存曲线立刻压成一条平线任务稳稳跑完。这就是 Mybatis 游标cursor最典型的使用场景数据量远超内存承受能力时用迭代器一条条从数据库拉而不是一次性全灌进 JVM。但很多人只停留在「把 List 改成 Cursor」这一步遇到Cannot open more than one iterator on a Cursor、A Cursor is already closed这类报错就懵了。要真正用好它得回到源码里看Cursor接口和DefaultCursor是怎么设计的。这篇就沿着org.apache.ibatis.cursor这条链路把接口契约、状态机、迭代器实现讲清楚同时结合 TaoToken 统一 Key/API 通道在settings.json里给一份可复制的配置骨架最后跑一次真实的游标查询验证配置和源码行为的对应关系。适合谁看写过 Mybatis 但没深挖过 cursor 包的同学、被大数据量查询内存问题困扰的后端、以及想搞懂「配置项到底怎么影响运行时行为」的开发者。核心检索词就三个Mybatis、源码、cursor 游标。2. TaoToken 前置统一 Key 与 API 通道让验证环境先跑通在动源码之前先把「能跑起来的环境」准备好。我习惯用 TaoToken 做统一入口原因是它把模型对话、编码计划、API Key 管理收敛到一个控制台里验证 Mybatis 游标这种偏工程的任务时不用在多个平台之间来回切。TaoToken 是什么一个提供统一 API 通道和 Key 管理的平台官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个地址不加 UTM。它适合需要长期做编码、Agent 任务、以及想用一套 Key 打通多个调用场景的开发者。具体到这篇的场景你需要先拿到一个可用的 Key然后把它写进settings.json。拿 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。如果你后面要做长期的编码或 Agent 任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。想先验证模型通道是否通用模型对话页https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。接入细节和参数说明在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意Key 属于敏感凭证不要硬编码进提交到 Git 的配置文件用环境变量或本地未跟踪的settings.local.json承载。3. 可复制配置settings.json 骨架与 Mybatis 游标参数这一节给两份东西一份是 TaoToken 的settings.json骨架一份是 Mybatis 侧让游标真正生效的配置。两者分开避免混淆。3.1 TaoToken settings.json 骨架{ provider: taotoken, api_base: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: claude-sonnet, timeout_seconds: 60, retry: { max_attempts: 3, backoff_ms: 800 }, features: { coding_plan: true, stream: true } }几个字段说明api_base固定指向https://taotoken.net/api不要带 UTM 参数api_key_env表示从环境变量读取而不是把 Key 明文写进来retry是网络抖动时的重试策略实测下来 3 次、800ms 退避对大多数场景够用。设置环境变量export TAOTOKEN_API_KEY你的Key3.2 Mybatis 游标生效的关键配置游标能不能用取决于ResultSet的类型。Mybatis 默认的ResultSetType是DEFAULT某些驱动下会退化成一次性加载。要稳定走游标需要显式设置select idscanAll resultMapreconcileMap fetchSize1000 resultSetTypeFORWARD_ONLY SELECT id, order_no, amount, status FROM reconcile_order ORDER BY id /select对应 Mapper 接口返回类型必须是CursorTpublic interface ReconcileMapper { CursorReconcileOrder scanAll(); }参数对照表配置项作用游标场景建议值fetchSize每次从数据库拉取的行数500~2000太小网络往返多太大失去流式意义resultSetType结果集类型FORWARD_ONLY游标只支持向前resultOrderedresultMap 收集时是否有序若 resultMap 里有 collection必须 true返回类型决定是否走 DefaultCursor必须是 Cursor不能是 List注意fetchSize在 MySQL 上要配合useCursorFetchtrue才真正生效否则驱动会忽略它。这是踩过的坑之一。4. 源码链路Cursor 接口与 DefaultCursor 状态机配置只是入口真正决定行为的是org.apache.ibatis.cursor.Cursor和org.apache.ibatis.cursor.defaults.DefaultCursor。4.1 Cursor 接口的三个契约CursorT继承Closeable和IterableT所以它天然带两个语义可关闭、可迭代。接口里三个方法public interface CursorT extends Closeable, IterableT { boolean isOpen(); boolean isConsumed(); int getCurrentIndex(); }isOpen()表示游标是否已开始从数据库取数isConsumed()表示是否已全部取完getCurrentIndex()返回当前索引第一条是 0没取到是 -1。继承Closeable是因为底层持有ResultSet必须手动释放否则连接池会被拖垮。4.2 DefaultCursor 的四个状态DefaultCursor内部用一个枚举CursorStatus管理生命周期四个状态CREATED刚创建结果集还没消费、OPEN正在消费、CLOSED被关闭可能没消费完、CONSUMED全部消费完必然已关闭。状态流转的关键在fetchNextObjectFromDatabase()每次取一条把状态置为OPEN通过resultSetHandler.handleRowValues把当前行映射成实体塞进ObjectWrapperResultHandler。取到 null 或者读满offset limit时调用close()并把状态改成CONSUMED。4.3 为什么迭代器只能拿一次iterator()方法里有两道校验if (iteratorRetrieved) { throw new IllegalStateException(Cannot open more than one iterator on a Cursor); } if (isClosed()) { throw new IllegalStateException(A Cursor is already closed.); } iteratorRetrieved true; return cursorIterator;iteratorRetrieved是个一次性开关。原因很直接游标底层是单向的ResultSet已经消费过的行不可能回头再读。所以设计上就禁止二次获取迭代器避免你以为能重头遍历、结果拿到空数据。4.4 CursorIterator 的懒加载CursorIterator的hasNext()里有个细节只有当object null时才去fetchNextUsingRowBound()。也就是说next()之前如果没调hasNext()它会自己补一次取数。fetchNextUsingRowBound()还负责跳过RowBounds的 offset实现物理分页语义。5. 验证请求跑一次游标查询看行为配置和源码都清楚了跑一次验证。写个最小测试try (SqlSession session sqlSessionFactory.openSession()) { ReconcileMapper mapper session.getMapper(ReconcileMapper.class); CursorReconcileOrder cursor mapper.scanAll(); System.out.println(isOpen cursor.isOpen()); System.out.println(isConsumed cursor.isConsumed()); int count 0; for (ReconcileOrder order : cursor) { count; if (count 3) { System.out.println(index cursor.getCurrentIndex() , orderNo order.getOrderNo()); } } System.out.println(total count); System.out.println(isConsumed cursor.isConsumed()); }预期输出循环开始前isOpenfalse、isConsumedfalse循环中getCurrentIndex()从 0 递增循环结束后isConsumedtrue。如果isConsumed一直是 false说明没消费完就退出了通常是中途 break 或抛异常。再验证一次「二次获取迭代器」的报错CursorReconcileOrder cursor mapper.scanAll(); cursor.iterator(); cursor.iterator(); // 这里抛 IllegalStateException抛出的正是Cannot open more than one iterator on a Cursor和源码里的校验完全对应。这一步做完你就把「配置项 → 运行时行为 → 源码分支」三者串起来了。6. 本篇常见错排查报错一Cannot open more than one iterator on a Cursor原因对同一个 Cursor 调了两次iterator()或者用了两次 for-each。解决一个 Cursor 只遍历一次需要多次遍历就重新查一次。报错二A Cursor is already closed原因Cursor 已经消费完或被 close 后又去拿迭代器。解决检查是否在 try-with-resources 外继续使用或者遍历中途异常导致提前关闭。报错三内存还是爆原因fetchSize没生效驱动一次性把结果拉回来了。MySQL 需要连接串加useCursorFetchtruePostgreSQL 需要autoCommitfalse且fetchSize大于 0。解决确认驱动参数别只改 XML。报错四getCurrentIndex()返回 -1原因还没调用next()就取索引。解决索引在取到第一条后才从 0 开始取数前是 -1这是设计如此。报错五resultMap 里有 collection 时数据错乱原因没设resultOrderedtrue。解决游标配合嵌套 resultMap 时SQL 必须按 id 排序并开启resultOrdered。排障和接入相关的入口放在这里API Keys 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你要长期做编码或 Agent 任务Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 只想先验证模型通道用模型对话 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。最后留个实操建议把fetchSize从 1000 调到 100 再跑一次观察数据库的往返次数和总耗时变化你会对「流式拉取」的代价有更直观的感受。源码里的fetchNextObjectFromDatabase()每调一次就是一次取数动作fetchSize决定的是驱动层每次批量拿多少两者配合才是完整的游标行为。
1. 从一次内存告警说起Mybatis 游标到底解决了什么线上有个对账任务单表扫 300 万行做逐条比对。一开始用ListT接结果服务刚跑两分钟就 OOM堆内存曲线像坐火箭。后来把返回类型从List换成Cursor内存曲线立刻压成一条平线任务稳稳跑完。这就是 Mybatis 游标cursor最典型的使用场景数据量远超内存承受能力时用迭代器一条条从数据库拉而不是一次性全灌进 JVM。但很多人只停留在「把 List 改成 Cursor」这一步遇到Cannot open more than one iterator on a Cursor、A Cursor is already closed这类报错就懵了。要真正用好它得回到源码里看Cursor接口和DefaultCursor是怎么设计的。这篇就沿着org.apache.ibatis.cursor这条链路把接口契约、状态机、迭代器实现讲清楚同时结合 TaoToken 统一 Key/API 通道在settings.json里给一份可复制的配置骨架最后跑一次真实的游标查询验证配置和源码行为的对应关系。适合谁看写过 Mybatis 但没深挖过 cursor 包的同学、被大数据量查询内存问题困扰的后端、以及想搞懂「配置项到底怎么影响运行时行为」的开发者。核心检索词就三个Mybatis、源码、cursor 游标。2. TaoToken 前置统一 Key 与 API 通道让验证环境先跑通在动源码之前先把「能跑起来的环境」准备好。我习惯用 TaoToken 做统一入口原因是它把模型对话、编码计划、API Key 管理收敛到一个控制台里验证 Mybatis 游标这种偏工程的任务时不用在多个平台之间来回切。TaoToken 是什么一个提供统一 API 通道和 Key 管理的平台官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个地址不加 UTM。它适合需要长期做编码、Agent 任务、以及想用一套 Key 打通多个调用场景的开发者。具体到这篇的场景你需要先拿到一个可用的 Key然后把它写进settings.json。拿 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。如果你后面要做长期的编码或 Agent 任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。想先验证模型通道是否通用模型对话页https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。接入细节和参数说明在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意Key 属于敏感凭证不要硬编码进提交到 Git 的配置文件用环境变量或本地未跟踪的settings.local.json承载。3. 可复制配置settings.json 骨架与 Mybatis 游标参数这一节给两份东西一份是 TaoToken 的settings.json骨架一份是 Mybatis 侧让游标真正生效的配置。两者分开避免混淆。3.1 TaoToken settings.json 骨架{ provider: taotoken, api_base: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: claude-sonnet, timeout_seconds: 60, retry: { max_attempts: 3, backoff_ms: 800 }, features: { coding_plan: true, stream: true } }几个字段说明api_base固定指向https://taotoken.net/api不要带 UTM 参数api_key_env表示从环境变量读取而不是把 Key 明文写进来retry是网络抖动时的重试策略实测下来 3 次、800ms 退避对大多数场景够用。设置环境变量export TAOTOKEN_API_KEY你的Key3.2 Mybatis 游标生效的关键配置游标能不能用取决于ResultSet的类型。Mybatis 默认的ResultSetType是DEFAULT某些驱动下会退化成一次性加载。要稳定走游标需要显式设置select idscanAll resultMapreconcileMap fetchSize1000 resultSetTypeFORWARD_ONLY SELECT id, order_no, amount, status FROM reconcile_order ORDER BY id /select对应 Mapper 接口返回类型必须是CursorTpublic interface ReconcileMapper { CursorReconcileOrder scanAll(); }参数对照表配置项作用游标场景建议值fetchSize每次从数据库拉取的行数500~2000太小网络往返多太大失去流式意义resultSetType结果集类型FORWARD_ONLY游标只支持向前resultOrderedresultMap 收集时是否有序若 resultMap 里有 collection必须 true返回类型决定是否走 DefaultCursor必须是 Cursor不能是 List注意fetchSize在 MySQL 上要配合useCursorFetchtrue才真正生效否则驱动会忽略它。这是踩过的坑之一。4. 源码链路Cursor 接口与 DefaultCursor 状态机配置只是入口真正决定行为的是org.apache.ibatis.cursor.Cursor和org.apache.ibatis.cursor.defaults.DefaultCursor。4.1 Cursor 接口的三个契约CursorT继承Closeable和IterableT所以它天然带两个语义可关闭、可迭代。接口里三个方法public interface CursorT extends Closeable, IterableT { boolean isOpen(); boolean isConsumed(); int getCurrentIndex(); }isOpen()表示游标是否已开始从数据库取数isConsumed()表示是否已全部取完getCurrentIndex()返回当前索引第一条是 0没取到是 -1。继承Closeable是因为底层持有ResultSet必须手动释放否则连接池会被拖垮。4.2 DefaultCursor 的四个状态DefaultCursor内部用一个枚举CursorStatus管理生命周期四个状态CREATED刚创建结果集还没消费、OPEN正在消费、CLOSED被关闭可能没消费完、CONSUMED全部消费完必然已关闭。状态流转的关键在fetchNextObjectFromDatabase()每次取一条把状态置为OPEN通过resultSetHandler.handleRowValues把当前行映射成实体塞进ObjectWrapperResultHandler。取到 null 或者读满offset limit时调用close()并把状态改成CONSUMED。4.3 为什么迭代器只能拿一次iterator()方法里有两道校验if (iteratorRetrieved) { throw new IllegalStateException(Cannot open more than one iterator on a Cursor); } if (isClosed()) { throw new IllegalStateException(A Cursor is already closed.); } iteratorRetrieved true; return cursorIterator;iteratorRetrieved是个一次性开关。原因很直接游标底层是单向的ResultSet已经消费过的行不可能回头再读。所以设计上就禁止二次获取迭代器避免你以为能重头遍历、结果拿到空数据。4.4 CursorIterator 的懒加载CursorIterator的hasNext()里有个细节只有当object null时才去fetchNextUsingRowBound()。也就是说next()之前如果没调hasNext()它会自己补一次取数。fetchNextUsingRowBound()还负责跳过RowBounds的 offset实现物理分页语义。5. 验证请求跑一次游标查询看行为配置和源码都清楚了跑一次验证。写个最小测试try (SqlSession session sqlSessionFactory.openSession()) { ReconcileMapper mapper session.getMapper(ReconcileMapper.class); CursorReconcileOrder cursor mapper.scanAll(); System.out.println(isOpen cursor.isOpen()); System.out.println(isConsumed cursor.isConsumed()); int count 0; for (ReconcileOrder order : cursor) { count; if (count 3) { System.out.println(index cursor.getCurrentIndex() , orderNo order.getOrderNo()); } } System.out.println(total count); System.out.println(isConsumed cursor.isConsumed()); }预期输出循环开始前isOpenfalse、isConsumedfalse循环中getCurrentIndex()从 0 递增循环结束后isConsumedtrue。如果isConsumed一直是 false说明没消费完就退出了通常是中途 break 或抛异常。再验证一次「二次获取迭代器」的报错CursorReconcileOrder cursor mapper.scanAll(); cursor.iterator(); cursor.iterator(); // 这里抛 IllegalStateException抛出的正是Cannot open more than one iterator on a Cursor和源码里的校验完全对应。这一步做完你就把「配置项 → 运行时行为 → 源码分支」三者串起来了。6. 本篇常见错排查报错一Cannot open more than one iterator on a Cursor原因对同一个 Cursor 调了两次iterator()或者用了两次 for-each。解决一个 Cursor 只遍历一次需要多次遍历就重新查一次。报错二A Cursor is already closed原因Cursor 已经消费完或被 close 后又去拿迭代器。解决检查是否在 try-with-resources 外继续使用或者遍历中途异常导致提前关闭。报错三内存还是爆原因fetchSize没生效驱动一次性把结果拉回来了。MySQL 需要连接串加useCursorFetchtruePostgreSQL 需要autoCommitfalse且fetchSize大于 0。解决确认驱动参数别只改 XML。报错四getCurrentIndex()返回 -1原因还没调用next()就取索引。解决索引在取到第一条后才从 0 开始取数前是 -1这是设计如此。报错五resultMap 里有 collection 时数据错乱原因没设resultOrderedtrue。解决游标配合嵌套 resultMap 时SQL 必须按 id 排序并开启resultOrdered。排障和接入相关的入口放在这里API Keys 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你要长期做编码或 Agent 任务Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 只想先验证模型通道用模型对话 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。最后留个实操建议把fetchSize从 1000 调到 100 再跑一次观察数据库的往返次数和总耗时变化你会对「流式拉取」的代价有更直观的感受。源码里的fetchNextObjectFromDatabase()每调一次就是一次取数动作fetchSize决定的是驱动层每次批量拿多少两者配合才是完整的游标行为。
