【AI开发之Rust】第 18 课:SQLite 持久化与本地缓存 —— 给 store 填上真实现

作者:悟空聊AI日期:2026/10/5

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. 进程级单连接 + 外部 MutexMutex<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/(写作时同步给出)。

  1. rusqlite 最小读写::memory: 建表/插入/查询/迭代,练参数化与 query_map 收行。
  2. 防注入验证:向 18.2 的插入函数传 x'); DROP TABLE kv; --,确认它只是被当作普通字符串存进去(参数化生效)。
  3. 完整实现 HistoryStore for SqliteStore:按 18.4 补全全部 6 个方法,并跑通 18.6 的冒烟测试。
  4. 迁移实验:先建 version=1 的库,再用"version=2:给 messages 加一列 complete INTEGER DEFAULT 1"的迁移脚本升级,验证老数据不丢、新字段可写。
  5. 忙锁观察:开两个 SqliteStore 指向同一文件,线程 A 在事务里 sleep 200ms 后提交,线程 B 同时写——先不设 busy_timeout 记录报错,再设 5s 观察排队成功。
  6. 并发冒烟:8 个 tokio 任务各 append 50 条消息到同一会话,结束后断言总数 = 400(体会 Mutex 串行化 + WAL 的效果)。
  7. 综合(重点):给 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 之间传回调"。这是实战篇的技术主峰。


参考文档


《【AI开发之Rust】第 18 课:SQLite 持久化与本地缓存 —— 给 store 填上真实现》 是转载文章,点击查看原文。


相关推荐


风险审计岗位数据分析能力要求:Excel、SQL、Power BI怎么准备
cspttty2026/9/29

一、风险审计岗位的核心加分项,不是会背准则,而是能发现业务风险 (一)前程无忧2026校园招聘白皮书显示,专业服务类岗位看重专业知识、问题解决能力、沟通能力、独立思考能力和执行力。 风险审计岗位不是单纯查账,而是围绕采购、销售、费用、合同、权限、库存、资金等流程,判断哪里可能失控、违规或低效。对2027届学生来说,简历上最有说服力的不是写熟悉审计,而是能写清楚自己做过什么风险识别动作。 1. 具体日常工作任务可以这样理解 月初从ERP或财务系统导出上月费用报销明细,用Excel透视表


GitLab+Jenkins CI-CD自动化部署实战
蓝胖的四次元口袋2026/9/21

作者:没有四次元口袋的蓝胖 日期:2026-09-15 标签:CI/CD, GitLab, Jenkins, DevOps 写在前面 这是一篇 CI/CD 自动化部署实战记录。从 GitLab 代码托管、分支规范制定,到 Jenkins 自动化构建部署,完整记录了团队从零搭建 CI/CD 流水线的全过程。 一、项目背景 团队之前的部署流程:每次代码提交后,需要 手动登录服务器 → mvn clean package → 上传 jar/war 包 → 重启 Tomcat,流程繁琐且容易出错。


uni-app 安卓自有证书完全指南
90后晨仔2026/9/13

