dart-code-generation

Build Runner による Dart コードの生成

目次

• セットアップと設定
• 基本的なコマンド
• バージョン管理ポリシー
• ワークフロー：継続的な開発
• ワークフロー：ビルドの競合の解決
• 例

セットアップと設定

Dart のビルドシステムを使用するパッケージ（例：json_serializable、built_value_generator）のコード生成を処理するように、build_runner を設定します。

必要なパッケージを pubspec.yaml の dev_dependencies に追加します。生成されたコードに依存するテストを作成する場合にのみ、build_test を含めてください。

注：Web 固有の開発とサービングについては、dart-web-development スキルを参照し、build_runner serve の代わりに webdev ツールを使用してください。 注：テスト戦略については、dart-testing スキルを参照してください。

基本的なコマンド

Dart CLI から build_runner コマンドを実行します。次の条件に基づいて、適切なコマンドを選択してください。

• ローカルで開発している場合： watch を使用して、入力ファイルを監視し、差分ビルドを自動的に実行する常駐ビルドサーバーを起動します。開発作業中は、この方法を推奨します。
• CI/CD パイプラインを実行する場合、または最終リリースビルドを行う場合： build を使用して、厳密なビルドを一度だけ実行します。
• 生成されたコードを必要とするテストを実行する場合： test を使用して、生成されたアセットをコンパイルし、テストスイートを実行します。
• Web アプリケーションをビルドする場合： build_runner serve を使用するのではなく、サービングを webdev serve に任せます。

バージョン管理ポリシー

生成ファイル（通常は .g.dart、.freezed.dart、または .part.dart）に関するプロジェクトのリポジトリポリシーに基づいて、条件に応じて対応します。

• プロジェクトのポリシーでオンザフライ生成が必要な場合： 生成ファイルをコミットしないでください。.gitignore ファイルに *.g.dart（およびその他の生成ファイルの拡張子）を追加します。
• プロジェクトのポリシーで生成コードのキャッシュが必要な場合： 生成ファイルをコミットし、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