
# 生成の仕組み

`dart run build_runner build` は `build_runner` を起動し、`build_runner` はパッケージが依存するすべてのパッケージのビルダーを実行します。`spring_core_dart_generator` は九つのビルダーを登録します。このページでは、メインのビルダー `spring_core_dart` を、ソースファイルから整形された `.spring.dart` ファイルまで追い、他のビルダーがその周りにどう収まるかを説明します。

## ビルド時に行う理由

Spring はアプリケーションの起動時にリフレクションでアノテーションを読みます。Dart には Flutter、AOT 実行ファイル、Web でリフレクションがないため、ジェネレーターは同じ作業をビルド中に Dart のアナライザーで行います。

- アナライザーはすべての宣言を、解決済みの型とアノテーションの定数値とともに見ます。これは Spring がリフレクションで読むもののすべてです。
- 結果は普通の Dart (コンストラクター呼び出し、クロージャー、定数) なので、コンパイラーは自分のコードと同じようにチェックし、ツリーシェイキングし、ミニファイできます。
- Spring が起動時に見つける間違い (置き場所の誤ったアノテーション、解析できないポイントカット、生成コードが名前を書けない型) は、ソースを指すビルドエラーになります。

## 構成要素

```text
dart run build_runner build
        │
        ▼
build_runner ── reads build.yaml of spring_core_dart_generator
        │       auto_apply: dependents  → runs in every package that depends on it
        │       build_to: source        → writes next to your code, not into .dart_tool/
        ▼
┌──────────────────────────────── per package ────────────────────────────────┐
│ spring_properties (off by default)                                          │
│        │ runs_before                                                        │
│        ▼                                                                    │
│ spring_core_dart   ── one step per .dart file of lib/ bin/ test/ example/   │
│ spring_test        ── one step per test/*_test.dart                         │
│ spring_flutter_keys, spring_flutter_web, spring_flutter_deep_links          │
│ spring_metadata ─────────────┐ runs_before                                  │
│ spring_flutter_page_loader ──┤                                              │
│                              ▼                                              │
│ spring_flutter_seo                                                          │
└─────────────────────────────────────────────────────────────────────────────┘
```

ジェネレーターの `build.yaml` の各ビルダーエントリーには次の設定があります。

