1. Android SQLite 查询踩坑现场Cursor 误用、事务缺失与主线程阻塞Android 自带的 SQLite 是每个 App 开发者绕不开的本地存储方案它轻量、无需额外依赖、随系统提供。但正因为“自带”很多人把它当成一个简单的 API 调用结果在 Cursor 游标管理、事务边界、线程调度上反复翻车。我见过太多项目在数据量小的时候一切正常一旦数据涨到几千条就开始出现查询结果缺行、界面卡顿、数据库锁死等问题。这篇文章聚焦三类高频错误Cursor 未关闭导致的资源泄漏、事务缺失导致的数据不一致、主线程直接查询导致的 ANR。同时我会把 TaoToken 统一 Key 的配置思路带进来——因为当你的 App 同时调用多个 AI 能力比如本地 SQLite 做缓存、远端模型做语义分析时鉴权和端点配置混乱会放大调试难度。用一个统一的 API 通道来管理 Key 和 Base URL能让你的排障路径清晰很多。适合谁看正在用 Android 原生 SQLite 做本地存储、遇到过 Cursor 结果不对或数据库卡顿、以及需要在多工具调用场景下统一管理鉴权配置的开发者。下面从一段真实的错误代码开始拆。1.1 那段“看起来没问题”的 Cursor 代码先看三段代码它们都能跑但结果不一样。// 第一段直接 while moveToNext Cursor cursor database.rawQuery(sql, null); System.out.println(cursor ); while (cursor.moveToNext()) { String province cursor.getString(cursor.getColumnIndex(PROVINCE)); list.add(province); count; }// 第二段moveToFirst do-while Cursor cursor database.rawQuery(sql, null); System.out.println(cursor ); cursor.moveToFirst(); do { String province cursor.getString(cursor.getColumnIndex(PROVINCE)); list.add(province); count; } while (cursor.moveToNext());// 第三段moveToFirst while致命 Cursor cursor database.rawQuery(sql, null); System.out.println(cursor ); cursor.moveToFirst(); while (cursor.moveToNext()) { String province cursor.getString(cursor.getColumnIndex(PROVINCE)); list.add(province); count; }第一段和第二段都能取到全部数据。第三段也能跑不报错但数据库里的第一条永远取不到。原因在于moveToFirst()已经把游标定位到第一行紧接着while (cursor.moveToNext())又往下移了一行第一行就被跳过了。正确做法只有两种要么不用moveToFirst()直接while (moveToNext())要么用了moveToFirst()之后必须配do-while。这个坑我在早期项目里踩过当时数据只有几条测试没发现上线后用户反馈“列表少了一条”排查了半天才定位到游标位置问题。更隐蔽的是这段代码还没有关闭 Cursor。Android 的 Cursor 是底层 SQLite 游标的一个窗口不关闭会持有资源在频繁查询场景下会触发CursorWindowAllocationException或者数据库连接泄漏。下面把完整的避坑方案拆开讲。2. TaoToken 统一 Key 前置配置多工具调用时的鉴权与端点管理在深入 SQLite 代码之前先解决一个容易被忽视的环境问题当你的调试流程里同时涉及本地数据库查询、远端模型调用、日志分析工具时每个工具各自维护一套 API Key 和 Base URL出错时你根本分不清是数据库问题还是鉴权问题。TaoToken 的思路是用一个统一 Key 走同一个 API 通道把鉴权配置收敛到一处。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数保持干净。你需要先拿到一个 Key。进入控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建完成后在 API Keys 页面复制https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite如果你用的是 Claude Code 这类编码工具接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code 的 Anthropic 兼容端点https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite为什么要先讲这个因为后面验证 SQLite 查询正确性时我会用单元测试 日志的方式而日志分析如果接入模型做语义归类就需要一个稳定的 API 通道。统一 Key 的好处是Base URL 只配一次Model ID 只写一次出错时先看 401 还是本地代理失败排障路径缩短一半。对于长期做 Android 编码和 Agent 调试的场景Coding Plan 更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite模型对话调试入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite配置的核心三件套永远是Base URL、Key、Model ID。缺一个都会在请求时暴露问题。下面进入 SQLite 的具体配置和代码。3. 可复制配置SQLite 事务、Cursor 管理与 auth.json 示例3.1 Cursor 的正确打开与关闭方式Android 中查询 SQLite 推荐用try-finally或 try-with-resources 确保 Cursor 关闭。从 API 16 开始 Cursor 实现了Closeable可以这样写public ListString queryProvinces(SQLiteDatabase db, String sql) { ListString list new ArrayList(); try (Cursor cursor db.rawQuery(sql, null)) { // 不使用 moveToFirst直接 while moveToNext while (cursor.moveToNext()) { int index cursor.getColumnIndex(PROVINCE); if (index 0) { list.add(cursor.getString(index)); } } } return list; }如果你确实需要先判断是否有数据用moveToFirst()的返回值然后配do-whiletry (Cursor cursor db.rawQuery(sql, null)) { if (cursor.moveToFirst()) { do { int index cursor.getColumnIndex(PROVINCE); if (index 0) { list.add(cursor.getString(index)); } } while (cursor.moveToNext()); } }注意getColumnIndex返回 -1 的情况直接getString(-1)会抛异常。生产代码里加一层判断。3.2 事务配置批量写入必须包事务单条 insert 不包事务也能跑但批量写入不包事务每条都是一个独立事务速度慢几十倍而且中途失败会导致部分写入。正确写法public void batchInsert(SQLiteDatabase db, ListProvince dataList) { db.beginTransaction(); try { for (Province p : dataList) { ContentValues values new ContentValues(); values.put(PROVINCE, p.getName()); values.put(CODE, p.getCode()); db.insert(province_table, null, values); } db.setTransactionSuccessful(); } finally { db.endTransaction(); } }setTransactionSuccessful()必须在endTransaction()之前调用否则事务会回滚。这个顺序写反了不会报错但数据全部丢失非常隐蔽。3.3 主线程查询的替代方案Android 在主线程做数据库查询会触发StrictMode警告数据量大时直接 ANR。用 Executor 或 Room 的异步查询替代private final ExecutorService executor Executors.newSingleThreadExecutor(); public void queryAsync(SQLiteDatabase db, String sql, ConsumerListString callback) { executor.execute(() - { ListString result queryProvinces(db, sql); new Handler(Looper.getMainLooper()).post(() - callback.accept(result)); }); }3.4 auth.json 配置示例Codex 场景如果你在用 Codex 或类似工具做辅助调试auth.json的配置需要写全三件套。路径通常在用户目录下的配置文件夹{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514 }注意 Base URL 不要带 UTM 参数保持https://taotoken.net/api干净。Model ID 按你实际使用的模型填写。这个文件如果只写了 Key 没写 Base URL请求会打到默认端点出现 401 或连接失败。3.5 settings 片段Claude Code 场景Claude Code 的 settings 配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/ClaudeCodeAnthropic, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }三件套齐全Base URL、Key、Model ID。少任何一个都会在启动时报错。4. 验证请求与成功结果日志与单元测试确认查询正确性配置写完了怎么确认 SQLite 查询真的取到了全部数据靠日志和单元测试。4.1 用日志打印游标行数和实际数据在查询方法里加日志try (Cursor cursor db.rawQuery(sql, null)) { int total cursor.getCount(); Log.d(SQLiteDebug, cursor count total); while (cursor.moveToNext()) { String province cursor.getString(cursor.getColumnIndex(PROVINCE)); Log.d(SQLiteDebug, row: province); list.add(province); } Log.d(SQLiteDebug, list size list.size()); }如果cursor count是 10list size是 9说明游标位置逻辑有问题大概率是moveToFirstwhile的组合。如果cursor count是 0说明 SQL 条件或表数据有问题。4.2 单元测试验证用 AndroidJUnit4 写一个本地测试Test public void testQueryAllProvinces() { SQLiteDatabase db SQLiteDatabase.create(null); db.execSQL(CREATE TABLE province_table (PROVINCE TEXT, CODE TEXT)); db.execSQL(INSERT INTO province_table VALUES (北京, 110000)); db.execSQL(INSERT INTO province_table VALUES (上海, 310000)); db.execSQL(INSERT INTO province_table VALUES (广东, 440000)); ListString result queryProvinces(db, SELECT PROVINCE FROM province_table); assertEquals(3, result.size()); assertEquals(北京, result.get(0)); assertEquals(上海, result.get(1)); assertEquals(广东, result.get(2)); }这个测试能直接暴露“第一条取不到”的问题。如果断言失败检查游标循环方式。4.3 用模型对话验证日志语义当日志量大时可以把日志片段贴到模型对话里做归类分析https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite比如把cursor count 10, list size 9这样的日志发给模型让它帮你判断是游标问题还是数据问题。统一 Key 的好处在这里体现同一个 Key 既能调模型又能保持端点一致不用来回切换配置。4.4 成功结果的样子正确的查询日志应该是cursor count 3 row: 北京 row: 上海 row: 广东 list size 3cursor count和list size一致每条数据都打印出来。如果list size比cursor count少 1就是游标跳过了第一行。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized报错原文HTTP 401 Unauthorized: invalid api key原因Key 没配、Key 过期、或者 Base URL 和 Key 不匹配。检查auth.json或settings里的api_key字段是否填写正确。如果用的是环境变量确认变量名没拼错。5.2 local proxy failed报错原文local proxy failed: connection refused原因本地代理配置指向了一个不可用的地址。检查 Base URL 是否写成了https://taotoken.net/api不要多加路径或参数。如果之前配过其他端点清理掉旧配置。5.3 reading choices 相关报错报错原文error reading choices: unexpected end of JSON input原因请求返回的不是标准 JSON通常是端点配错或网络中断。确认 Base URL 完整Model ID 存在。如果用的是 Claude Code检查ANTHROPIC_BASE_URL是否指向https://taotoken.net/ClaudeCodeAnthropic。5.4 OAuth 相关报错报错原文OAuth token expired or invalid原因OAuth 流程的 token 过期。重新走一遍授权流程或者改用 API Key 方式。如果同时配了 OAuth 和 API Key优先使用 API Key避免冲突。5.5 SQLite 相关报错对照报错原因解决CursorWindowAllocationExceptionCursor 未关闭窗口内存耗尽try-with-resources 关闭 Cursordatabase is locked多线程同时写未加事务用事务包裹批量写单线程写ANR on query主线程查询移到 Executor 异步执行第一条数据丢失moveToFirst while改 do-while 或去掉 moveToFirst5.6 配置检查清单每次遇到鉴权问题按这个顺序查Base URL 是否完整且无多余参数、Key 是否有效、Model ID 是否存在、配置文件路径是否正确。三件套齐全后大部分 401 和连接失败都能解决。6. 统一 Key 与 SQLite 调试的配合CTA 与后续动作SQLite 的坑集中在游标、事务、线程三处而多工具调用时的坑集中在鉴权和端点配置。把这两类问题分开排查效率会高很多。TaoToken 统一 Key 的价值在于当你用模型辅助分析 SQLite 日志时不需要为每个工具单独配 KeyBase URL 和 Model ID 写一次就行。排障和接入相关的入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite验证模型是否正常响应https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite长期编码和 Agent 调试https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite最后给一个实用技巧在 SQLite 查询方法里加一行Log.d打印cursor.getCount()和list.size()这两个数字不一致时立刻能定位到游标问题。这个习惯帮我省了很多排查时间。配置方面auth.json和settings里的三件套写全Base URL 保持https://taotoken.net/api干净401 和连接失败基本不会再出现。