跳到正文
CH 14综合与交付Flutter8 分钟阅读

本地持久化:shared_preferences 与 drift(SQLite)

第 14 章 · 本地持久化:shared_preferences 与 drift(SQLite)

本章示例examples/ch14-persistence在线阅读源码下载 zip

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:小配置的家

dartlib/src/settings_store.dart源文件
// 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% 下的文件

三个要点

  1. 必须 await 初始化后再 runApp(否则首帧拿不到主题,会闪一下):

    dart
    Future<void> main() async {
      WidgetsFlutterBinding.ensureInitialized();
      final SharedPreferences prefs = await SharedPreferences.getInstance();
      runApp(ProviderScope(
        overrides: [settingsProvider.overrideWithValue(SettingsStore(prefs))],
        child: ...,
      ));
    }
    
  2. 它不可监听。prefs.getString(...) 改了不会通知任何 widget。示例里点"记录同步时间"后要 setState(() {}) 才能刷新显示——想响应式就用 Riverpod 包一层。

  3. 只支持基础类型:String / int / double / bool / List<String>。对象要自己 jsonEncode(参考 ch12)。

测试

dart
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

声明表

dartlib/src/database.dart源文件
// 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;
  ...
}
bash
dart run build_runner build   # 生成 database.g.dart

生成器给了你:Todo 数据类(不可变、带 copyWith/==)、TodosCompanion(插入/更新用)、$TodosTable(查询用)。

查询与写入

dart
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 自动刷新,不用手写"改完再通知"。

文件位置

dart
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 的沙箱路径):

bash
$ 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:

yaml
dependencies:
  sqlite3: ^3.4.0    # drift 会带进来

所以:

  • 不需要 sqlite3_flutter_libs(0.6.0 起它是空包,pub 上标了 +eol);
  • flutter test 在宿主机上也能直接跑(hooks 会构建宿主版本);
  • 各平台产物由构建系统自动带进安装包。

这是过去两三年变化最大的一块,网上老教程里的 sqlite3_flutter_libs + 手工 CMake 配置已经可以忘掉了。

迁移

dart
@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 加一列
        }
      },
    );

规则:

  1. schemaVersion 只增不减;每次改表都要 +1 并写迁移;
  2. 迁移必须幂等且可重放(用户可能从 v1 直接升到 v5);
  3. 开发期用 drift_dev schema dump 生成 schema 快照 + drift_dev schema steps 测试迁移(本章示例只有 v1,没展开);
  4. 生产里永远不要 deleteDatabaseAndCreate 了事——用户数据会丢。

14.5 与 Riverpod 集成

dartlib/src/providers.dart源文件
// 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:

dart
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 测试:内存数据库 + 释放连接

dart
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);
});

两个实测坑

  1. 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();
    
  2. withLength 不是客户端强制校验。text().withLength(min: 1, max: 200) 主要描述 schema;插入空串/超长串不会自动抛异常(除非在数据库层加 CHECK)。业务校验要写在应用层(示例的 TodoActions.add 拦空串)。

14.7 运行与验证

bash
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

本次真实验证:

text
✓ 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
/* 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
// 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 老兵的三句话:

  1. 小配置用 shared_preferences,结构化数据用 SQLite;不要用一个去凑另一个的活。
  2. schemaVersion 和迁移是上线后才最痛的东西,从第一版就写。
  3. 测试用内存数据库 + 显式卸载,Timer 仍挂起 这类报错几乎都源于"订阅没释放"。

下一章:平台通道(MethodChannel/EventChannel)——当你需要调 Android/iOS 的系统能力(传感器、蓝牙、通知)时,FFI 和 SQLite 都帮不上忙,得靠它。