本文参考 DCloud 官方文档《Android平台签名证书(.keystore)生成指南》(ask.dcloud.net.cn/article/357… Oracle 官方 keytool 文档与 Android 签名机制原理整理而成。 一、核心前提:Android 只需要一套自有证书 在 Android 平台,签名的规则非常明确:同一个包名(Package Name)的应用,必须使用同一个证书签名,才能覆盖安装和更新。如果包名相同但签名不同,Android 系统会在安装时报错,用户必须先卸


ArcGIS JS 基础教程(30):体元系列 - VoxelSlice 体元切片
非科班Java出身GISer2026/9/5

ArcGIS JS 基础教程(30):体元系列 - VoxelSlice 体元切片 零、写在前面一、功能介绍二、功能实现2.1 创建并添加切片2.2 切片的三个核心属性2.3 管理集合(增删改) 三、功能应用四、核心代码五、在线示例六、关键 API 说明七、系列导航 零、写在前面 📌 本系列教程完整目录:ArcGIS JS 系列基础教程(100个项目常用热门功能) 💡 在线示例:完整可运行的 HTML 示例,无需任何环境配置,可直接在浏览器中打开体验 🗂️ 专


0823Keepalived + LVS(DR) + MariaDB主主 小白完整实战教程
Void 出逃2026/8/28

文章目录 Keepalived + LVS(DR) + MariaDB主主 小白完整实战教程一、业务背景与架构选型数据库业务四大刚性需求传统架构痛点本套方案组件分工项目预期收益 二、MariaDB主从/主主复制原理核心日志与线程完整同步流程 三、实验环境规划四、基础环境初始化(所有机器)1. 修改主机名、网卡IP2. router路由器开启IP转发 五、部署MariaDB,配置主主双向复制db1配置db2配置第一步:db2作为从库,同步db1(db1→db2)第二步:db1作


【系列:TDengine 工业物联网实战:从零搭起可运行系统 · 第 7 篇】
jufeng13072026/8/20

第 4 篇我们搭好了写入管线,背压、攒批、并发 worker 都就位了。可管线再高效,也得有数据往里喂。今天回到源头:数据从哪来?两条路——模拟器直接造,采集器从三源收,最终都汇入同一条 pipeline。这篇就讲四件事:物理模型、确定性 seed、归一化漏斗、坏数据去向。读完你能回答:模拟器的物理模型为什么这么设计?三源各适合什么场景?坏数据去哪了? 两条路径,一个入口 先看全局。整个系统的数据入口分成两条路,但最终汇聚到同一个 WritePipeline——就是第 4 篇讲背压、攒批、并发


uni-app 生命周期深度解析(iOS / Android / 鸿蒙 / Vue3 四端对照)
90后晨仔2026/8/7

📌 本文定位: 面向同时具备 iOS、Android、鸿蒙原生开发经验,正在转向 uni-app 的资深工程师。所有技术点均基于 uni-app 官方文档 及 Vue3 官方文档整理。 一、先搞懂一个 JS 语法问题:为什么说"与 data/methods 平级的叫生命周期"? 很多原生工程师初学 uni-app 时会对这句话感到困惑。我们从 JavaScript 语言层面彻底讲清楚。 1.1 Options API 的本质是一个"配置对象" 在 Vue2/Vue3 的 Options A


GPT 5.6 的真正变革:从"最强模型"到"最合适模型",AI 工程范式正在重置
浮生望2026/7/29

摘要: GPT 5.6以Sol、Terra、Luna三层架构重新定义AI使用方式。跑分不再决定竞争力,真正的差距在于把什么任务分给什么模型,用更少Token和更少返工完成更高质量交付。AI正从顾问变成协作者。 每次新模型发布,人们都在问同一个问题,但那个问题已经过时了 GPT 5.6 发布后,讨论一如既往地集中在几个老问题上:跑分涨了多少?代码能力有没有超过 Claude?谁又成了"最强模型"? 这些问题很重要,但如果你只盯着它们,就错过了 GPT 5.6 真正改变游戏规则的地方。 Open


影像创作领域的GitHub!深度体验了这个国产AI,我卸了3个AI视频工具!
程序员X小鹿2026/7/21

大家好,我是X小鹿,今天分享一个不一样的 AI 视频工具。 以前做一条 AI 短片,从剧本创作、脚本编写、到角色定妆、场景道具生成、再到分镜生成、视频生成,以及最后的剪辑成片,每一步都需要用到单独的工具。 生成一条短片,需要在多个工具间来回切换。 后来也陆续出现了一些 AI 视频工具,把上面的很多流程都集成在了一个平台上,用起来确实比之前方便了不少。 最近用了 AI 视频创作平台 updream ,发现它虽然也是将很多功能集成在了一起,但和之前接触的一些 AI 视频工具又不太一样。 体验下来,


图像的分辨率
元來2026/7/12

一、什么是分辨率 图像分辨率表示: 图像能够表示多少空间细节,或者图像在水平和垂直方向上包含多少个像素。 日常最常见的分辨率写法是: 宽度 × 高度 例如: 1920 × 1080 4096 × 4096 6144 × 6144 其中: 1920表示图像水平方向有1920个像素;1080表示图像垂直方向有1080个像素。 因此一张1920 × 1080的图像,像素总数为:1920×1080=2,073,600 即大约207万个像素,也可以称为约200万像素图像。 二、

首页编辑器站点地图

本站内容在 CC BY-SA 4.0 协议下发布

Copyright © 2026 聚合阅读