| 設定 | 値 | 効果 |
|---|---|---|
| `auto_apply` | `dependents` (`none` である `spring_properties` を除くすべて) | `spring_core_dart_generator` を依存関係に持つすべてのパッケージでビルダーが動きます。`build.yaml` を書く必要はありません。 |
| `build_to` | `source` | 出力はパッケージの中、ソースの隣に書き出されるので、読み、コミットし、公開できます。 |
| `build_extensions` | ビルダーごと | ビルダーがどの入力を見て、どのファイルを書き出せるか ([パスの対応](None#ファイルの置き場所) を参照)。 |
| `runs_before` | 三つのビルダーに | ジェネレーターが求める唯一の順序 ([順序](None#ビルダーの順序) を参照)。 |

## ビルダーの順序

`build_runner` はビルダーをフェーズごとに実行します。パッケージに適用される各ビルダーが一つのフェーズです。ステップは前のフェーズが書き出したファイルを読めますが、同じフェーズの他のステップが書き出すものは読めません。ジェネレーターは `runs_before` で三つの制約を宣言します。

| ビルダー | 先に動く対象 | 理由 |
|---|---|---|
| `spring_properties` | `spring_core_dart` | 手書きのスターターは、自身の `lib/` から、その `@ConfigurationProperties` クラス向けに生成されたモジュールをインポートし、そのサンプルはその `lib/` をインポートします。サンプルのステップ (メインのビルダー) は同じフェーズで書き出されたファイルを読めないため、`lib/` の部分は一つ前のフェーズで生成されます。 |
| `spring_metadata` | `spring_flutter_seo` | サイトのページは `spring_metadata.json` に列挙されたルートから作られます。 |
| `spring_flutter_page_loader` | `spring_flutter_seo` | サイトの各ページは、ページローダーがすでに入った `web/index.html` のコピーです。 |

他のビルダーの順序は `build_runner` に任されます。それに依存するものはありませんが、例外が一つあり、順序なしで処理されています。Flutter アプリの型付きキー (`theme.spring.keys.dart`、`messages.spring.keys.dart`) はメインのビルダーの出力の `part` ファイルで、`spring_flutter_keys` が自身のフェーズで書き出します。メインのビルダーはそれらのファイルが存在するかを確認できないため、キーのビルダーと同じ計算で `part` 行を決めます。このため、メインのビルダーが動いている間は `spring_flutter_keys` を無効にしてはいけません ([ビルダー](builders.md) を参照)。

## ファイルの置き場所

メインのビルダーは、四つのソースルートの `.dart` ファイルごとに一つのファイルを書き出せます。ファイルはルートの最上位にある `spring_gen/` フォルダーに置かれ、残りのパスはそのまま写され、`.dart` は `.spring.dart` に置き換えられます。

| 自分のファイル | 生成ファイル |
|---|---|
| `lib/main.dart` | `lib/spring_gen/main.spring.dart` |
| `lib/src/a.dart` | `lib/spring_gen/src/a.spring.dart` |
| `lib/src/shop/cart.dart` | `lib/spring_gen/src/shop/cart.spring.dart` |
| `bin/main.dart` | `bin/spring_gen/main.spring.dart` |
| `test/app/app.dart` | `test/spring_gen/app/app.spring.dart` |
| `example/main.dart` | `example/spring_gen/main.spring.dart` |
| `example/shop/bin/main.dart` | `example/spring_gen/shop/bin/main.spring.dart` |
| `test/shop_test.dart` (テストのビルダー) | `test/spring_gen/shop.test.spring.dart` |

`.spring.dart` ファイルのほかに、ビルダーは生成コードの種類ごとに一つのファイルを、モジュールにその種類のコードがあるときだけ書き出します。`lib/src/a.dart` からは、`lib/spring_gen/src/` に次のファイルができます。

| ファイル | 内容 |
|---|---|
| `a.spring.dart` | Bean 定義と配線 |
| `a.spring.introspection.dart` | モジュールが使うクラスの記述 (`$<module>Introspections`) を持つライブラリと、[オブジェクトのメソッド](../spring-core-dart/beans/object-methods.md) の `copyWith` |
| `a.spring.properties.dart` | `@ConfigurationProperties` クラスのバインディングを持つライブラリ。バインダーだけが使う記述です |
| `a.spring.proxies.dart` | モジュールのライブラリの part: AOP プロキシクラスと遅延解決プロキシ |
| `a.spring.debug.dart` | `@SpringBootApplication` だけに。そのライブラリの part で、フィンガープリントとリロードの関数。デバッグとプロファイルのビルドだけが使います |

名前は一つの規則 `<name>.spring.<kind>.dart` に従います。`theme.spring.keys.dart` や `json_schemas.spring.classes.dart` と同じです。

`.spring.dart` ファイルは二つのライブラリをインポートし、それらのリストをモジュールに渡します。自分のファイルに、それらのためのインポート、エクスポート、`part` 行が必要になることはありません。ただし `copyWith` を呼ぶ場所は別です。

他のディレクトリ (`tool/`、`web/` など) のファイルには生成ファイルができず、すでに `.spring.dart` で終わるファイルが入力になることはありません。

生成ファイルをルートごとに一つのフォルダーにまとめると邪魔にならず、アナライザーやコードレビューから一行で除外できます。隣のファイルからは相対パスで、`lib/` からは `package:` URI でインポートします。

```dart
// bin/main.dart
import 'spring_gen/main.spring.dart';

// lib/src/beans.dart
import 'package:my_app/spring_gen/src/beans.spring.dart';
```

## メインのビルダーの一つのステップ

`build_runner` は、`lib/`、`bin/`、`test/`、`example/` の `.dart` ファイルごとにメインのビルダーを一度呼びます。ほとんどの呼び出しはすぐに終わります。

### 1. 軽いテキストチェック

ビルダーはファイルをテキストとして読みます。`ComponentScan` も `SpringBootApplication` も含まなければ、ステップは終わります。ファイルは解決されず、出力も書き出されません。これにより、大きなパッケージでもビルドが速く保たれます。

### 2. ライブラリの解決

そうでなければ、ファイルはアナライザーで解決され、その要素モデルが得られます。ライブラリのクラス、関数、トップレベル変数と、解決済みの型とアノテーションの値です。

- トップレベル変数以外 (クラス、関数、フィールドなど) に付いた `@ComponentScan` は、正しい形の例とともにビルドを失敗させます。
- トップレベル関数に `@SpringBootApplication` (URL で照合、`spring_boot_dart` のもの) があれば、ステップは [アプリケーション](spring-boot-application.md) を組み立てます。一つのファイルに二つ以上あるとビルドが失敗します。
- そうでなく、トップレベル変数に `@ComponentScan` があれば、ステップは [モジュール](component-scan.md) を組み立てます。一つのファイルに二つ以上あるとビルドが失敗し、private な変数や名前が `$` で始まる変数でも失敗します。
- それ以外では何も書き出されません。

### 3. スキャンするファイルを見つける

ファイルの場所が、どのファイルが出力に属するかを決めます。このディレクトリが **スキャンルート** です。

- `@ComponentScan` ファイルでは、そのファイルのディレクトリ。
- `@SpringBootApplication` ファイルでは、`lib/` と `main` のディレクトリ (`example/` の下のエントリーポイントでは `example/` のみ)。

スキャンルートの下のすべての `.dart` ファイルはグロブで見つけられ、パスでソートされるので、出力はどのマシンでも同じです。生成された `.spring.dart` ファイルは除外されます。ルートの下で自身の `@ComponentScan` を宣言するファイルは、そのディレクトリを所有します。そのファイル群は除外され、代わりにそのモジュールがインポートされます ([入れ子のスキャン](component-scan.md#入れ子のスキャン) を参照)。

### 4. リソースを読む

`lib/resources/` のファイルが読まれ、テキストまたは base64 として埋め込まれます ([埋め込みリソース](resources.md) を参照)。Flutter アプリでは、ビルダーは型付きキーのファイルの `part` 行も決めます。

### 5. スキャン: 要素からモデルへ

各ライブラリが解決され、スキャナーはその宣言をモデルに変えます。コンポーネントクラスと `@Bean` メソッドごとに一つの Bean モデル (コンストラクター、注入ポイント、条件、ライフサイクルメソッド、イベントリスナー、プロキシを含む) と、`@Configurable` クラス、イントロスペクション、`@PropertySource`、`@Log`、データリポジトリ、Flutter ウィジェットのモデルです。

要素モデルだけでは足りない答えもあるため、ビルダーはライブラリをスキャンする前に、いくつかの本体の構文木も解決します。

- **`@Bean` メソッドの本体。** `DataSource` を返すと宣言され、`HikariDataSource(url)` を返す `@Bean` メソッドは `HikariDataSource` を登録します。本当の型を見つけるために本体が読まれます。
- **フィールドの初期化子**。クラスがフィールドに与える値のためです。
- **`ObjectMapper` の呼び出し**。どのクラスが JSON から読まれ、JSON に書かれるかを知り、使われるものだけにイントロスペクションを付けるためです ([実行されるものだけ](optimizations/introspection.md) を参照)。

スキャナーはすべての宣言の検証も行います。エラーがあってもスキャンは止まりません。すべてのライブラリの問題が集められ、まとめて報告されます。スキャンの後、ビルダーは二つの無条件の Bean が名前やエイリアスを共有していないかを確認し、`@Value('asset:...')` の値を `pubspec.yaml` と照合し、何か問題が見つかればビルドを失敗させます。[ビルド時のチェック](checks.md) を参照してください。

### 6. AOP

ビルダーは、どの Bean に生成されたプロキシクラスを付けるかを決めます。アプリケーションではすべてのモジュールのアドバイスがわかるので、どのポイントカットにも一致しえない Bean のプロキシを省けます ([AOP プロキシ](optimizations/aop-proxies.md) を参照)。アプリケーションでは、[自動構成](auto-configurations.md) を列挙するために、すべての依存関係の `lib/spring_auto_configuration.dart` も読みます。

### 7. 出力と整形

エミッターは `code_builder` でモデルを Dart に変えます。

1. 生成されるクラス (`.spring.proxies.dart` の part に入る AOP プロキシ、`@Configuration` と `@Lookup` のサブクラス、リポジトリクラス)。
2. Bean ごとに一つの `BeanDefinition`、埋め込みリソース、インポートされたモジュール、その他のモジュール引数を持つゲッター `BeanModule get $<name>`。
3. イントロスペクション対象のクラスの記述 (専用のライブラリ `.spring.introspection.dart` に入ります)、および `@ConfigurationProperties` のバインダーだけが使う記述 (`.spring.properties.dart`)。
4. アプリケーションでは、`springApplication`、`runApplication`、ホットリロードの関数。
5. `BuildContext` の拡張 (Flutter) と `@Log` の拡張。

すべてのライブラリはプレフィックス (`_i1.`、`_i2.` など) 付きでインポートされるので、コードの名前が生成された名前と衝突することはありません。スキャンされたライブラリがパッケージの公開ライブラリを通して型をインポートしている場合、生成ファイルもパッケージの `src/` ファイルではなく同じ公開ライブラリをインポートします。結果は `dart_style` で整形され、次のヘッダーで始まります。

```dart
// GENERATED CODE - DO NOT MODIFY BY HAND
// Generated by spring_core_dart_generator from @ComponentScan.

// ignore_for_file: type=lint, implementation_imports, unnecessary_cast
// ignore_for_file: deprecated_member_use, invalid_use_of_visible_for_testing_member
// ignore_for_file: invalid_use_of_internal_member, invalid_use_of_protected_member
```

生成コードにはアナライザーの警告がありません。それでも lint は無視されます (`type=lint`)。自分の lint セットが、ジェネレーターのテストに使われるものより厳しいかもしれないからです。

アプリケーションでは、ビルダーはさらに生成コード (ライブラリとそのファイル) のハッシュを計算し、デバッグ用の part `main.spring.debug.dart` に `_$fingerprint` として書き込みます。`springApplication` はそれを、デバッグとプロファイルのビルドでだけ `fingerprint:` として渡します。ホットリロードの際、ランタイムはそれを実行中のコンテキストのものと比べ、コンテキストを再起動すべきかを決めます ([@SpringBootApplication](spring-boot-application.md#ホットリロード) を参照)。

### 8. 書き出し

テキストは出力パスに書き出されます。ステップが失敗した場合は既存のファイルが残ります ([下記](None#ソースにエラーがあるとき) を参照)。

## コアのフォルダー

ジェネレーターのコア (`lib/src/core/`) は、`spring_core_dart` の `lib/src` と同じく、関心事ごとに分かれています。

| フォルダー | 内容 |
|---|---|
| `beans/` | Bean のスキャンとモデル、モジュールのエミッター、`@Configuration` と `@Lookup` のサブクラス、`@Log` |
| `aop/` | ポイントカット、アドバイザー、プロキシの判断 |
| `introspection/` | 専用のスキャナー、モデル、エミッター: クラスに記述が必要なもの、JSON とバリデーションのチェック、オブジェクトのメソッド、JSON Schema |
| `properties/` | `--dart-define` 用のプロパティキー、Dart の名前 |
| `spel/` | Dart にコンパイルされる SpEL |
| `metadata/` | `spring_metadata.json` |
| `builder/` | ビルダー、ビルド時の設定、ビルドのキー、パートのインターフェース |

Bean のスキャンとパッケージのパートは、記述を自分では作りません。クラスに何が必要か (コントローラーの結果は書き出される、リクエストボディは読み込まれる、式がメソッドを呼ぶ) をイントロスペクションに伝え、イントロスペクションがそのすべてのためにクラスを一度だけ記述します。

## パッケージのパート

コアは、Bean をスキャンし、その定義、プロキシ、イントロスペクションを書き、チェックします。コアは他のパッケージのパートの名前を挙げません。パッケージが加えるものは **パート** (`PackageGeneration`) で、ジェネレーターの `lib/src/<part>/` (`data/`、`flutter/`、`navigation/` など) にあります。パートはスターターのものではなく、パッケージのものです。いくつかのパートはライブラリ (`spring_web_dart`、`spring_security_core`、`spring_boot_actuator`) に属します。

- **パートは、アプリケーションがそのパッケージに届くときだけ動きます。** `pubspec.yaml` に列挙されているか、列挙したパッケージが持ち込むときです。Flutter スターターがなければ Flutter のコードは一つも動かず、データスターターがなければデータのコードも動きません。
- **パートは一度だけ列挙されます。** `lib/src/packages.dart` に、ビルダーが尋ねる順で並びます。この順が、パートが書くものの順であり、報告するエラーの順です。
- **パートはビルドのキーで外せます。** 自動構成モジュールと同じです。`PackageBuild` は `AutoConfigurationBuild` と同じように読まれます ([キーで決まるジェネレーターのパート](optimizations/build-conditions.md#キーで決まるジェネレーターのパート) を参照)。組み込みのパートでキーを取るものはまだありません。
- **ジェネレーターをパートに分けても、生成コードは変わりませんでした。** クリーンビルドの時間も同じです。
- フレームワークの外のパートのための公開された登録は、まだありません。

| パート | 待つパッケージ | 行うこと |
|---|---|---|
| データのメタデータ | `spring_boot_starter_data` | `spring_metadata.json` の `entities` と `repositories`。 |
| Flutter | `spring_boot_starter_flutter` | Spring ウィジェット、ローダーの種類、`SpringWidgetBindings` Bean、`BuildContext` のゲッター、アセットのチェック。 |
| ナビゲーション | `spring_boot_starter_flutter_navigation` | `@ScreenRoute` と `@RouteShell`: `ScreenRoutes` Bean と画面の定数。 |
| ChangeNotifier | `spring_boot_starter_flutter` | `@ChangeNotifierComponent`: プロキシに `ChangeNotifier` をミックスインします。 |
| シグナル | `spring_boot_starter_flutter_signals` | 追跡できない `@Signal`、`@Computed`、`@Effect` でビルドを失敗させます。 |
| Web | `spring_web_dart` | リクエストマッピングと `@ExceptionHandler` がその値をどう扱うか。 |
| WebSocket | `spring_boot_starter_websocket` | エンドポイントのハンドラーと `sendJson` がその値をどう扱うか。 |
| スケジューリング | `spring_boot_starter_scheduling` | `@Scheduled` メソッドに記述が必要なもの (なし)。 |
| セキュリティ | `spring_security_core` | メソッドセキュリティのアノテーションの式がどこを見るか。 |
| キャッシュ | `spring_boot_starter_cache` | キャッシュのアノテーションの式がどこを見るか。キャッシュされる `Stream` は不可。 |
| Actuator | `spring_boot_actuator` | アプリケーションのリソースに `build-info.properties` を加えます。 |
| データ | `spring_boot_starter_data` | エンティティ、リポジトリ、ドライバーのグルーとそのチェック。 |

`spring.json.schemas` の JSON Schema はパートではなくコアのものです。どのビルドでも求められ、その part ファイルはパートのものより後に来ます。各スターターのページ「ビルドに含まれるもの」は、そのスターターのためにどのパートが動くかを挙げています。たとえば [データスターターのページ](../spring-boot-starter-data/optimizations.md) です。

## 他のビルダー

他のビルダーはファイルごとには動きません。

- `spring_test` は `test/*_test.dart` ファイルごとに動きます。ファイルを解析するだけで (解決はしない)、`@SpringBootTest` または `@DataTest` クラスが見つからなければ何も書き出しません。
- `spring_metadata`、`spring_flutter_keys`、`spring_flutter_web`、`spring_flutter_page_loader`、`spring_flutter_seo`、`spring_flutter_deep_links` はパッケージごとに一度動きます (入力は `build_runner` の `$package$` プレースホルダー)。それぞれ、まずパッケージがそれを必要とするかを確認し、必要なければ何も書き出しません。

自分のファイル (`web_dev_config.yaml`、`web/index.html`、`web/`、`Info.plist`、`AndroidManifest.xml` など) に書き込む四つの Flutter ビルダーは、`build_runner` に出力を宣言しません。宣言された出力は、ビルダーが書き出すのをやめたときに `build_runner` に削除され、手で書いた同名のファイルを上書きしてしまいます。これらのビルダーは自分でファイルを管理し、マーカーの間やヘッダーの後ろに書き、自分が書いていない内容には決して触れません。[ビルダー](builders.md) を参照してください。

## インクリメンタルビルド

`build_runner` は、ステップが読むすべてのファイルを記録します。入力、解決するライブラリ (とそれがインポートするもの)、グロブが見つけたファイル、`pubspec.yaml`、`lib/resources/` のファイルです。次のビルドでは、そのいずれかが変わった場合にだけステップが再実行されます。実際には次のようになります。

- スキャンルートの下の Bean クラスを変えると、そのルートのモジュールが再生成されます。アプリケーションのステップも再実行されます (インポートするモジュールのライブラリを解決するため) が、そのファイルが変わるのは書き出す内容が変わったときだけです。
- スキャンされるディレクトリにファイルを追加すると、グロブの結果が変わるので、そのモジュールが再生成されます。
- `lib/resources/` のファイルを変えると、それを埋め込むすべての出力が再生成されます。
- どのステップも読まなかったファイル (スキャンされるものがインポートしない、スキャンルートの外のファイル) を変えても、何も再生成されません。

出力は時刻やマシンに依存しません。ファイルはパスでソートされ、キーもソートされ、時計から書き出されるものはありません (この理由で、アクチュエーターアプリの生成された `build-info.properties` にはビルド時刻がありません)。ソースに変更のないビルドは同じバイト列を書き出すので、生成ファイルが `git diff` に現れるのは本当に何かが変わったときだけです。

## watch の場合

`dart run build_runner watch` はビルドを一つ動かし続け、ファイルが変わると再ビルドします。ビルダーのオブジェクトはプロセスと同じだけ生き続け、メインのビルダーはそれを利用します。

- 出力ごとに、最後に生成した内容を覚えています。
- 入力中は、スキャンされるライブラリに構文エラーがあることがよくあります。その場合、ビルダーは最後の正常な内容を再び書き出すので生成ファイルは変わらず、次の生成が成功するまで出力ごとに一つの警告をログに出します。
- 検証エラー (間違った場所のアノテーション、不正なポイントカット) はビルドエラーとして報告され、ファイルは元のまま残ります。

そのため、キーを押すたびに生成ファイルが消え、それをインポートするすべてのファイルが赤くなるのをエディターが目にすることはありません。

## ソースにエラーがあるとき

| 状況 | 既存の生成ファイルがある場合 | ない場合 (コールドビルド) |
|---|---|---|
| スキャンされるライブラリに構文エラーがある | ファイルは残り、警告が一つログに出る | ビルドが失敗する |
| 検証エラー、またはエラーのあるコードでのクラッシュ | ファイルは残り、エラーでビルドが失敗する | ビルドが失敗する |
| テストファイルに構文エラーがある (`spring_test`) | ファイルは残り、警告がログに出る | 何も書き出されず、警告がログに出る |

既存のファイルはそれ自身のパッケージのディレクトリから読まれます。`dart run build_runner build --workspace` が一つのディレクトリから pub ワークスペースのすべてのパッケージをビルドする場合も同じです。詳しくは [エラーと生成ファイル](errors.md) を参照してください。

## ビルダーを制限する

パッケージは、自身の `build.yaml` で `build_runner` の通常の設定を使い、ビルダーの対象を絞ったり無効にしたりできます。Spring for Dart のスターターはこれを行っています。アプリケーションなのはサンプルだけで、残りは手で書かれています。

```yaml
# spring_boot_starter_web の build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        generate_for: [example/**, test/app/**]
      spring_core_dart_generator:spring_properties:
        enabled: true
        generate_for: [lib/src/config/**]
      spring_core_dart_generator:spring_test:
        enabled: false
```

各ビルダーが何をし、どれを有効のままにすべきかは [ビルダー](builders.md) を参照してください。

## Spring (Java) との対応

Spring はコンテキストの起動時にクラスパスをスキャンします。`ClassPathBeanDefinitionScanner` がベースパッケージのクラスファイルを読み、`ConfigurationClassPostProcessor` が `@Bean` メソッドを解析し、リフレクションが Bean を生成します。Spring 6 AOT は代わりにこの解析をビルド中に行い (`BeanFactoryInitializationAotProcessor`)、Bean を登録する Java ソースを書き出せます。主に GraalVM ネイティブイメージ向けです。Dart はほとんどのプラットフォームで他の方法を提供しないため、ジェネレーターは常に Spring AOT のように動きます。

## 関連項目

- [ビルダー](builders.md)
- [@ComponentScan モジュール](component-scan.md)
- [ビルド速度](optimizations/build-speed.md)
- [BeanModule](../spring-core-dart/beans/bean-module.md)
