flutter-drift

Flutter Drift

使用此技能在 Flutter 应用中添加或修复基于 Drift 的本地持久化。此技能是一套操作流程：先检查目标应用，只选择相关的参考文件，使用当前 Drift API 实现，并验证生成的代码。

核心工作流程

1. 编辑前检查应用：
   • 检查 pubspec.yaml、现有数据库文件、build.yaml、状态管理包、目标平台和测试。
   • 优先采用应用当前的架构和命名，而不是此技能中的示例。
2. 使用包管理命令添加或确认依赖项，而不是硬编码版本：
   • dart pub add drift drift_flutter path_provider dev:drift_dev dev:build_runner
   • 仅当应用已在使用 provider 或 flutter_riverpod，或用户要求集成时，才添加这些依赖。
3. 创建或更新数据库入口：
   • 在 Dart 或 .drift 文件中定义表。
   • 将表添加到 @DriftDatabase。
   • 除非项目需要自定义执行器，否则使用 package:drift_flutter/drift_flutter.dart 中的 driftDatabase 打开 Flutter 数据库。
4. 将 Drift 调用限定在数据库对象上：
   • 在组件、服务和仓库中使用 database.select(database.todoItems)、database.into(database.todoItems)、database.update(database.todoItems) 和 database.delete(database.todoItems)。
   • 仅在 GeneratedDatabase 子类或 DatabaseAccessor 类中使用裸调用 select(todoItems)，这些类中的方法和表 getter 才在作用域内。
5. 更改 Drift 声明后生成代码：
   • 运行 dart run build_runner build。
   • 将生成器错误视为阻塞问题，不要当作可选的清理项。
6. 对现有应用中的架构更改，使用 Drift 的引导式迁移工作流程：
   • 在 build.yaml 中配置 drift_dev 数据库。
   • 根据需要，在架构更改前后运行 dart run drift_dev make-migrations。
   • 递增 schemaVersion、编写生成的逐步迁移，并运行生成的迁移测试。
7. 完成前进行验证：
   • 对已编辑的 Dart 文件运行 dart format。
   • 对包运行 flutter analyze 或 dart analyze。
   • 运行针对性测试；如果更改了迁移，还要运行生成的迁移测试。

资源路由

• 添加 Drift、打开数据库、配置 Web 支持或跨 isolate 共享数据库时，阅读 references/setup.md。
• 定义表、列、默认值、键、索引、约束、生成列或严格表时，阅读 references/tables.md。
• 实现查询、筛选、排序、分页、联接、聚合、子查询、自定义列或并集时，阅读 references/queries.md。
• 实现插入、更新、删除、upsert、companion、事务或批量操作时，阅读 references/writes.md。
• 实现响应式 Drift 流、StreamBuilder、StreamProvider、自定义查询流、表更新监听器或手动流失效时，阅读 references/streams.md。
• 涉及 schemaVersion、现有用户数据、build.yaml、make-migrations、生成的架构文件或迁移测试时，阅读 references/migrations.md。
• 使用 Provider、Riverpod、StreamBuilder、搜索、筛选、分页，或面向用户的加载和错误状态，将 Drift 数据接入 Flutter 组件时，阅读 references/flutter-ui.md。

必需的 API 规则

• 不要在 widget 中将 select(database.table) 作为顶层函数调用。在数据库类外部使用 database.select(database.table)。
• 不要使用 watch(...)、todoUpdates(...) 或 notifyTableUpdates(...)。请使用 customSelect(...).watch()、tableUpdates(...) 和 notifyUpdates(...)。
• 不要调用 delete(table).go(id)。添加 where 子句后再调用 go()，或者使用项目中已有的生成式表扩展辅助方法。
• 不要使用 batch.updateAll(...)，也不要将原始 ID 传给 batch.delete(...)。请使用 batch.update(..., where: ...)、传入可插入行的 batch.delete(...)，或 batch.deleteWhere(...)。
• 不要混用 Provider 和 Riverpod API。Provider.of<AppDatabase>(context) 属于 provider；Provider<AppDatabase>((ref) { ... }) 和 AsyncValue.when(...) 属于 Riverpod。
• 没有针对现有数据库的迁移计划时，不要提高 schemaVersion。
• 当 UI 流必须更新时，不要依赖原始 SQLite 写入。请使用 Drift 写入 API，或通过显式的 TableUpdate 元数据调用 notifyUpdates。

后备方案

• 如果软件包下载受阻，请更新源文件，并为用户留下准确的 dart pub add 或 flutter pub add 命令，然后说明依赖解析未经验证。
• 如果项目无法运行 build_runner，不要手动编写生成的 *.g.dart 文件。请修复源声明并报告生成器受阻的情况。
• 如果迁移状态不明确，请在更改 schemaVersion 前停止；询问当前已发布的架构历史或数据库文件。
• 如果需要支持 Web，但缺少 sqlite3.wasm 和 drift_worker.js，请添加相应代码路径，并明确报告所需的 Web 资源。

验证清单

• pubspec.yaml 包含 Drift 运行时和生成器依赖项。
• 数据库文件包含有效的 part 指令、表声明、@DriftDatabase、构造函数和 schemaVersion。
• 所有查询和写入示例都限定在正确的数据库／访问器上下文中。
• 已使用 build_runner 重新生成代码。
• Flutter UI 示例能够处理加载、空、错误和数据状态，且不会将 AsyncValue 当作 List。
• 只有在包含生成的架构快照、逐步迁移代码和测试时，才更改迁移。
• 对已编辑的软件包运行 flutter analyze 或 dart analyze 并通过；若仍有分析器错误，则报告阻碍原因。