dart-code-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dart-build-runner-automation

Dart Build Runner 自动化

Goal

目标

Configures and executes Dart's

build_runner

tool to automate code generation, testing, and serving of Dart applications. Analyzes project requirements to inject necessary development dependencies, determines the optimal build strategy (one-time build vs. continuous watching), and resolves file conflict errors during the generation phase.

配置并执行Dart的

build_runner

工具，以自动化Dart应用的代码生成、测试和服务。分析项目需求以注入必要的开发依赖，确定最优构建策略（一次性构建 vs 持续监听），并解决生成阶段的文件冲突错误。

Decision Logic

决策逻辑

When tasked with running a build or code generation process, evaluate the user's current context to select the correct command:

Is the user actively developing and modifying files? -> Choose
```
watch
```
.
Is this a CI/CD pipeline or a one-off production build? -> Choose
```
build
```
.
Is the user building a web application? -> Do NOT use
```
build_runner serve
```
; delegate to
```
webdev serve
```
(see
```
dart-web-development
```
).
Does the user need to run tests on generated code? -> Choose
```
test
```
.

当需要执行构建或代码生成流程时，评估用户当前环境以选择正确的命令：

用户是否正在积极开发并修改文件？ -> 选择
```
watch
```
命令。
这是否是CI/CD流水线或一次性生产构建？ -> 选择
```
build
```
命令。
用户是否正在构建Web应用？ -> 不要使用
```
build_runner serve
```
；转而使用
```
webdev serve
```
（参考
```
dart-web-development
```
）。
用户是否需要对生成的代码运行测试？ -> 选择
```
test
```
命令。

Instructions

操作步骤

Verify and Inject Dependencies Inspect the

pubspec.yaml

file. Ensure that

build_runner

is listed under

dev_dependencies

. If testing generated code, also ensure

build_test

is present.

yaml

dev_dependencies:
  build_runner: ^2.4.0 # Use the latest compatible version
  build_test: ^3.2.0   # Optional: Only if testing is required

Run the package fetch command:

bash

dart pub get

Determine Project Policy on Generated Files STOP AND ASK THE USER: "Should generated files (e.g.,
```
.g.dart
```
) be committed to version control, or are they generated on-the-fly in this project?"
- If generated on-the-fly: Ensure
```
.g.dart
```
  is added to the
```
.gitignore
```
  file.
- If committed: Proceed without modifying
```
.gitignore
```
  .
Execute the Build Command Based on the Decision Logic, execute the appropriate command from the project root.

For continuous background generation during development (PREFERRED):
bash
```
dart run build_runner watch
```
For a one-time build:
bash
```
dart run build_runner build
```
For running tests that require code generation:
bash
```
dart run build_runner test
```
Validate-and-Fix: Handle Conflicting Outputs Monitor the terminal output for the build command. If the build fails with a
```
ConflictingOutputsException
```
(indicating that generated files already exist and conflict with the new build), automatically recover by appending the
```
--delete-conflicting-outputs
```
flag.
bash
```
dart run build_runner build --delete-conflicting-outputs
```
Or for watch mode:
bash
```
dart run build_runner watch --delete-conflicting-outputs
```
Verify that the command succeeds after applying this flag.

验证并注入依赖 检查
```
pubspec.yaml
```
文件，确保
```
build_runner
```
已列在
```
dev_dependencies
```
下。如果需要对生成的代码进行测试，还要确保
```
build_test
```
已存在。

yaml

dev_dependencies:
  build_runner: ^2.4.0 # 使用最新兼容版本
  build_test: ^3.2.0   # 可选：仅在需要测试时添加

运行包获取命令：

bash

dart pub get

确定项目对生成文件的管理策略 务必先询问用户：“生成的文件（如
```
.g.dart
```
）是否需要提交到版本控制，还是在项目中按需生成？”

如果是按需生成： 确保
```
.g.dart
```
已添加到
```
.gitignore
```
文件中。
如果需要提交： 无需修改
```
.gitignore
```
，直接继续。

执行构建命令 根据决策逻辑，从项目根目录执行相应的命令。

开发期间推荐使用（持续后台生成）：

bash

dart run build_runner watch

一次性构建：

bash

dart run build_runner build

运行需要代码生成的测试：

bash

dart run build_runner test

验证与修复：处理输出冲突 监控构建命令的终端输出。如果构建因
```
ConflictingOutputsException
```
失败（表示生成的文件已存在并与新构建冲突），自动通过添加
```
--delete-conflicting-outputs
```
参数恢复。

bash

dart run build_runner build --delete-conflicting-outputs

对于watch模式：

bash

dart run build_runner watch --delete-conflicting-outputs

验证添加该参数后命令是否执行成功。

Constraints

约束条件

Strict Web App Routing: Never use
```
dart run build_runner serve
```
for web applications. You must use the
```
webdev
```
tool instead.
File Tracking: AVOID committing
```
.g.dart
```
files if the project policy is to generate them on-the-fly. Always clarify this policy before running git commands.
Development Preference: PREFER the
```
watch
```
command for continuous background generation during active development sessions to prevent stale code errors.
Conflict Resolution: Always use
```
--delete-conflicting-outputs
```
when regenerating files that have changed structure or when switching branches, rather than manually deleting
```
.dart_tool
```
or
```
.g.dart
```
files.
Related Skills: Defer to
```
dart-testing
```
for advanced test configurations and
```
dart-web-development
```
for web-specific serving and compilation.

Web应用严格路由： 绝不要对Web应用使用
```
dart run build_runner serve
```
，必须改用
```
webdev
```
工具。
文件追踪： 如果项目策略是按需生成
```
.g.dart
```
文件，请勿提交这些文件。在运行git命令前务必明确此策略。
开发优先选择： 在活跃开发会话期间，优先使用
```
watch
```
命令进行持续后台生成，以避免代码过期错误。
冲突解决： 当重新生成结构已更改的文件或切换分支时，始终使用
```
--delete-conflicting-outputs
```
，而非手动删除
```
.dart_tool
```
或
```
.g.dart
```
文件。
相关技能： 高级测试配置请参考
```
dart-testing
```
，Web特定的服务与编译请参考
```
dart-web-development
```
。