Android 里的 Cursor 类介绍：从查询到遍历，配 TaoToken 统一 Key 打通 AI 辅助排查

1. 为什么 Android 里的 Cursor 总让人踩坑Cursor 是 Android 访问 SQLite 和 ContentProvider 数据时绕不开的一个类。你可以把它理解成一个「游标卡尺」查询语句执行完数据并不会一次性全塞进内存而是放在一个结果集里Cursor 就是指向这个结果集某一行的指针。它本身不存数据只负责定位和取值。很多刚接触 Android 数据读取的朋友第一次写db.query()拿到 Cursor 后直接cursor.getString(0)就崩了报CursorIndexOutOfBoundsException或者遍历完忘了close()跑几次之后日志里开始刷CursorWindowAllocationException。这些问题的根源都是没搞清楚 Cursor 的「行指针」模型和「列索引」机制。这篇内容面向的是本地 SQLite / ContentProvider 数据读取场景目标是让你能独立写出可运行的 Cursor 遍历代码并且遇到空指针、越界、游标未关闭这几类问题时知道从哪一行开始查。同时我会给出一套通过 TaoToken 统一 Key 接入 AI 辅助排查的配置骨架把「写代码」和「问 AI 定位问题」串成一条线。Cursor 的核心操作其实就四组query 拿到结果集、moveToFirst/moveToNext 移动行指针、getColumnIndex 拿列下标再取值、close 释放资源。把这四组吃透Android 里 90% 的 Cursor 报错都能自己定位。2. TaoToken 前置统一 Key 打通 AI 辅助排查写 Cursor 代码时最烦的不是写不出来而是报错信息只有一行android.database.CursorIndexOutOfBoundsException: Index -1 requested, with a size of 5你得自己反推是哪一步 move 没做。这时候如果有个能直接贴代码和报错、帮你定位的 AI 工具效率会高很多。TaoToken 在这里的角色是「统一 Key 网关」你不需要为每个 AI 工具单独申请一套凭证用同一个 Key 就能在模型对话、Coding Plan、API 调用之间切换。对 Android 开发者来说最实用的两个入口是模型对话贴报错问原因和 Coding Plan长期编码辅助。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址https://taotoken.net/api需要先拿到 Key 的话去控制台的 API Keys 页面创建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite如果你主要做的是长期 Android 项目、需要 Agent 式的编码辅助可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite只是想快速贴一段 Cursor 报错问原因用模型对话就够了https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档在这里配置格式以它为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意TaoToken 是 AI 工具的统一接入层不替代 Android Studio 或任何编辑器。你的 Cursor 代码还是在 IDE 里写TaoToken 负责的是「把报错和代码片段发给 AI 帮你分析」这一段。3. 可复制配置Cursor 查询遍历完整代码先给一段能直接跑的完整代码基于 SQLiteOpenHelper 建一个 Book 表然后查询并遍历。这段代码覆盖了 query、moveToFirst、moveToNext、getColumnIndex、close 五个关键动作。3.1 建表与插入测试数据public class DbHelper extends SQLiteOpenHelper { private static final String DB_NAME book.db; private static final int VERSION 1; public DbHelper(Context context) { super(context, DB_NAME, null, VERSION); } Override public void onCreate(SQLiteDatabase db) { db.execSQL(CREATE TABLE Book ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, author TEXT, pages INTEGER, price REAL)); } Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { db.execSQL(DROP TABLE IF EXISTS Book); onCreate(db); } }插入几条数据方便验证SQLiteDatabase db dbHelper.getWritableDatabase(); db.execSQL(INSERT INTO Book (name, author, pages, price) VALUES (?, ?, ?, ?), new Object[]{Android 第一行代码, 郭霖, 520, 79.0}); db.execSQL(INSERT INTO Book (name, author, pages, price) VALUES (?, ?, ?, ?), new Object[]{Kotlin 实战, Dmitry, 380, 69.0});3.2 查询并遍历 Cursorpublic void queryBooks() { SQLiteDatabase db dbHelper.getReadableDatabase(); Cursor cursor null; try { cursor db.rawQuery(SELECT * FROM Book, null); if (cursor ! null cursor.moveToFirst()) { int nameIndex cursor.getColumnIndex(name); int authorIndex cursor.getColumnIndex(author); int pagesIndex cursor.getColumnIndex(pages); int priceIndex cursor.getColumnIndex(price); do { String name cursor.getString(nameIndex); String author cursor.getString(authorIndex); int pages cursor.getInt(pagesIndex); double price cursor.getDouble(priceIndex); Log.d(CursorDemo, name name , author author , pages pages , price price); } while (cursor.moveToNext()); } } finally { if (cursor ! null) { cursor.close(); } } }这段代码有几个关键点值得单独说。getColumnIndex返回的是列在结果集中的下标从 0 开始如果列名不存在会返回 -1。所以更稳妥的写法是用getColumnIndexOrThrow列名写错时直接抛IllegalArgumentException比拿到 -1 再去取值报越界更容易定位。moveToFirst()的返回值是 boolean表示是否成功移动到第一行。如果结果集为空它返回 false此时不能取值。这就是为什么外层要套if (cursor.moveToFirst())。do-while配合moveToNext()是标准遍历写法先处理当前行再尝试移到下一行移不动就退出。不要写成while (cursor.moveToNext())开头那样会漏掉第一行。3.3 用 for 循环的等价写法如果你习惯 for 循环可以用isAfterLast()判断for (cursor.moveToFirst(); !cursor.isAfterLast(); cursor.moveToNext()) { int nameIndex cursor.getColumnIndex(name); String name cursor.getString(nameIndex); Log.d(CursorDemo, name name); }这种写法在结果集为空时moveToFirst()返回 falseisAfterLast()为 true循环体一次都不执行也是安全的。3.4 TaoToken settings.json 配置骨架把 AI 辅助排查接进来以支持 settings.json 的工具为例配置骨架如下{ ai: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: 你的_TAOTOKEN_KEY, model: claude-sonnet, timeout: 30000 }, context: { includeFileTypes: [.java, .kt, .xml], maxFileSize: 200000 } }baseUrl用 API 地址不要带 UTM 参数。apiKey从控制台创建后填入不要硬编码提交到 Git 仓库建议用环境变量或本地 properties 文件读取。4. 验证请求确认 Cursor 遍历和 AI 接入都通了4.1 验证 Cursor 遍历结果跑完queryBooks()在 Logcat 里过滤CursorDemo标签应该看到两条记录D/CursorDemo: nameAndroid 第一行代码, author郭霖, pages520, price79.0 D/CursorDemo: nameKotlin 实战, authorDmitry, pages380, price69.0如果只看到一条检查是不是把do-while写成了while开头导致漏行。如果一条都没有检查moveToFirst()是否返回 false也就是查询结果为空。4.2 验证列索引取值单独打印列索引确认列名和下标对应关系Log.d(CursorDemo, nameIndex cursor.getColumnIndex(name)); Log.d(CursorDemo, notExistIndex cursor.getColumnIndex(not_exist_column));正常输出nameIndex1id 是 0notExistIndex-1。看到 -1 就说明列名写错了这时候用getColumnIndexOrThrow会直接抛异常比静默返回 -1 更好排查。4.3 验证 TaoToken 接入用 curl 发一个最小请求确认 Key 和地址可用curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的_TAOTOKEN_KEY \ -d { model: claude-sonnet, messages: [ {role: user, content: Android Cursor 报 CursorIndexOutOfBoundsException: Index -1 requested 是什么原因} ] }返回里有正常的choices内容说明 Key 和网络都通了。然后把这段报错和你的 Cursor 代码一起贴进模型对话让它帮你定位是哪一步 move 没做。5. 本篇常见错排查Cursor 报错对照表下面这张表覆盖了 Cursor 使用中最常见的几类异常遇到报错先对号入座。报错信息常见原因定位方法修复方式CursorIndexOutOfBoundsException: Index -1 requested没调 moveToFirst 就取值或 getColumnIndex 返回 -1打印 getColumnIndex 结果取值前先 moveToFirst列名用 getColumnIndexOrThrowCursorIndexOutOfBoundsException: Index 5 requested, size 5moveToNext 越界后仍取值检查循环条件用 do-while 或 isAfterLast 判断NullPointerException on cursor.getStringcursor 为 nullquery 失败检查 query 返回值加 null 判断检查表名和 SQLCursorWindowAllocationException结果集过大CursorWindow 内存不够看查询返回行数分页查询加 limit及时 closeIllegalArgumentException: column xxx does not existgetColumnIndexOrThrow 列名写错对照建表语句修正列名注意大小写游标泄漏Activity 退出后报错忘记 close用 try-finally 包裹finally 里 close或用 try-with-resources5.1 空指针的典型场景Cursor cursor db.query(Book, null, null, null, null, null, null); cursor.moveToFirst(); // 如果 query 返回 null 或结果为空这里可能出问题 String name cursor.getString(cursor.getColumnIndex(name));这段代码有两个隐患query 理论上可能返回 null虽然实际很少以及结果为空时 moveToFirst 返回 false 但代码没判断。正确写法是if (cursor ! null cursor.moveToFirst())。5.2 越界的典型场景cursor.moveToFirst(); while (!cursor.isAfterLast()) { String name cursor.getString(cursor.getColumnIndex(name)); cursor.moveToNext(); }这个写法本身没问题但如果把moveToNext()写在取值之前就会在最后一行之后还取一次值触发越界。记住顺序先判断位置有效再取值再移动。5.3 游标未关闭的后果Cursor 底层持有 CursorWindow不 close 会一直占着内存。在 Activity 里可以用startManagingCursor让 Activity 托管生命周期但这个方法在新版本里已经废弃推荐还是手动在 finally 里 close。如果一次查询返回几千行不 close 跑几次就会看到CursorWindowAllocationException。6. 语义一致 CTA把 AI 排查接进你的 Android 工作流Cursor 的坑基本集中在「位置」和「生命周期」两件事上位置没移对就取值报越界生命周期没管好报泄漏。把第 3 节的代码模板存下来每次写查询直接套能省掉大部分低级错误。遇到一时看不出来的报错把 Logcat 里的异常栈和对应的 Cursor 代码片段一起发给 AI让它帮你反推是哪一步 move 或 getColumnIndex 出了问题。统一 Key 的接入入口在这里模型对话贴报错问原因https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan长期 Android 项目编码辅助https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteAPI Keys创建和管理 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档配置格式以它为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后留一个实用习惯每次写完 Cursor 遍历先在 Logcat 里打印getCount()和每一行的getPosition()确认行指针移动轨迹符合预期再去接业务逻辑。这一步花不了两分钟但能挡掉后面大半的越界和空指针问题。