dart-code-generation

使用 Build Runner 生成 Dart 代码

目录

• 设置和配置
• 核心命令
• 版本控制策略
• 工作流：持续开发
• 工作流：解决构建冲突
• 示例

设置和配置

配置 build_runner，为使用 Dart 构建系统的软件包处理代码生成（例如，json_serializable、built_value_generator）。

将所需的软件包添加到 pubspec.yaml 的 dev_dependencies 中。只有在编写依赖生成代码的测试时，才需要包含 build_test。

注意：有关 Web 专项开发和服务的内容，请参阅 dart-web-development 技能，并使用 webdev 工具，而不是 build_runner serve。 注意：有关测试策略，请参阅 dart-testing 技能。

核心命令

通过 Dart CLI 执行 build_runner 命令。根据以下条件选择合适的命令：

• 如果在本地开发：使用 watch 启动持久运行的构建服务，监视输入文件并自动执行增量重建。这是活跃开发期间的首选方法。
• **如果在 CI/CD 流水线中运行或执行最终发布构建：**使用 build 执行严格的一次性构建。
• **如果执行需要生成代码的测试：**使用 test 编译生成的资源并运行测试套件。
• **如果构建 Web 应用：**使用 webdev serve 负责服务，而不是使用 build_runner serve。

版本控制策略

根据项目对生成文件（通常是 .g.dart、.freezed.dart 或 .part.dart）的仓库策略应用相应逻辑：

• **如果项目策略要求按需生成：**不要提交生成文件。将 *.g.dart（以及其他生成文件扩展名）添加到 .gitignore 文件中。
• **如果项目策略要求缓存生成的代码：**提交生成文件，并确保 CI 流水线验证生成文件与其源输入保持同步。

工作流：持续开发

在需要代码生成的常规功能开发中使用此工作流。

任务进度

• 运行 dart pub get，确保所有构建器依赖均已解析。
• 在专用终端进程中执行 dart run build_runner watch。
• 修改源文件（例如，添加 @JsonSerializable() 注解）。
• 确认监视器检测到更改并成功输出生成文件。
• 检查监视器输出中的错误 -> 修复源注解 -> 确认监视器成功重新构建。

工作流：解决构建冲突

当 build_runner 因已有生成文件或先前构建运行产生的输出冲突而失败时，使用此工作流。

任务进度

• 在构建输出中查找 ConflictingOutputsException 或类似错误。
• 终止所有正在运行的 watch 进程。
• 使用冲突解决标志执行构建命令：dart run build_runner build --delete-conflicting-outputs。
• 确认构建成功完成。
• 重启 watch 进程以继续开发。

示例

依赖项设置

# pubspec.yaml
dev_dependencies:
  build_runner: ^2.4.0
  build_test: ^3.2.0 # Optional: Include if testing generated code
  json_serializable: ^8.0.0 # Example builder

执行命令

开始持续生成（开发时首选）：

dart run build_runner watch

删除冲突输出以强制执行干净构建：

dart run build_runner build --delete-conflicting-outputs

运行使用生成代码的测试：

dart run build_runner test