1. 从一次崩溃说起SQLiteDatabase 到底解决什么问题如果你刚开始做 Android 本地存储大概率会遇到这样的场景用户填了一堆表单切到后台再回来数据全没了或者你想缓存一份离线列表用 SharedPreferences 存又发现只能塞键值对稍微复杂一点的结构就写不下去。这时候 SQLiteDatabase 就是那个绕不开的东西。SQLiteDatabase 是 Android 系统内置的轻量级关系型数据库操作入口它代表一个已经打开的数据库连接你能通过它执行建表、插入、查询、更新、删除这些 SQL 语句。它适合谁适合需要在手机本地持久化结构化数据的场景比如记账 App 的交易记录、待办清单的任务表、离线缓存的文章列表。它不需要你额外装数据库服务一个文件就是一个库跟着 App 走。我试过在没封装好的情况下直接裸写 SQL结果就是到处拼字符串、Cursor 忘了关、事务没提交导致数据半截写入。所以这篇不打算只讲 API 名字而是把「建库 → 建表 → 增删改查 → 事务 → adb 验证」整条链路拆开给你一份能直接复制的 SQLiteOpenHelper 骨架再配上一份 config.toml 配置片段让你一次跑通。核心检索词先摆在这SQLiteDatabase 数据库操作全流程重点就是建库、建表、CRUD、事务这四件事。下面每一步我都会给出可执行代码和验证命令你跟着敲就行。2. 前置准备TaoToken 配置骨架与项目环境在写数据库代码之前先把环境和一个容易被忽略的配置环节理清楚。很多同学卡在「代码写完了但跑不起来」往往不是 SQL 写错而是依赖或配置没对齐。2.1 项目依赖与目录约定新建一个 Empty Views Activity 项目包名假设为com.example.sqlitedemo。在app/build.gradle里确认有这些基础依赖SQLiteDatabase 是系统 API不需要额外引入数据库库android { namespace com.example.sqlitedemo compileSdk 34 defaultConfig { applicationId com.example.sqlitedemo minSdk 24 targetSdk 34 versionCode 1 versionName 1.0 } } dependencies { implementation androidx.appcompat:appcompat:1.6.1 implementation com.google.android.material:material:1.11.0 }数据库文件默认会落在/data/data/包名/databases/目录下这个路径后面用 adb 验证时会用到。2.2 TaoToken 配置片段把模型能力接进你的调试链路写数据库的过程中你可能会想让模型帮你生成建表语句、解释报错、或者把一段 Cursor 遍历代码改写成更安全的写法。这时候可以用 TaoToken 的 API 作为辅助。它的 Base URL 是https://taotoken.net/api模型对话入口在 deep link 里。下面是一份config.toml配置片段路径放在项目根目录的config/config.toml你可以直接复制# config/config.toml [provider] name taotoken base_url https://taotoken.net/api api_key sk-你的Key timeout_seconds 30 [model] id claude-sonnet-4-20250514 max_tokens 2048 temperature 0.3 [task] # 用于生成 SQL 建表语句与排错 mode coding prompt_template 你是 Android SQLite 助手请根据以下需求生成可执行的 SQL 与 Java 代码{input}注意三件套要写全Base URL 用https://taotoken.net/apiKey 去控制台生成Model ID 按你实际可用的填。如果你用的是 Claude Code 这类工具配置方式类似把 Base URL 和 Key 填进对应字段即可。API Key 的获取入口在https://taotoken.net/api-keys模型对话在https://taotoken.net/model-chat接入文档在https://taotoken.net/doc。注意config.toml 里的 api_key 不要提交到 Git建议用.gitignore排除或者用环境变量注入。2.3 为什么数据库项目也需要这个配置不是必须但很实用。比如你写了一个CREATE TABLE语句运行时抛了no such column把报错贴给模型它能快速定位是列名拼写还是版本迁移问题。再比如事务那块beginTransaction和setTransactionSuccessful的配对新手很容易漏掉endTransaction让模型帮你 review 一遍能省不少调试时间。环境准备好之后下面进入真正的代码环节。3. 可复制配置SQLiteOpenHelper 骨架与建表语句这一节是全文的核心给你一份完整的DbHelper骨架包含建库、建表、版本管理以及 CRUD 和事务方法。你可以直接复制到项目里改包名使用。3.1 SQLiteOpenHelper 完整骨架新建DbHelper.java继承SQLiteOpenHelperpackage com.example.sqlitedemo; import android.content.ContentValues; import android.content.Context; import android.database.Cursor; import android.database.sqlite.SQLiteDatabase; import android.database.sqlite.SQLiteOpenHelper; public class DbHelper extends SQLiteOpenHelper { private static final String DB_NAME demo.db; private static final int DB_VERSION 1; public static final String TABLE_TASK task; public static final String COL_ID _id; public static final String COL_TITLE title; public static final String COL_DONE done; private static final String SQL_CREATE_TASK CREATE TABLE TABLE_TASK ( COL_ID INTEGER PRIMARY KEY AUTOINCREMENT, COL_TITLE TEXT NOT NULL, COL_DONE INTEGER DEFAULT 0); public DbHelper(Context context) { super(context, DB_NAME, null, DB_VERSION); } Override public void onCreate(SQLiteDatabase db) { db.execSQL(SQL_CREATE_TASK); } Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { db.execSQL(DROP TABLE IF EXISTS TABLE_TASK); onCreate(db); } }这里几个关键点DB_VERSION从 1 开始以后加字段就把它加 1onUpgrade里做迁移。onCreate只在数据库文件第一次创建时调用所以建表语句放这里。3.2 增删改查方法封装在DbHelper里继续加方法用ContentValues而不是拼字符串避免 SQL 注入public long insertTask(String title) { SQLiteDatabase db getWritableDatabase(); ContentValues values new ContentValues(); values.put(COL_TITLE, title); values.put(COL_DONE, 0); return db.insert(TABLE_TASK, null, values); } public int updateTaskDone(long id, boolean done) { SQLiteDatabase db getWritableDatabase(); ContentValues values new ContentValues(); values.put(COL_DONE, done ? 1 : 0); return db.update(TABLE_TASK, values, COL_ID ?, new String[]{String.valueOf(id)}); } public int deleteTask(long id) { SQLiteDatabase db getWritableDatabase(); return db.delete(TABLE_TASK, COL_ID ?, new String[]{String.valueOf(id)}); } public Cursor queryAll() { SQLiteDatabase db getReadableDatabase(); return db.query(TABLE_TASK, null, null, null, null, null, COL_ID DESC); }注意getWritableDatabase()用于写操作getReadableDatabase()用于读。查询返回Cursor用完必须close()否则会泄漏。3.3 事务处理批量插入的正确姿势事务是新手最容易踩坑的地方。批量插入 100 条数据如果不用事务每条都触发一次磁盘写入慢且容易半途失败。正确写法public void insertBatch(ListString titles) { SQLiteDatabase db getWritableDatabase(); db.beginTransaction(); try { for (String title : titles) { ContentValues values new ContentValues(); values.put(COL_TITLE, title); values.put(COL_DONE, 0); db.insert(TABLE_TASK, null, values); } db.setTransactionSuccessful(); } finally { db.endTransaction(); } }beginTransaction开启setTransactionSuccessful标记成功endTransaction结束。如果中间抛异常没有标记成功endTransaction会自动回滚。这个 try-finally 结构一定要背下来。3.4 在 Activity 里调用DbHelper helper new DbHelper(this); long id helper.insertTask(写数据库教程); Cursor cursor helper.queryAll(); while (cursor.moveToNext()) { String title cursor.getString( cursor.getColumnIndexOrThrow(DbHelper.COL_TITLE)); int done cursor.getInt( cursor.getColumnIndexOrThrow(DbHelper.COL_DONE)); // 处理数据 } cursor.close(); helper.close();到这里建库、建表、CRUD、事务的骨架就齐了。下面用 adb 验证它真的跑通了。4. 验证请求adb 查看数据库文件与查询结果代码写完了不代表数据真的落盘了。用 adb 直接看数据库文件是最踏实的验证方式。4.1 确认数据库文件生成先跑一次 App触发一次插入操作然后在终端执行adb shell run-as com.example.sqlitedemo ls -l /data/data/com.example.sqlitedemo/databases/如果看到demo.db和demo.db-journal或-wal说明建库成功。run-as用于以 App 身份访问私有目录debug 包才可用。4.2 用 sqlite3 查询表内容进入设备 shelladb shell run-as com.example.sqlitedemo cd databases sqlite3 demo.db进去之后执行.tables .schema task SELECT * FROM task;.tables列出所有表.schema task看建表语句SELECT *看数据。如果能看到你插入的 title说明整条链路通了。4.3 用 TaoToken 辅助排查 SQL 报错如果SELECT报no such table把.schema的输出和你的建表语句贴给模型让它对比。模型对话入口在https://taotoken.net/model-chat把报错原文和代码一起发过去通常几秒就能定位。这一步不是必须但能省下翻文档的时间。4.4 验证事务回滚想确认事务真的生效可以在insertBatch里故意在循环中间抛一个RuntimeException然后重新跑再用SELECT COUNT(*) FROM task看数量。如果数量没变说明回滚成功。这个实验做一次你对事务的理解会深很多。5. 常见报错排查401、local proxy failed 与 Cursor 泄漏这一节把几个高频报错列出来对照着查。5.1 401 Unauthorized如果你在调用 TaoToken API 时遇到 401先检查config.toml里的api_key是否填对有没有多余空格。Base URL 必须是https://taotoken.net/api不要漏掉/api。Key 去https://taotoken.net/api-keys重新生成一个再试。5.2 local proxy failed这个报错通常出现在网络层说明请求没发出去。检查你的base_url是否写成了https://taotoken.net少了/api或者timeout_seconds设得太短。把超时调到 30 秒以上再试。5.3 reading choices 相关报错如果你用的是兼容 OpenAI 格式的调用返回体里没有choices字段多半是 Model ID 填错了。确认config.toml里的id是你账号下真实可用的模型不要凭记忆写。5.4 Cursor 泄漏与 OAuth 无关但同样致命Cursor用完不close()日志里会出现CursorWindow相关警告严重时 App 直接崩。养成习惯查询方法返回 Cursor 后调用方用 try-finally 包住或者用try (Cursor c ...)语法。另外SQLiteDatabase本身在 Activity 销毁时也要close()否则连接一直占着。5.5 三件套检查清单无论你用的是 CC Switch、Cline MCP 还是 Codex 的auth.json只要涉及模型接入三件套必须写全Base URL 用https://taotoken.net/apiKey 用控制台生成的Model ID 用实际可用的。少任何一个都会报错。auth.json里对应字段是base_url、api_key、model别写错键名。6. 把这条链路用起来从本地库到长期编码数据库骨架跑通之后你可以把它当成一个模板后面每加一张表就复制一份建表语句版本号加一在onUpgrade里写迁移。事务那块封装成通用方法批量操作都走它。如果你打算长期做 Android 开发或者想让模型持续帮你 review 数据库代码可以考虑用 Coding Plan入口在https://taotoken.net/coding-plan。它适合需要反复调试、迭代代码的场景比单次对话更顺手。接入文档在https://taotoken.net/doc遇到配置问题先翻文档大部分坑里面都有写。最后留一个实用技巧每次改完DbHelper先卸载 App 再重装确保onCreate重新执行避免旧数据库文件干扰。验证时优先用 adb 看真实文件别只信 Logcat。数据库这东西眼见为实。