跨平台开发 / 系统课时
统一 build_runner 生成流程
统一 build_runner 生成流程
本篇解决 Flutter 项目中代码生成命令分散、生成文件更新不一致的问题。通过统一 build_runner 工作流,可以让 JSON 序列化、Riverpod 等生成代码保持稳定更新,减少团队协作中的编译差异。
学习目标
- 理解 build_runner 在 Flutter 工程中的生成流程和职责
- 掌握常用生成命令的使用方式与适用场景
- 建立可重复执行的代码生成规范
理解 build_runner 的工作方式
Flutter 中很多库不会直接手写全部代码,而是通过注解生成辅助文件。例如 JSON 序列化会根据模型类生成转换方法,Riverpod Generator 会根据声明生成 Provider 实现。
build_runner 负责扫描项目源码、执行生成器,并将结果写入生成文件。开发阶段如果生成流程不统一,就容易出现代码已经修改但生成文件没有更新的问题。
常见生成场景包括:
json_serializable根据模型生成fromJson和toJson- Riverpod 根据注解生成 Provider 代码
- Freezed 根据不可变模型定义生成实现类
选择合适的生成命令
开发过程中通常使用两类命令:一次性生成和持续监听生成。
bash
# 首次生成或修改较少时执行
flutter pub run build_runner build
# 开发阶段持续监听源码变化并自动重新生成
flutter pub run build_runner watch预期输出
text
[INFO] Generating build script completed
[INFO] Running build completed
[INFO] Succeeded after <TIME>实际输出中的耗时会根据项目规模不同而变化。
build 适合 CI 或提交前验证,watch 适合本地开发。持续监听可以减少手动执行命令的次数,但也需要注意终端进程状态。
处理生成冲突参数
当生成文件已经存在但内容与当前源码不一致时,可以使用删除后重新生成的方式恢复一致状态。
bash
flutter pub run build_runner build --delete-conflicting-outputs预期输出
text
[INFO] Deleted conflicting outputs
[INFO] Running build completed
[INFO] Succeeded after <TIME>这个参数适合生成文件被移动、分支切换后产生冲突的情况。它不会删除业务源码,只会处理生成器管理的输出文件。
在团队中固定生成流程
多人协作时,应让所有开发者使用相同的生成入口,而不是各自记忆不同命令。可以在项目文档中约定:
- 修改注解模型后执行生成
- 提交代码前确保生成文件同步
- CI 中执行一次完整生成检查
- 不直接修改生成文件
生成代码的目标不是减少代码数量,而是让重复且容易出错的实现交给工具维护。稳定的生成流程可以让依赖代码生成的 Flutter 项目保持可预测状态。
按自己的节奏,确认真正理解。