1. 為什么 Android 里的 Cursor 總讓人踩坑Cursor 是 Android 訪問 SQLite 和 ContentProvider 數(shù)據(jù)時繞不開的一個類。你可以把它理解成一個「游標(biāo)卡尺」查詢語句執(zhí)行完數(shù)據(jù)并不會一次性全塞進(jìn)內(nèi)存而是放在一個結(jié)果集里Cursor 就是指向這個結(jié)果集某一行的指針。它本身不存數(shù)據(jù)只負(fù)責(zé)定位和取值。很多剛接觸 Android 數(shù)據(jù)讀取的朋友第一次寫db.query()拿到 Cursor 后直接cursor.getString(0)就崩了報CursorIndexOutOfBoundsException或者遍歷完忘了close()跑幾次之后日志里開始刷CursorWindowAllocationException。這些問題的根源都是沒搞清楚 Cursor 的「行指針」模型和「列索引」機(jī)制。這篇內(nèi)容面向的是本地 SQLite / ContentProvider 數(shù)據(jù)讀取場景目標(biāo)是讓你能獨(dú)立寫出可運(yùn)行的 Cursor 遍歷代碼并且遇到空指針、越界、游標(biāo)未關(guān)閉這幾類問題時知道從哪一行開始查。同時我會給出一套通過 TaoToken 統(tǒng)一 Key 接入 AI 輔助排查的配置骨架把「寫代碼」和「問 AI 定位問題」串成一條線。Cursor 的核心操作其實(shí)就四組query 拿到結(jié)果集、moveToFirst/moveToNext 移動行指針、getColumnIndex 拿列下標(biāo)再取值、close 釋放資源。把這四組吃透Android 里 90% 的 Cursor 報錯都能自己定位。2. TaoToken 前置統(tǒng)一 Key 打通 AI 輔助排查寫 Cursor 代碼時最煩的不是寫不出來而是報錯信息只有一行android.database.CursorIndexOutOfBoundsException: Index -1 requested, with a size of 5你得自己反推是哪一步 move 沒做。這時候如果有個能直接貼代碼和報錯、幫你定位的 AI 工具效率會高很多。TaoToken 在這里的角色是「統(tǒng)一 Key 網(wǎng)關(guān)」你不需要為每個 AI 工具單獨(dú)申請一套憑證用同一個 Key 就能在模型對話、Coding Plan、API 調(diào)用之間切換。對 Android 開發(fā)者來說最實(shí)用的兩個入口是模型對話貼報錯問原因和 Coding Plan長期編碼輔助。官網(wǎng)入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基礎(chǔ)地址https://taotoken.net/api需要先拿到 Key 的話去控制臺的 API Keys 頁面創(chuàng)建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite如果你主要做的是長期 Android 項(xiàng)目、需要 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接入文檔在這里配置格式以它為準(zhǔn)https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意TaoToken 是 AI 工具的統(tǒng)一接入層不替代 Android Studio 或任何編輯器。你的 Cursor 代碼還是在 IDE 里寫TaoToken 負(fù)責(zé)的是「把報錯和代碼片段發(fā)給 AI 幫你分析」這一段。3. 可復(fù)制配置Cursor 查詢遍歷完整代碼先給一段能直接跑的完整代碼基于 SQLiteOpenHelper 建一個 Book 表然后查詢并遍歷。這段代碼覆蓋了 query、moveToFirst、moveToNext、getColumnIndex、close 五個關(guān)鍵動作。3.1 建表與插入測試數(shù)據(jù)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); } }插入幾條數(shù)據(jù)方便驗(yàn)證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 實(shí)戰(zhàn), 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(); } } }這段代碼有幾個關(guān)鍵點(diǎn)值得單獨(dú)說。getColumnIndex返回的是列在結(jié)果集中的下標(biāo)從 0 開始如果列名不存在會返回 -1。所以更穩(wěn)妥的寫法是用getColumnIndexOrThrow列名寫錯時直接拋IllegalArgumentException比拿到 -1 再去取值報越界更容易定位。moveToFirst()的返回值是 boolean表示是否成功移動到第一行。如果結(jié)果集為空它返回 false此時不能取值。這就是為什么外層要套if (cursor.moveToFirst())。do-while配合moveToNext()是標(biāo)準(zhǔn)遍歷寫法先處理當(dāng)前行再嘗試移到下一行移不動就退出。不要寫成while (cursor.moveToNext())開頭那樣會漏掉第一行。3.3 用 for 循環(huán)的等價寫法如果你習(xí)慣 for 循環(huán)可以用isAfterLast()判斷for (cursor.moveToFirst(); !cursor.isAfterLast(); cursor.moveToNext()) { int nameIndex cursor.getColumnIndex(name); String name cursor.getString(nameIndex); Log.d(CursorDemo, name name); }這種寫法在結(jié)果集為空時moveToFirst()返回 falseisAfterLast()為 true循環(huán)體一次都不執(zhí)行也是安全的。3.4 TaoToken settings.json 配置骨架把 AI 輔助排查接進(jìn)來以支持 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 參數(shù)。apiKey從控制臺創(chuàng)建后填入不要硬編碼提交到 Git 倉庫建議用環(huán)境變量或本地 properties 文件讀取。4. 驗(yàn)證請求確認(rèn) Cursor 遍歷和 AI 接入都通了4.1 驗(yàn)證 Cursor 遍歷結(jié)果跑完queryBooks()在 Logcat 里過濾CursorDemo標(biāo)簽應(yīng)該看到兩條記錄D/CursorDemo: nameAndroid 第一行代碼, author郭霖, pages520, price79.0 D/CursorDemo: nameKotlin 實(shí)戰(zhàn), authorDmitry, pages380, price69.0如果只看到一條檢查是不是把do-while寫成了while開頭導(dǎo)致漏行。如果一條都沒有檢查moveToFirst()是否返回 false也就是查詢結(jié)果為空。4.2 驗(yàn)證列索引取值單獨(dú)打印列索引確認(rèn)列名和下標(biāo)對應(yīng)關(guān)系Log.d(CursorDemo, nameIndex cursor.getColumnIndex(name)); Log.d(CursorDemo, notExistIndex cursor.getColumnIndex(not_exist_column));正常輸出nameIndex1id 是 0notExistIndex-1。看到 -1 就說明列名寫錯了這時候用getColumnIndexOrThrow會直接拋異常比靜默返回 -1 更好排查。4.3 驗(yàn)證 TaoToken 接入用 curl 發(fā)一個最小請求確認(rèn) 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內(nèi)容說明 Key 和網(wǎng)絡(luò)都通了。然后把這段報錯和你的 Cursor 代碼一起貼進(jìn)模型對話讓它幫你定位是哪一步 move 沒做。5. 本篇常見錯排查Cursor 報錯對照表下面這張表覆蓋了 Cursor 使用中最常見的幾類異常遇到報錯先對號入座。報錯信息常見原因定位方法修復(fù)方式CursorIndexOutOfBoundsException: Index -1 requested沒調(diào) moveToFirst 就取值或 getColumnIndex 返回 -1打印 getColumnIndex 結(jié)果取值前先 moveToFirst列名用 getColumnIndexOrThrowCursorIndexOutOfBoundsException: Index 5 requested, size 5moveToNext 越界后仍取值檢查循環(huán)條件用 do-while 或 isAfterLast 判斷NullPointerException on cursor.getStringcursor 為 nullquery 失敗檢查 query 返回值加 null 判斷檢查表名和 SQLCursorWindowAllocationException結(jié)果集過大CursorWindow 內(nèi)存不夠看查詢返回行數(shù)分頁查詢加 limit及時 closeIllegalArgumentException: column xxx does not existgetColumnIndexOrThrow 列名寫錯對照建表語句修正列名注意大小寫游標(biāo)泄漏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 或結(jié)果為空這里可能出問題 String name cursor.getString(cursor.getColumnIndex(name));這段代碼有兩個隱患query 理論上可能返回 null雖然實(shí)際很少以及結(jié)果為空時 moveToFirst 返回 false 但代碼沒判斷。正確寫法是if (cursor ! null cursor.moveToFirst())。5.2 越界的典型場景cursor.moveToFirst(); while (!cursor.isAfterLast()) { String name cursor.getString(cursor.getColumnIndex(name)); cursor.moveToNext(); }這個寫法本身沒問題但如果把moveToNext()寫在取值之前就會在最后一行之后還取一次值觸發(fā)越界。記住順序先判斷位置有效再取值再移動。5.3 游標(biāo)未關(guān)閉的后果Cursor 底層持有 CursorWindow不 close 會一直占著內(nèi)存。在 Activity 里可以用startManagingCursor讓 Activity 托管生命周期但這個方法在新版本里已經(jīng)廢棄推薦還是手動在 finally 里 close。如果一次查詢返回幾千行不 close 跑幾次就會看到CursorWindowAllocationException。6. 語義一致 CTA把 AI 排查接進(jìn)你的 Android 工作流Cursor 的坑基本集中在「位置」和「生命周期」兩件事上位置沒移對就取值報越界生命周期沒管好報泄漏。把第 3 節(jié)的代碼模板存下來每次寫查詢直接套能省掉大部分低級錯誤。遇到一時看不出來的報錯把 Logcat 里的異常棧和對應(yīng)的 Cursor 代碼片段一起發(fā)給 AI讓它幫你反推是哪一步 move 或 getColumnIndex 出了問題。統(tǒng)一 Key 的接入入口在這里模型對話貼報錯問原因https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan長期 Android 項(xiàng)目編碼輔助https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteAPI Keys創(chuàng)建和管理 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文檔配置格式以它為準(zhǔn)https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后留一個實(shí)用習(xí)慣每次寫完 Cursor 遍歷先在 Logcat 里打印getCount()和每一行的getPosition()確認(rèn)行指針移動軌跡符合預(yù)期再去接業(yè)務(wù)邏輯。這一步花不了兩分鐘但能擋掉后面大半的越界和空指針問題。