本地持久化:shared_preferences 与 drift(SQLite)
第 14 章 · 本地持久化:shared_preferences 与 drift(SQLite)
run
$cd examples/ch14-persistence && flutter run -d macos已验证
- flutter analyze 0 告警、flutter test 12 个用例全绿、flutter build macos --debug 真实构建并启动成功
- 完整工程已打包:打包下载
本章目录 · 17 节
14.1 本章目标
- 知道四种持久化手段各自该存什么:键值、关系数据、文件、密钥;
- 用
shared_preferences存小配置,并知道它不是数据库; - 用
drift(SQLite)建表、写查询、用watch()把查询变成 Stream; - 会做数据迁移(
schemaVersion+MigrationStrategy); - 会用内存数据库写测试,并在 widget 测试里正确释放数据库连接;
- 知道各平台的数据目录差异。
对照 Go:os.UserConfigDir() + JSON / database/sql + mattn/go-sqlite3;
对照 C:手写 ini + sqlite3_open_v2 / sqlite3_prepare_v2。
14.2 四种手段,别用错
| 手段 | 存什么 | 容量 | 查询 | 示例 |
|---|---|---|---|---|
shared_preferences |
键值配置(主题、上次同步时间、引导页标记) | 小(几十 KB) | 无 | 本章前半 |
| SQLite(drift) | 结构化数据(待办、消息、离线缓存、日志) | 大(GB 级) | SQL | 本章后半 |
文件(path_provider) |
图片、导出文件、日志 | 随意 | 无(自己管) | 下载缓存 |
| 安全存储 | token、密码 | 极小 | 无 | ch17 |
最常见的错误:用 shared_preferences 存列表/对象(把整个 JSON 塞进去),然后在数据变大时崩溃/卡顿。一旦你需要"查询、排序、分页、关联",就该上 SQLite。
14.3 shared_preferences:小配置的家
// examples/ch14-persistence/lib/src/settings_store.dart
class SettingsStore {
SettingsStore(this._prefs);
final SharedPreferences _prefs;
static const String _themeKey = 'theme_mode';
static const String _lastSyncKey = 'last_sync_at';
ThemeMode get themeMode => switch (_prefs.getString(_themeKey)) {
'dark' => ThemeMode.dark,
'system' => ThemeMode.system,
_ => ThemeMode.light, // 读不到/值不认识 → 默认
};
Future<void> setThemeMode(ThemeMode mode) => _prefs.setString(_themeKey, mode.name);
DateTime? get lastSyncAt => DateTime.tryParse(_prefs.getString(_lastSyncKey) ?? '');
Future<void> markSyncedAt(DateTime at) =>
_prefs.setString(_lastSyncKey, at.toUtc().toIso8601String());
}
底层就是各平台的键值存储:
| 平台 | 实际存储 |
|---|---|
| macOS / iOS | NSUserDefaults(plist) |
| Android | SharedPreferences(XML) |
| Linux | ~/.local/share/<app>/shared_preferences.json |
| Windows | 注册表 / %APPDATA% 下的文件 |
三个要点
-
必须
await初始化后再runApp(否则首帧拿不到主题,会闪一下):dart Future<void> main() async { WidgetsFlutterBinding.ensureInitialized(); final SharedPreferences prefs = await SharedPreferences.getInstance(); runApp(ProviderScope( overrides: [settingsProvider.overrideWithValue(SettingsStore(prefs))], child: ..., )); } -
它不可监听。
prefs.getString(...)改了不会通知任何 widget。示例里点"记录同步时间"后要setState(() {})才能刷新显示——想响应式就用 Riverpod 包一层。 -
只支持基础类型:
String/int/double/bool/List<String>。对象要自己jsonEncode(参考 ch12)。
测试
setUp(() => SharedPreferences.setMockInitialValues(<String, Object>{}));
final SharedPreferences prefs = await SharedPreferences.getInstance();
final SettingsStore store = SettingsStore(prefs);
await store.setThemeMode(ThemeMode.dark);
expect(prefs.getString('theme_mode'), 'dark');
setMockInitialValues 会把平台通道替换成内存实现,测试完全离线。
14.4 drift:类型安全的 SQLite
声明表
// examples/ch14-persistence/lib/src/database.dart
class Todos extends Table {
IntColumn get id => integer().autoIncrement()();
TextColumn get title => text().withLength(min: 1, max: 200)();
BoolColumn get done => boolean().withDefault(const Constant(false))();
DateTimeColumn get createdAt => dateTime().withDefault(currentDateAndTime)();
}
@DriftDatabase(tables: <Type>[Todos])
class AppDatabase extends _$AppDatabase {
AppDatabase(super.executor);
AppDatabase.memory() : super(NativeDatabase.memory()); // 测试
factory AppDatabase.open() => AppDatabase(_openConnection()); // 应用
@override
int get schemaVersion => 1;
...
}
dart run build_runner build # 生成 database.g.dart
生成器给了你:Todo 数据类(不可变、带 copyWith/==)、TodosCompanion(插入/更新用)、$TodosTable(查询用)。
查询与写入
Future<List<Todo>> allTodos() =>
(select(todos)..orderBy(<OrderClauseGenerator<$TodosTable>>[(t) => OrderingTerm.desc(t.createdAt)])).get();
Stream<List<Todo>> watchTodos() => (select(todos)..orderBy(...)).watch();
Future<int> addTodo(String title) =>
into(todos).insert(TodosCompanion.insert(title: title.trim()));
Future<void> setDone(int id, {required bool done}) =>
(update(todos)..where((t) => t.id.equals(id))).write(TodosCompanion(done: Value<bool>(done)));
Future<int> deleteTodo(int id) => (delete(todos)..where((t) => t.id.equals(id))).go();
| drift | 生成的 SQL(大致) | Go database/sql |
|---|---|---|
select(todos)..where(...) |
SELECT * FROM todos WHERE id = ? |
db.Query("SELECT ...") + Scan |
into(todos).insert(...) |
INSERT INTO todos (...) VALUES (?) |
db.Exec("INSERT ...") |
update(todos)..write(...) |
UPDATE todos SET done = ? WHERE id = ? |
db.Exec("UPDATE ...") |
.watch() |
查询 + SQLite update hook | 无内置,要自己轮询/触发器 |
.watch() 是本例最值钱的能力:任何一次写入都会让 Stream 推新结果,UI 自动刷新,不用手写"改完再通知"。
文件位置
LazyDatabase _openConnection() => LazyDatabase(() async {
final Directory dir = await getApplicationSupportDirectory();
final File file = File(p.join(dir.path, 'ch14_todos.sqlite'));
return NativeDatabase.createInBackground(file); // 后台 isolate,不阻塞 UI
});
| 平台 | getApplicationSupportDirectory() |
|---|---|
| macOS | ~/Library/Containers/<bundle id>/Data/Library/Application Support/<bundle id>/(沙箱) |
| Linux | ~/.local/share/<app>/ |
| Windows | %APPDATA%\<app>\ |
| Android | /data/data/<package>/files/ |
| iOS | .../Library/Application Support/ |
本次真实验证(注意 macOS 的沙箱路径):
$ sqlite3 "$HOME/Library/Containers/com.dartbook.ch14Persistence/Data/Library/Application Support/com.dartbook.ch14Persistence/ch14_todos.sqlite" \
".tables" "select count(*) from todos;"
todos
0
做端到端验证时,别去
~/Library/Application Support/<app>找——macOS 应用默认开启沙箱,真实路径在~/Library/Containers/<bundle id>/Data/下。
原生 SQLite 从哪来(2026 年的现状)
package:sqlite3 3.x 使用 Dart 的 build hooks(原 native assets)自动编译/打包 SQLite:
dependencies:
sqlite3: ^3.4.0 # drift 会带进来
所以:
- 不需要
sqlite3_flutter_libs(0.6.0 起它是空包,pub 上标了+eol); flutter test在宿主机上也能直接跑(hooks 会构建宿主版本);- 各平台产物由构建系统自动带进安装包。
这是过去两三年变化最大的一块,网上老教程里的 sqlite3_flutter_libs + 手工 CMake 配置已经可以忘掉了。
迁移
@override
int get schemaVersion => 2;
@override
MigrationStrategy get migration => MigrationStrategy(
onCreate: (Migrator m) => m.createAll(),
onUpgrade: (Migrator m, int from, int to) async {
if (from < 2) {
await m.addColumn(todos, todos.done); // v1 → v2 加一列
}
},
);
规则:
schemaVersion只增不减;每次改表都要 +1 并写迁移;- 迁移必须幂等且可重放(用户可能从 v1 直接升到 v5);
- 开发期用
drift_dev schema dump生成 schema 快照 +drift_dev schema steps测试迁移(本章示例只有 v1,没展开); - 生产里永远不要
deleteDatabaseAndCreate了事——用户数据会丢。
14.5 与 Riverpod 集成
// examples/ch14-persistence/lib/src/providers.dart
final databaseProvider = Provider<AppDatabase>((Ref ref) {
final AppDatabase db = AppDatabase.open();
ref.onDispose(db.close);
return db;
});
final todosProvider = StreamProvider<List<Todo>>(
(Ref ref) => ref.watch(databaseProvider).watchTodos(),
);
final doneCountProvider = Provider<int>((Ref ref) {
final List<Todo>? todos = ref.watch(todosProvider).value;
return todos?.where((Todo t) => t.done).length ?? 0;
});
UI 只读 todosProvider,写操作统一走 TodoActions:
class TodoActions {
Future<void> add(String title) async { if (title.trim().isEmpty) return; await _db.addTodo(title); }
Future<void> toggle(Todo todo) => _db.setDone(todo.id, done: !todo.done);
}
好处:UI 不碰数据库,所有写操作集中在一处,容易加审计、事务、乐观更新。
注意 Riverpod 3 的 API 变化:
AsyncValue.valueOrNull已被移除,用.value(可空)。
14.6 测试:内存数据库 + 释放连接
late AppDatabase db;
setUp(() => db = AppDatabase.memory()); // 每个用例独立、天然隔离
tearDown(() => db.close());
test('增删改查', () async {
final int id = await db.addTodo('写 ch14 示例');
expect((await db.allTodos()).single.title, '写 ch14 示例');
await db.setDone(id, done: true);
expect((await db.allTodos()).single.done, isTrue);
});
两个实测坑
-
widget 测试里"Timer 仍挂起"。
StreamProvider订阅了 drift 的查询,测试结束时 watcher 还在等数据 → 框架报:text A Timer is still pending even after the widget tree was disposed.解决:测试结尾显式卸载 widget 树,让 provider 释放订阅:
dart await tester.pumpWidget(const SizedBox.shrink()); await tester.pumpAndSettle(); -
withLength不是客户端强制校验。text().withLength(min: 1, max: 200)主要描述 schema;插入空串/超长串不会自动抛异常(除非在数据库层加 CHECK)。业务校验要写在应用层(示例的TodoActions.add拦空串)。
14.7 运行与验证
cd examples/ch14-persistence
flutter pub get
dart run build_runner build # 生成 lib/src/database.g.dart
flutter analyze # No issues found!
flutter test # All tests passed! (12 个用例)
flutter run -d macos
本次真实验证:
✓ Built build/macos/Build/Products/Debug/ch14_persistence.app
flutter: The Dart VM service is listening on http://127.0.0.1:64291/...
$ sqlite3 ".../ch14_todos.sqlite" ".tables"
todos
界面上:添加待办 → 勾选(自动写库)→ 删除;点右上角云图标记录同步时间(写 prefs);点亮度图标切主题(持久化,重启后仍生效)。
附:C/Go 代码对照:SQLite 的两种写法
/* C:prepare → bind → step → finalize,每一步都要检查返回码 */
sqlite3 *db;
sqlite3_open("todos.db", &db);
sqlite3_exec(db,
"CREATE TABLE IF NOT EXISTS todos("
"id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL)", 0, 0, 0);
sqlite3_stmt *stmt;
sqlite3_prepare_v2(db, "INSERT INTO todos(title) VALUES(?)", -1, &stmt, NULL);
sqlite3_bind_text(stmt, 1, "买咖啡豆", -1, SQLITE_TRANSIENT);
sqlite3_step(stmt);
sqlite3_finalize(stmt);
sqlite3_close(db);
// Dart / drift:声明表 → 生成查询构建器 → 类型安全地写
class Todos extends Table {
IntColumn get id => integer().autoIncrement()();
TextColumn get title => text().withLength(min: 1, max: 200)();
}
await into(todos).insert(TodosCompanion.insert(title: '买咖啡豆'));
await (delete(todos)..where((t) => t.done.equals(true))).go();
C 里"字符串所有权、finalize、close、每步错误码"全靠人;drift 把这些收进生成代码,但迁移(schemaVersion)仍然要你自己写——这是 SQLite 在所有语言里都躲不掉的债。
14.8 本章小结 + C/Go 对照清单
| 主题 | Go | C | Dart/Flutter | 陷阱 |
|---|---|---|---|---|
| 配置存储 | os.UserConfigDir + JSON |
手写 ini | shared_preferences |
别存大对象;不可监听 |
| 关系数据 | database/sql |
sqlite3_prepare_v2 |
drift |
忘了迁移脚本 |
| 类型安全 | struct + Scan |
手工强转 | 生成的数据类 + Companion | withLength 不强制 |
| 响应式查询 | 无内置 | 无内置 | .watch() → Stream |
widget 测试要卸载 |
| 数据库位置 | 自己拼路径 | 自己拼路径 | getApplicationSupportDirectory() |
macOS 沙箱路径 |
| 线程 | 连接池/goroutine | 线程 + mutex | 后台 isolate | UI 线程别做重查询 |
| 迁移 | goose / 手写 |
ALTER TABLE |
schemaVersion + MigrationStrategy |
只增不减、可重放 |
给 C/Go 老兵的三句话:
- 小配置用
shared_preferences,结构化数据用 SQLite;不要用一个去凑另一个的活。 schemaVersion和迁移是上线后才最痛的东西,从第一版就写。- 测试用内存数据库 + 显式卸载,
Timer 仍挂起这类报错几乎都源于"订阅没释放"。
下一章:平台通道(MethodChannel/EventChannel)——当你需要调 Android/iOS 的系统能力(传感器、蓝牙、通知)时,FFI 和 SQLite 都帮不上忙,得靠它。