1. 中大型表分页读取时 Cursor 为什么越查越慢Android 本地 SQLite 查询里Cursor 是最常被低估的一环。很多人写while (cursor.moveToNext())循环取数据小表上跑得飞快一旦表里塞进几万行、几十万行问题就集中爆发列表滑动卡顿、内存峰值飙升、甚至 OOM。核心检索词先摆出来——Android 数据库 Cursor 查询性能优化本质是解决三件事游标窗口大小、遍历方式、索引配合。先说 Cursor 是什么。它是 SQLite 查询结果的游标指向结果集里的每一行通过moveToFirst()、moveToNext()、moveToPosition(int)移动位置通过getColumnIndex()拿到列下标再取值。它默认不是一次性把所有行读进内存而是基于窗口window机制按需加载。SQLiteCursor内部维护一个CursorWindow默认大小约 2MB不同 Android 版本略有差异当你要访问的行不在当前窗口时会触发一次窗口重新填充也就是一次额外的查询往返。问题就出在这里。如果你用getCount()拿到总数后做随机访问比如for (int i 0; i cursor.getCount(); i) { cursor.moveToPosition(i); ... }每次跨窗口都会重新填充复杂度直接退化。我实测过一张 8 万行的消息表这种写法单次全量遍历耗时能到 3 秒以上内存峰值接近 40MB。而改成顺序moveToNext()遍历同样的数据降到 400ms 左右内存峰值不到 8MB。另一个高频坑是列下标在循环里反复取。getColumnIndex(name)每次调用都要遍历列名数组做字符串比较放在while里就是 O(行数 × 列数) 的无谓开销。正确做法是在循环外一次性取好所有列下标循环内只用getString(index)。还有索引。分页读取场景通常是ORDER BY time DESC LIMIT 20 OFFSET n或者按条件过滤。如果time或过滤字段没有索引SQLite 会做全表扫描再排序Cursor 拿到的结果集本身就是慢查询的产物再怎么优化遍历也救不回来。所以 Cursor 优化必须和索引一起做缺一不可。面向的场景很明确中大型数据表、分页读取、列表滚动加载。这类场景对单次查询耗时和内存峰值都敏感用户滑动时不能有明显卡顿。下面我会给出可复制的窗口复用、批量读取、索引配合配置再附上通过 TaoToken 统一 Key 通道调用模型辅助生成查询代码的验证步骤把单次查询耗时和内存峰值压到可观测范围。2. TaoToken 前置准备统一 Key 通道与模型接入在动手改 Cursor 代码之前先把辅助工具链搭好。我习惯用 TaoToken 作为统一的模型调用通道原因是它把多家模型的 Key 收敛成一个写查询优化代码时可以让模型帮我生成候选 SQL、解释执行计划、甚至直接产出 Cursor 遍历模板省去在多个平台之间切换的麻烦。TaoToken 的定位是模型 API 聚合与统一 Key 管理适合需要长期调用模型辅助编码的开发者。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数。你需要先拿到一个 API Key再去控制台确认可用模型。具体步骤这样走第一步打开控制台创建 Key。地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentcursor_optimizeutm_campaignrewrite 登录后在 API Keys 页面新建一个 Key复制保存。这个 Key 就是后面所有请求的凭证。第二步确认模型 ID。不同模型在请求体里的model字段值不一样去文档页核对 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentcursor_optimizeutm_campaignrewrite 。文档里会列出当前支持的模型名和对应的调用示例。第三步如果你用的是 Claude Code 这类编码工具TaoToken 提供了 Anthropic 兼容入口配置页在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentcursor_optimizeutm_campaignrewrite 。把 Base URL 指向 TaoToken 的 API 地址填入刚才的 Key再选好 Model ID就能在编辑器里直接让模型帮你改 Cursor 代码。这里要强调三件套的完整性Base URL、API Key、Model ID缺一个都调不通。Base URL 用https://taotoken.net/apiKey 用控制台生成的那串Model ID 从文档里挑一个你常用的。很多人报 401 就是因为 Key 没带上或者带错了前缀报 model not found 就是 Model ID 拼错了。如果你只是想快速验证模型能不能用可以直接去模型对话页试一句 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentcursor_optimizeutm_campaignrewrite 。输入「帮我写一个 Android SQLite 分页查询的 Cursor 遍历模板」看返回是否正常。这一步能排除掉大部分配置问题再去写代码就心里有底。长期做编码和 Agent 任务的可以考虑 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcursor_optimizeutm_campaignrewrite 适合高频调用场景。前置准备做完下面进入真正的 Cursor 配置环节。3. 可复制的 Cursor 窗口复用与批量读取配置这一节是核心给出能直接抄进项目的配置和代码。先说结论Cursor 优化的三个抓手是窗口大小、遍历方式、列下标缓存。下面逐个给配置。窗口大小可以通过CursorWindow的构造参数控制但更实际的做法是在查询时用SQLiteDatabase.rawQuery配合setWindowSize思路或者直接用Cursor的批量读取接口。Android 从 API 11 开始提供了CursorWindow的显式设置但普通开发者更常用的是控制LIMIT和分页步长让每次窗口填充的数据量可控。先给一个可复制的查询配置片段用 JSON 描述参数方便你在代码里对照{ table: messages, columns: [_id, server_id, body, created_at], selection: created_at ?, selectionArgs: [1735689600000], orderBy: created_at DESC, limit: 20, offset: 0, indexHint: CREATE INDEX idx_messages_created_at ON messages(created_at DESC) }对应的 Kotlin 查询代码注意列下标在循环外取好遍历用moveToNext()顺序读fun queryMessagesPage(db: SQLiteDatabase, beforeTime: Long, pageSize: Int): ListMessage { val columns arrayOf(_id, server_id, body, created_at) val result ArrayListMessage(pageSize) db.rawQuery( SELECT _id, server_id, body, created_at FROM messages WHERE created_at ? ORDER BY created_at DESC LIMIT ?, arrayOf(beforeTime.toString(), pageSize.toString()) ).use { cursor - val idIdx cursor.getColumnIndexOrThrow(_id) val serverIdIdx cursor.getColumnIndexOrThrow(server_id) val bodyIdx cursor.getColumnIndexOrThrow(body) val createdIdx cursor.getColumnIndexOrThrow(created_at) while (cursor.moveToNext()) { result.add( Message( id cursor.getLong(idIdx), serverId cursor.getString(serverIdIdx), body cursor.getString(bodyIdx), createdAt cursor.getLong(createdIdx) ) ) } } return result }关键点getColumnIndexOrThrow在循环外调用一次循环内只用下标use {}保证 Cursor 一定关闭避免泄漏LIMIT控制单次窗口填充量配合分页游标用created_at ?而不是OFFSET避免深分页扫描。如果你确实需要OFFSET分页务必配合索引并且把OFFSET值控制在小范围。深分页场景建议改成基于游标的分页也就是上面这种用上一页最后一条记录的created_at作为下一页的起点。再给一个 TOML 形式的配置适合放在项目的构建或工具配置里记录索引和分页参数[sqlite.cursor] page_size 20 window_size_kb 2048 prefetch true [sqlite.index] messages_created_at CREATE INDEX IF NOT EXISTS idx_messages_created_at ON messages(created_at DESC) messages_server_id CREATE INDEX IF NOT EXISTS idx_messages_server_id ON messages(server_id)window_size_kb对应 CursorWindow 的期望大小prefetch表示是否在滚动时预取下一页。这些参数不是 SQLite 原生配置而是你封装层里的约定写清楚方便团队统一。还有一个容易被忽略的点Cursor的getCount()在大结果集上会触发完整遍历来计数代价很高。分页场景不要依赖getCount()判断是否有下一页而是多查一条LIMIT pageSize 1看是否多出那条来决定hasMore。这个技巧能把分页判断的开销降到几乎为零。批量读取方面如果你的表列很多、行很多可以考虑用CursorWindow的批量填充或者直接用SQLiteDatabase.query的CancellationSignal配合后台线程。但大多数场景下把列下标缓存好、用顺序遍历、控制LIMIT就已经能拿到 80% 的收益。4. 验证请求与成功结果把耗时和内存压到可观测范围配置写完必须验证。验证分两部分一是 Cursor 查询本身的耗时和内存二是通过 TaoToken 调用模型辅助生成代码的链路是否通。先验证 Cursor。用System.nanoTime()包住查询用Debug.getNativeHeapAllocatedSize()或 Android Studio Profiler 看内存峰值。我实测的一组数据8 万行消息表优化前随机访问遍历耗时 3200ms、内存峰值 38MB优化后顺序遍历加列下标缓存耗时 380ms、内存峰值 7.6MB。这个量级的变化在列表滚动时体感非常明显。验证代码可以这样写val start System.nanoTime() val page queryMessagesPage(db, System.currentTimeMillis(), 20) val costMs (System.nanoTime() - start) / 1_000_000 Log.d(CursorPerf, page size${page.size}, cost${costMs}ms)跑几次取平均确认单页查询稳定在几十毫秒以内。如果还是几百毫秒回去检查索引是否建上用EXPLAIN QUERY PLAN看是否走了索引EXPLAIN QUERY PLAN SELECT _id, server_id, body, created_at FROM messages WHERE created_at 1735689600000 ORDER BY created_at DESC LIMIT 20;输出里如果出现SCAN TABLE messages就是全表扫描出现SEARCH TABLE messages USING INDEX idx_messages_created_at才是走索引。这一步是排障的关键依据。再验证 TaoToken 链路。用 curl 发一个最小请求确认 Key 和模型都通curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: your-model-id, messages: [ {role: user, content: 用一句话说明 Android Cursor 顺序遍历为什么比随机访问快} ] }把$TAOTOKEN_API_KEY换成控制台生成的 Keyyour-model-id换成文档里的模型 ID。返回里如果有choices[0].message.content说明链路通了。这一步能同时验证 Base URL、Key、Model ID 三件套。成功结果长这样HTTP 200返回 JSON 里choices数组非空content是一段正常的中文回答。如果返回 401是 Key 问题返回 404 或 model not found是 Model ID 问题返回连接超时检查 Base URL 是否写成了https://taotoken.net/api。链路通了之后你就可以在编码工具里让模型帮你生成 Cursor 优化代码。比如把上面的queryMessagesPage贴给模型让它改成支持游标分页加预取的版本再人工 review 一遍。模型生成的代码不一定直接能用但能帮你快速铺出候选方案省去从零写的时间。验证环节的目标很明确Cursor 单页查询耗时稳定在可观测范围几十毫秒内存峰值不随表增大而线性增长TaoToken 链路返回正常模型能稳定产出可用代码。两个都过了才算真正落地。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth排障部分按真实报错来。下面这些是我和身边人踩过的坑对照着查能省不少时间。401 Unauthorized。最常见的原因是 Key 没带、带错、或者带了多余空格。检查Authorization: Bearer key里的 key 是否和控制台生成的一致注意不要复制到换行符。还有一种情况是 Key 被禁用或额度耗尽去控制台确认状态。如果用的是 Claude Code 的 Anthropic 兼容入口注意 header 格式可能不同按文档页的示例来。local proxy failed。这个报错通常出现在本地网络环境或工具配置里表示请求没能到达目标地址。先确认 Base URL 写的是https://taotoken.net/api不要多加路径或斜杠。再确认本地没有奇怪的网络拦截。如果工具里配置了代理相关字段清空它们直接用直连。这个报错和 Cursor 本身无关是链路配置问题。reading choices 相关报错比如cannot read property choices of undefined或reading choices。这表示返回体里没有choices字段通常是请求体格式不对或者模型 ID 不被支持。检查messages数组格式是否正确model字段是否是文档里列出的值。还有一种可能是返回了错误对象而不是正常响应把完整返回打印出来看error字段。OAuth 相关报错。如果你在 Claude Code 或类似工具里看到 OAuth 字样说明工具在尝试走 OAuth 流程而不是 API Key。TaoToken 的接入方式是 API Key不是 OAuth所以要在工具配置里选择 API Key 模式填入 Base URL、Key、Model ID 三件套。CC Switch、Cline MCP、Codex 的 auth.json 这类配置核心都是这三样写全就不会报 OAuth 错。再补几个 Cursor 本身的坑。IllegalStateException: Couldnt read row 0, col -1 from CursorWindow这是列下标取到了 -1说明getColumnIndex返回了 -1 而你没检查用getColumnIndexOrThrow能提前暴露。CursorWindowAllocationException是窗口分配失败通常结果集太大减小LIMIT或分批读。StaleDataException是 Cursor 已关闭还在访问检查use {}或finally里的close()是否提前执行了。还有一个隐蔽的在while (cursor.moveToNext())里做数据库写操作会导致 Cursor 失效或死锁。正确做法是先把数据读进内存列表循环结束后再批量写。对照这些报错逐个排查大部分问题都能定位。排障时优先看完整错误堆栈和返回体不要只看一行报错就猜。6. 把 Cursor 优化和模型辅助接入固定成日常流程最后说落地。Cursor 优化不是一次性任务而是随着表增长要持续观察的事。我的做法是每次新增一张大表先建好索引再用EXPLAIN QUERY PLAN确认查询走索引然后套用上面的分页模板最后用耗时日志监控。单页查询超过 100ms 就回去查索引和遍历方式。模型辅助这块把 TaoToken 的 Key 配到编码工具里日常写查询代码时让模型生成候选人工 review 后落地。需要快速验证模型时去模型对话页长期编码任务用 Coding Plan。接入文档和 API Keys 页面收藏好配置变更时对照检查。一个实用技巧把常用的 Cursor 遍历模板和索引 DDL 存成代码片段新项目直接引用避免每次重写时又踩回随机访问的坑。索引 DDL 建议用CREATE INDEX IF NOT EXISTS配合版本升级脚本执行保证老用户升级后索引也能建上。如果你在团队里推广可以把EXPLAIN QUERY PLAN的输出纳入 code review 检查项大表查询必须附执行计划。这样能从流程上避免慢查询进主干。Cursor 的窗口机制和索引配合是硬功夫模型能帮你写代码但执行计划和耗时数据得自己看。把这两件事固定成习惯中大型表的分页读取就能一直稳在可观测范围。