72 lines
2.7 KiB
Markdown
72 lines
2.7 KiB
Markdown
# build_runner 代码生成指南
|
||
|
||
## 一、是什么
|
||
|
||
`build_runner` 是 Dart 官方的**代码生成调度器**。它本身不生成任何代码，而是统一调度各个**生成器插件**，根据模型上的注解自动生成 `.g.dart` 文件。
|
||
|
||
类比：`build_runner` = 工厂流水线调度员，各个生成器插件 = 流水线上的工人。
|
||
|
||
## 二、当前项目的生成器
|
||
|
||
| 生成器插件 | 注解 | 生成内容 | 状态 |
|
||
|---|---|---|---|
|
||
| `isar_community_generator` | `@collection` | Isar 数据库 Schema（增删改查） | ✅ 已配置 |
|
||
| `json_serializable` | `@JsonSerializable()` | `fromJson` / `toJson` 方法 | 🔲 待添加 |
|
||
|
||
一次 `build_runner build` 会**同时调度所有已配置的生成器**，全部 `.g.dart` 一次性生成。
|
||
|
||
## 三、涉及的模型文件
|
||
|
||
### Isar 模型（`@collection`）
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `lib/core/storage/models/question.dart` | 题目 |
|
||
| `lib/core/storage/models/wrong_question.dart` | 错题 |
|
||
| `lib/core/storage/models/answer_record.dart` | 答题记录 |
|
||
| `lib/core/storage/models/play_record.dart` | 播放记录 |
|
||
| `lib/core/version/app_version_entity.dart` | 版本信息实体 |
|
||
|
||
### json_serializable 模型（`@JsonSerializable`）
|
||
|
||
> 待引入后，纯接口 DTO 模型（如 `UserPointRecord`、`OssStsConfig` 等）将使用注解自动生成序列化代码，替代手写 `fromJson`。
|
||
|
||
## 四、使用命令
|
||
|
||
```bash
|
||
# 生成一次（推荐日常使用）
|
||
dart run build_runner build
|
||
|
||
# 清理旧产物后重新生成（遇到生成代码冲突时使用）
|
||
dart run build_runner build --delete-conflicting-outputs
|
||
|
||
# 监听模式：每次保存文件自动生成（开发阶段推荐）
|
||
dart run build_runner watch
|
||
```
|
||
|
||
## 五、什么时候需要跑
|
||
|
||
| 操作 | 是否需要跑 |
|
||
|---|---|
|
||
| Isar 模型加了/删了/改了字段 | ✅ 必须，否则编译报错 |
|
||
| `@JsonSerializable` 模型改了字段 | ✅ 必须，否则序列化字段对不上 |
|
||
| 只改了页面 UI / 业务逻辑 | ❌ 不需要 |
|
||
| 只改了 `pubspec.yaml` 依赖 | ❌ 不需要（跑 `flutter pub get` 即可） |
|
||
|
||
## 六、生成产物说明
|
||
|
||
- 生成文件命名：`xxx.g.dart`，和模型文件同目录
|
||
- 生成文件**必须提交到 Git**（`.gitignore` 里不要排除 `*.g.dart`）
|
||
- **不要手动编辑** `.g.dart` 文件，改了也会被下次生成覆盖
|
||
|
||
## 七、常见问题
|
||
|
||
### Q: 编译报错 `MissingStubError` 或 `is not a subtype of`
|
||
A: 模型字段改了但没跑 build_runner，重新生成即可。
|
||
|
||
### Q: 报 `AlreadyExistsException` 或 conflicting outputs
|
||
A: 加 `--delete-conflicting-outputs` 参数清理后重新生成。
|
||
|
||
### Q: 生成很慢怎么办
|
||
A: 开发阶段用 `watch` 模式，增量生成比每次全量 `build` 快很多。
|