# 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` 快很多。