Flutter Hive 数据库封装

存储策略

模型 → toJson() → Box

• - 无需 TypeAdapter，无 ~200 个类型上限
• 无需 build_runner，依赖精简
• HiveService 懒加载 Box，新增模型无需修改 Service

目录结构

lib/
├── services/
│ ├── hive_service.dart # 模式1：数据服务
│ └── hive_repository.dart # 模式1：基类
└── /
└── database/
├── _repository.dart # 模式2：数据库操作
└── models/
└── _model.dart # 模式3：数据模型

三种触发模式

模式1：创建数据服务

触发词：「创建数据服务」「初始化 Hive」「配置 Hive」

执行命令：
bash
python ~/.cursor/skills/flutter-hive-database/scripts/generate.py \
--mode service \
--project <项目根目录绝对路径>

生成文件：

• - lib/service/hiveservice.dart — 懒加载 Box 管理
• lib/service/hiverepository.dart — 通用 CRUD 基类

完成后在 main.dart 添加：
dart
import package:/service/hive_service.dart;

void main() async {
WidgetsFlutterBinding.ensureInitialized();
await HiveService.init();
runApp(const MyApp());
}

模式2：创建 xxx 数据库操作

触发词：「创建xxx数据库操作」「创建xxx的 Repository」

执行前询问用户：

请问功能模块的路径是什么？（如 features/user 或 user）

Repository 的名称是什么？（PascalCase，如 User）

执行命令：
bash
python ~/.cursor/skills/flutter-hive-database/scripts/generate.py \
--mode repository \
--project <项目根目录绝对路径> \
--feature \
--name

示例：
bash
python generate.py --mode repository \
--project /Users/me/myapp \
--feature features/user \
--name User

生成文件：

• - lib/features/user/database/user_repository.dart — 含原始 Map CRUD，等待模型注入

模式3：创建数据模型（并注入 CRUD）

触发词：「创建xxx数据模型」「提供 JSON 创建数据库模板」

执行前询问用户：

请提供实体的 JSON 数据或字段定义

entity 参数格式：
json
{
name: User,
fields: [
{name: id, type: int, nullable: false},
{name: name, type: String, nullable: false},
{name: age, type: int, nullable: true},
{name: createdAt, type: DateTime, nullable: false}
]
}

支持的 type：int、double、String、bool、DateTime、List、Map

执行命令：
bash
python ~/.cursor/skills/flutter-hive-database/scripts/generate.py \
--mode model \
--project <项目根目录绝对路径> \
--feature \
--entity

示例：
bash
python generate.py --mode model \
--project /Users/me/myapp \
--feature features/user \
--entity {name:User,fields:[{name:id,type:int,nullable:false},{name:name,type:String,nullable:false}]}

生成 / 更新文件：

• - lib/features/user/database/models/usermodel.dart — 模型（含 toJson/fromJson/copyWith）
• lib/features/user/database/userrepository.dart — 自动注入 save/findById/getAll/update/deleteById 方法

如果 Repository 不存在，脚本会自动创建后再注入

依赖配置

bash
flutter pub add hivece hivece_flutter

无需 hivecegenerator，无需 build_runner

验证清单

• - [ ] HiveService.init() 在 runApp() 之前调用
• [ ] UI 层只通过 Repository 操作数据，不直接调用 HiveService
• [ ] fromJson 中可选字段使用 as Type? 保证旧数据兼容

参考文件

• - 完整生成逻辑参见 scripts/generate.py