18.1 这节课解决什么问题
第 17 课的 HistoryStore 还是内存假实现——App 一重启历史全丢。本课把它换成 SQLite 本地数据库,回答三件事:
1① rusqlite:怎么连、怎么建表、怎么读写(参数化查询防注入) 2② 表结构 & 迁移:schema 版本升级不丢数据 3③ 把 sqlite 实现塞回 core:服务层测试一行不改(17 课接口红利的兑现) 4
同时处理 SQLite 在真实 App 里最常见的"最后 20%":忙锁(database is locked)、连接共享、并发读写。这些坑恰恰是 UniFFI(19-21 课)把 core 暴露给多个 UI 线程后必然撞上的。
💡 为什么本地存储选 SQLite 而不是"写个 JSON 文件"?历史记录会持续增长,需要随机查询单会话/删除/排序——JSON 全量读改写在大数据量下又慢又容易坏。SQLite 单文件、零服务、SQL 能力完整,是移动/桌面端本地存储的事实标准。会话与消息的结构化适合表;而"聊天原样快照"之类大对象适合存成 JSON 列/独立文件——两种都会在本课出现。
18.2 rusqlite 起步:打开连接 + 最小读写
1# core/Cargo.toml 追加 2[dependencies] 3rusqlite = { version = "0.32", features = ["bundled"] } # bundled:免系统 SQLite,跨端更省心 4chrono 不再需要——时间用 i64 毫秒(第 17 课 now_ms) 5
1// store/sqlite.rs —— 新的模块 2use rusqlite::Connection; 3use std::path::Path; 4 5pub struct SqliteStore { 6 conn: Connection, 7} 8 9impl SqliteStore { 10 /// 打开(或创建)数据库文件 11 pub fn open(path: impl AsRef<Path>) -> Result<Self, rusqlite::Error> { 12 let conn = Connection::open(path)?; 13 conn.pragma_update(None, "journal_mode", "WAL")?; // 见 18.5 14 conn.pragma_update(None, "foreign_keys", "ON")?; 15 let store = SqliteStore { conn }; 16 store.migrate()?; // 见 18.3 17 Ok(store) 18 } 19} 20
最小读写样例(临时库,:memory: 可用于测试):
1use rusqlite::{params, Connection}; 2 3fn main() -> rusqlite::Result<()> { 4 let conn = Connection::open_in_memory()?; 5 6 conn.execute("CREATE TABLE kv (k TEXT PRIMARY KEY, v TEXT NOT NULL)", [])?; 7 8 // 参数化插入(占位符 ?1,值作为参数传入 → 自动防注入) 9 conn.execute("INSERT INTO kv (k, v) VALUES (?1, ?2)", params!["greeting", "你好"])?; 10 11 // 参数化查询 12 let v: String = conn.query_row( 13 "SELECT v FROM kv WHERE k = ?1", 14 ["greeting"], 15 |row| row.get(0), 16 )?; 17 println!("{v}"); 18 19 // 多行读取(迭代 Statement) 20 let mut stmt = conn.prepare("SELECT k, v FROM kv")?; 21 let rows = stmt.query_map([], |row| { 22 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?)) 23 })?; 24 for pair in rows { 25 println!("{:?}", pair?); 26 } 27 Ok(()) 28} 29
⚠️ 永远用参数化,绝不要字符串拼接 SQL:
1// ❌ 注入风险 + 引号转义地狱 2let sql = format!("INSERT INTO kv VALUES ('{}')", user_input); 3// ✅ 参数绑定:rusqlite 负责转义,SQL 与数据分离 4conn.execute("INSERT INTO kv VALUES (?1)", params![user_input])?; 5
18.3 表结构与迁移:schema 版本化
18.3.1 建表 DDL
1-- sessions:会话表 2CREATE TABLE IF NOT EXISTS sessions ( 3 id TEXT PRIMARY KEY, -- "s-<ms>-<rand>" 4 title TEXT NOT NULL, 5 created_at_ms INTEGER NOT NULL 6); 7 8-- messages:消息表 9CREATE TABLE IF NOT EXISTS messages ( 10 id TEXT PRIMARY KEY, 11 session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE, 12 role TEXT NOT NULL, -- 'user' / 'assistant' / 'system' 13 content TEXT NOT NULL, 14 created_at_ms INTEGER NOT NULL 15); 16 17CREATE INDEX IF NOT EXISTS idx_messages_session 18 ON messages (session_id, created_at_ms); 19
ON DELETE CASCADE:删会话自动连带删消息(17 课 delete_session 就两个动作,其实库层一步到位);- 索引建在
(session_id, created_at_ms)上:查单会话历史只走索引,随数据增长不退化; role用 TEXT 存,读出来再转Role枚举(写入反过来)——不存 SQLite 不认识的 Rust enum。
18.3.2 用 PRAGMA user_version 做轻量迁移
1impl SqliteStore { 2 /// 简单迁移:记录 schema 版本号,逐版升级 3 fn migrate(&self) -> rusqlite::Result<()> { 4 let cur: i64 = self.conn.query_row("PRAGMA user_version", [], |r| r.get(0))?; 5 6 if cur < 1 { 7 self.conn.execute_batch( 8 "BEGIN; 9 CREATE TABLE IF NOT EXISTS sessions (...同 18.3.1...); 10 CREATE TABLE IF NOT EXISTS messages (...); 11 CREATE INDEX ...; 12 PRAGMA user_version = 1; 13 COMMIT;", 14 )?; 15 } 16 // 将来加字段/加表:if cur < 2 { ... PRAGMA user_version = 2; } 17 Ok(()) 18 } 19} 20
💡 真实项目可用
rusqlite_migration这类 crate 管理有序迁移脚本;但"用户版本号 + 逐段 execute_batch"的原生写法已经足够支撑本课程规模,且零额外依赖。关键是养成习惯:任何 schema 变更都必须是"新增一段 if 版本号"的迁移,而不是改旧 SQL——否则老用户升级必炸。
18.4 实现 HistoryStore for SqliteStore
1use crate::models::{Message, Role, Session}; 2use crate::store::{HistoryStore, StoreError}; 3use rusqlite::params; 4 5impl HistoryStore for SqliteStore { 6 fn create_session(&self, session: &Session) -> Result<(), StoreError> { 7 self.conn 8 .execute( 9 "INSERT INTO sessions (id, title, created_at_ms) VALUES (?1, ?2, ?3)", 10 params![session.id, session.title, session.created_at_ms], 11 ) 12 .map_err(map_err)?; 13 Ok(()) 14 } 15 16 fn list_sessions(&self, limit: u32) -> Result<Vec<Session>, StoreError> { 17 let mut stmt = self 18 .conn 19 .prepare("SELECT id, title, created_at_ms FROM sessions ORDER BY created_at_ms DESC LIMIT ?1") 20 .map_err(map_err)?; 21 let rows = stmt 22 .query_map([limit], |row| { 23 Ok(Session { 24 id: row.get(0)?, 25 title: row.get(1)?, 26 created_at_ms: row.get(2)?, 27 }) 28 }) 29 .map_err(map_err)?; 30 rows.collect::<Result<Vec<_>, _>>().map_err(map_err) 31 } 32 33 fn delete_session(&self, session_id: &str) -> Result<(), StoreError> { 34 self.conn 35 .execute("DELETE FROM sessions WHERE id = ?1", params![session_id]) 36 .map_err(map_err)?; // messages 靠 CASCADE 一起删 37 Ok(()) 38 } 39 40 fn append_message(&self, msg: &Message) -> Result<(), StoreError> { 41 let role = role_to_db(&msg.role); // Role → &str 42 self.conn 43 .execute( 44 "INSERT INTO messages (id, session_id, role, content, created_at_ms) 45 VALUES (?1, ?2, ?3, ?4, ?5)", 46 params![msg.id, msg.session_id, role, msg.content, msg.created_at_ms], 47 ) 48 .map_err(map_err)?; 49 Ok(()) 50 } 51 52 fn list_messages(&self, session_id: &str) -> Result<Vec<Message>, StoreError> { 53 let mut stmt = self 54 .conn 55 .prepare( 56 "SELECT id, session_id, role, content, created_at_ms 57 FROM messages WHERE session_id = ?1 ORDER BY created_at_ms ASC", 58 ) 59 .map_err(map_err)?; 60 let rows = stmt 61 .query_map([session_id], |row| { 62 let role: String = row.get(2)?; 63 Ok(Message { 64 id: row.get(0)?, 65 session_id: row.get(1)?, 66 role: role_from_db(&role), 67 content: row.get(3)?, 68 created_at_ms: row.get(4)?, 69 }) 70 }) 71 .map_err(map_err)?; 72 rows.collect::<Result<Vec<_>, _>>().map_err(map_err) 73 } 74 75 fn clear_messages(&self, session_id: &str) -> Result<(), StoreError> { 76 self.conn 77 .execute("DELETE FROM messages WHERE session_id = ?1", params![session_id]) 78 .map_err(map_err)?; 79 Ok(()) 80 } 81} 82 83/// 把 rusqlite 错误统一转成 StoreError(第 17 课的契约类型) 84fn map_err(e: rusqlite::Error) -> StoreError { 85 match e { 86 rusqlite::Error::QueryReturnedNoRows => StoreError::NotFound("记录不存在".into()), 87 other => StoreError::Io(other.to_string()), 88 } 89} 90 91fn role_to_db(role: &Role) -> &'static str { 92 match role { Role::User => "user", Role::Assistant => "assistant", Role::System => "system" } 93} 94 95fn role_from_db(s: &str) -> Role { 96 match s { "assistant" => Role::Assistant, "system" => Role::System, _ => Role::User } 97} 98
💡 读 DB 行 → Rust struct 的样板循环(
query_map+row.get)在代码里很常见。量大后可考虑serde的 rusqlite 适配(derive直接映射行),但先学会手写版,错误类型和列顺序都由你掌控。
18.5 并发与"database is locked":真实 App 必修课
18.5.1 问题从哪来
第 19 课起,UI 的多个线程/任务可能同时调 append_message(用户连发多条)、list_sessions(刷新列表)、delete_session。SQLite 默认一次只允许一个写者,写锁没释放时另一写会报 database is locked。
rusqlite 的 Connection 默认不是 Sync(含内部缓存),直接放进 Box<dyn HistoryStore> 并跨线程调用会编译不过。三种处理姿势:
| 姿势 | 做法 | 适用 |
|---|---|---|
| A. 每操作新开连接 | 线程/调用各自 Connection::open | 演示、低频 |
| B. 进程级单连接 + 外部 Mutex | Mutex<Connection> 串行化所有访问 | 简单可靠(本课采用) |
| C. 连接池 | r2d2_sqlite 之类 | 高并发、多读多写 |
本课采用 B:把 Connection 包在 Mutex 里,天然满足 Sync 且把写冲突变成"排队"(加上 18.2 已开的 WAL 模式,读不阻塞写):
1use std::sync::Mutex; 2 3pub struct SqliteStore { 4 conn: Mutex<Connection>, // 内部串行化;对外仍是 Sync 5} 6 7impl SqliteStore { 8 pub fn open(path: impl AsRef<std::path::Path>) -> Result<Self, rusqlite::Error> { 9 let conn = Connection::open(path)?; 10 conn.pragma_update(None, "journal_mode", "WAL")?; 11 conn.pragma_update(None, "foreign_keys", "ON")?; 12 let store = SqliteStore { conn: Mutex::new(conn) }; 13 store.migrate()?; 14 Ok(store) 15 } 16 17 fn lock(&self) -> Result<std::sync::MutexGuard<'_, Connection>, StoreError> { 18 self.conn.lock().map_err(|_| StoreError::Io("存储锁中毒".into())) 19 } 20} 21
然后每个方法开头 let conn = self.lock()?;,后续全部走 conn:
1impl HistoryStore for SqliteStore { 2 fn create_session(&self, session: &Session) -> Result<(), StoreError> { 3 let conn = self.lock()?; 4 conn.execute( 5 "INSERT INTO sessions (id, title, created_at_ms) VALUES (?1, ?2, ?3)", 6 params![session.id, session.title, session.created_at_ms], 7 ) 8 .map_err(map_err)?; 9 Ok(()) 10 } 11 // ……其余方法同样先 lock() 12} 13
⚠️ 同步方法里用
std::sync::Mutex没问题(不跨.await持有)。永远不要在持锁期间调用 UI/网络——锁粒度 = 一条 SQL。SQLite 单次操作毫秒级,串行化完全可接受。
18.5.2 WAL 模式是什么
1journal_mode = WAL(Write-Ahead Logging): 2 - 写操作先追加到 .wal 文件,再择机合入主库 3 - 效果:读写不互相阻塞(一个写者 + 多个读者可同时进行) 4 - App 常见标配;配合 busy_timeout 可进一步缓解极端冲突 5
1// 极端冲突兜底:等锁最长 5 秒而不是立刻报错 2conn.busy_timeout(std::time::Duration::from_secs(5))?; 3
18.6 把真 store 接回 service:17 课测试一行不改
1// core 集成测试:sqlite_smoke.rs 2use my_ai_core::llm::chat::ChatLlm; 3use my_ai_core::models::Message; 4use my_ai_core::service::AssistantService; 5use my_ai_core::store::{HistoryStore, SqliteStore}; 6 7struct FakeLlm; // 同 17.6 8 9#[tokio::test] 10async fn sqlite_roundtrip_via_service() { 11 // 临时文件库,测完自动删 12 let dir = std::env::temp_dir(); 13 let path = dir.join(format!("ai_test_{}.db", std::process::id())); 14 15 let store = SqliteStore::open(&path).unwrap(); 16 let service = AssistantService::new(Box::new(FakeLlm), Box::new(store), "系统提示".into()); 17 18 let session = service.new_session("持久化测试").await.unwrap(); 19 let mut got = String::new(); 20 service 21 .ask_stream(&session.id, "存下来了吗", Box::new(|d| got.push_str(d))) 22 .await 23 .unwrap(); 24 assert!(got.contains("你好,世界")); 25 26 // 重新打开同一个文件(模拟 App 重启):数据还在 27 let store2 = SqliteStore::open(&path).unwrap(); 28 let sessions = store2.list_sessions(10).unwrap(); 29 assert_eq!(sessions.len(), 1); 30 let msgs = store2.list_messages(&session.id).unwrap(); 31 assert_eq!(msgs.len(), 2); 32 33 std::fs::remove_file(&path).ok(); 34} 35
验收瞬间:同一段 service 测试,把 MemStore::default() 换成 SqliteStore::open(...) 就跑通——17 课设计的接口抽象兑现了。
18.7 📝 动手练习
参考实现放 code/18-sqlite/(写作时同步给出)。
- rusqlite 最小读写:
:memory:建表/插入/查询/迭代,练参数化与query_map收行。 - 防注入验证:向 18.2 的插入函数传
x'); DROP TABLE kv; --,确认它只是被当作普通字符串存进去(参数化生效)。 - 完整实现 HistoryStore for SqliteStore:按 18.4 补全全部 6 个方法,并跑通 18.6 的冒烟测试。
- 迁移实验:先建 version=1 的库,再用"version=2:给 messages 加一列 complete INTEGER DEFAULT 1"的迁移脚本升级,验证老数据不丢、新字段可写。
- 忙锁观察:开两个
SqliteStore指向同一文件,线程 A 在事务里sleep 200ms后提交,线程 B 同时写——先不设 busy_timeout 记录报错,再设 5s 观察排队成功。 - 并发冒烟:8 个 tokio 任务各 append 50 条消息到同一会话,结束后断言总数 = 400(体会 Mutex 串行化 + WAL 的效果)。
- 综合(重点):给
messages补complete列并在模型加字段,让ask_stream断流时(FakeLlm 抛StreamInterrupted)能落一条complete=false的尾巴消息——为 19 课"流中断可恢复"预演。
验收门禁:能写出带 ?1 占位 + params! 的最小读写;能说出 WAL 解决了什么、Mutex 解决了什么;能解释为什么 schema 变更必须走版本迁移而不是改旧 SQL。
✅ 本节小结
- rusqlite:
bundled特性免系统依赖;:memory:便于测试;永远参数化 SQL; - schema:sessions/messages 两张表 + 复合索引 +
ON DELETE CASCADE;PRAGMA user_version做增量迁移; - 枚举映射:DB 存 TEXT,行读取时再转回 Rust enum;
- 并发:
Mutex<Connection>串行化(天然 Sync)、WAL 读写分离、busy_timeout兜底; - 接口红利:换 store 实现,service 测试与调用方零改动;
- 纪律:持锁不做 IO、schema 只加不改、迁移逐版本前进。
下一课预告:第 19 课《UniFFI 导出核心能力》——把 17-18 课的 core 交给各端:UniFFI 生成 Swift/Kotlin/Python 绑定、async 方法导出、复杂类型(Session/Message/enum 错误)映射、以及"如何在壳与 core 之间传回调"。这是实战篇的技术主峰。
参考文档
- Primers 编程伙伴/Bash/帮助手册/let
- Primers 编程伙伴/Bash/帮助手册/sync
- Primers 编程伙伴/Python/内建函数/open
- Primers 编程伙伴/HTML/HTML 元素/code
- Primers 编程伙伴/Bash/帮助手册/sleep
- Primers 编程伙伴/Bash/帮助手册/complete
《【AI开发之Rust】第 18 课:SQLite 持久化与本地缓存 —— 给 store 填上真实现》 是转载文章,点击查看原文。
