
# ビルダー

`spring_core_dart_generator` は `build.yaml` に九つのビルダーを登録します。そのうち八つは、ジェネレーターに依存するすべてのパッケージに自動で適用されます。`spring_properties` はパッケージが有効にするまで無効です。各ビルダーはまずパッケージがそれを必要とするかを確認し、必要なければ何も書き出しません。そのため、純粋な Dart サーバーに Flutter のファイルができることはなく、テーマのない Flutter アプリにテーマキーができることもありません。

## ビルダーが複数ある理由

`build_runner` のビルダーは、入力と出力をあらかじめ宣言します。ジェネレーターの出力にはさまざまな形があります。

- スキャンされるライブラリごとに一つの `.spring.dart` ファイル (メインのビルダー)。
- テストファイルごとに一つのファイル (テストのビルダー)。
- パッケージごとに一つのファイル (`spring_metadata.json`、型付きキー)。
- アプリが所有し、自分でも編集するファイル (`web/index.html`、`Info.plist`、`AndroidManifest.xml`、`web_dev_config.yaml`)。これらは出力として宣言してはいけません。`build_runner` が手書きの同名ファイルを上書きし、ビルダーが書き出すのをやめたときに削除してしまうからです。

形ごとにそれぞれのビルダーがあります。分けておくことで、パッケージは使わないものを無効にすることもできます。

## 概要

| ビルダー | 入力 | 書き出すもの | 動く条件 |
|---|---|---|---|
| [`spring_core_dart`](#spring_core_dart) | `lib/`、`bin/`、`test/`、`example/` のすべての `.dart` ファイル | `<root>/spring_gen/<path>.spring.dart` | ファイルに `@ComponentScan` または `@SpringBootApplication` がある |
| [`spring_properties`](#spring_properties) | `lib/` のすべての `.dart` ファイル | `lib/spring_gen/<path>.spring.dart` | パッケージが有効にする (デフォルトでは無効) |
| [`spring_test`](#spring_test) | `test/**_test.dart` | `test/spring_gen/<name>.test.spring.dart` | ファイルに `@SpringBootTest` または `@DataTest` クラスがある |
| [`spring_prefetch`](#spring_prefetch) | パッケージ | `lib/resources/spring_gen/prefetch/resources.json` | `spring.resources.prefetch.locations` が設定されている |
| [`spring_search_index`](#spring_search_index) | パッケージ | `lib/resources/spring_gen/search/<language>.json` | `spring.search.markdown` が設定されている |
| [`spring_json_schemas`](#spring_json_schemas) | パッケージ | `lib/spring_gen/json_schemas.spring.classes.dart` | `spring.json.schemas` が設定されている |
| [`spring_metadata`](#spring_metadata) | パッケージ | `lib/spring_gen/spring_metadata.json` | `lib/` または `bin/` に Spring のコードがある |
| [`spring_flutter_keys`](#spring_flutter_keys) | パッケージ | `lib/spring_gen/theme.spring.keys.dart`、`lib/spring_gen/messages.spring.keys.dart` | パッケージが `spring_boot_starter_flutter` に依存し、テーマのプロパティまたはメッセージファイルがある |
| [`spring_flutter_web`](#spring_flutter_web) | パッケージ | `web_dev_config.yaml` (宣言なし) | `spring.flutter.web.dev-server.*` または `spring.flutter.security.web.mode` が設定されている |
| [`spring_flutter_page_loader`](#spring_flutter_page_loader) | パッケージ | `web/index.html` のブロック (宣言なし) | パッケージが `spring_boot_starter_flutter` に依存し、`web/index.html` がある |
| [`spring_flutter_seo`](#spring_flutter_seo) | パッケージ | `web/` のページ、`sitemap.xml`、`robots.txt`、`llms.txt` (宣言なし) | `spring.flutter.web.seo.enabled` が `true` で、`web/index.html` が存在する |
| [`spring_flutter_deep_links`](#spring_flutter_deep_links) | パッケージ | `Info.plist`、`Runner.entitlements`、`AndroidManifest.xml` のブロック、ドメインのファイル (宣言なし) | `spring.flutter.navigation.deep-links.*` が設定されている |

`build.yaml` では、ビルダーはパッケージ名を先頭に付けて `spring_core_dart_generator:spring_core_dart` のように書きます。

## spring_core_dart

メインのビルダーです。Bean のモジュールとアプリケーションを書き出します。

- **読むもの:** `lib/`、`bin/`、`test/`、`example/` の `.dart` ファイル。テキストに `ComponentScan` または `SpringBootApplication` が含まれていれば、そのファイルが解決され、次にスキャンルートの下のすべてのライブラリ、`lib/resources/` のファイル、`pubspec.yaml`、(アプリケーションでは) すべての依存関係の `lib/spring_auto_configuration.dart` が読まれます。
- **書き出すもの:** `<root>/spring_gen/<path>.spring.dart`。[`@ComponentScan` 変数](component-scan.md) には `BeanModule`、`@SpringBootApplication` の `main` には [アプリケーション](spring-boot-application.md) 全体です。
- **何もしない場合:** どちらのアノテーションもないすべてのファイル。そのようなファイルは解決すらされません。
- **オプション:**

| オプション | 値 | デフォルト | ページ |
|---|---|---|---|
| `aop_proxies` | `all`、`interfaces`、`none` | `all` | [AOP プロキシ](optimizations/aop-proxies.md) |
| `aop_prune` | `true`、`false` | `true` | [AOP プロキシ](optimizations/aop-proxies.md) |
| `aop_defer` | `true`、`false` | `false` | [AOP プロキシ](optimizations/aop-proxies.md) |
| `dart_defines_exclude` | プロパティ名のプレフィックスのリスト | `[]` | [--dart-define キー](dart-defines.md#キーを外す) |

間違った値 (未知の `aop_proxies` モード、真偽値でない値、`dart_defines_exclude` のワイルドカード) は `ArgumentError` でビルドを失敗させます。すべてのオプションは [オプション](options.md) にあります。

```yaml
# 自分のパッケージの build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          aop_proxies: interfaces
          dart_defines_exclude: [spring.flutter.theme]
```

## spring_properties

これもメインのビルダーですが、`lib/` に限定され、`spring_core_dart` より前の独自のフェーズに置かれます (`runs_before`)。

- **存在する理由:** 手書きのスターターは、`lib/` の `@ComponentScan` ライブラリを通して `@ConfigurationProperties` クラスをバインドし、自身の `lib/` が生成されたモジュールをインポートします。そのサンプル (メインのビルダーが生成する) はその `lib/` をインポートします。ビルダーは同じフェーズの別の入力が書き出すものを読めないため、`lib/` の部分は一つ前のフェーズで生成され、サンプルのステップがそれを読めるようにしています。
- **読むものと書き出すもの:** メインのビルダーと同じで、`lib/` のみ。
- **オプション:** `spring_core_dart` と同じ。
- **デフォルトでは無効** (`auto_apply: none`)。パッケージは `enabled: true` で有効にし、メインのビルダーをサンプルに限定します。

```yaml
# spring_boot_starter_flutter_security の build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        generate_for: [example/**]
      spring_core_dart_generator:spring_properties:
        enabled: true
        generate_for: [lib/src/properties/**]
      spring_core_dart_generator:spring_test:
        enabled: false
```

アプリケーションには不要です。

## spring_test

テストのビルダーです。[テスト](tests.md) を参照してください。

- **読むもの:** 各 `test/<name>_test.dart`。テキストに `SpringBootTest` または `DataTest` が含まれていれば、解析され (解決はされない)、そのテストクラスが読まれます。テスト対象のアプリケーションを見つけるため、`bin/` と `lib/` の `.dart` ファイルも見ます。
- **書き出すもの:** テストの `main` が呼ぶ `runSpringTests()` 関数を持つ `test/spring_gen/<name>.test.spring.dart`。
- **何もしない場合:** `@SpringBootTest` や `@DataTest` クラスのないテストファイル。
- **オプション:** なし。

## spring_json_schemas

`spring.json.schemas` の JSON Schema のクラスを書き出します。[JSON Schema のクラス](json-schema-classes.md) を参照してください。

- **読むもの:** `spring.json.schemas[n].*` (アプリケーションがプロファイルなしで読むのと同じ方法)、`lib/resources/` の `resources:` のスキーマ、リモートのスキーマ (`https://`、`github:`)。リモートのものはビルドのたびにダウンロードし、`.dart_tool/spring/json_schemas/` に保存します。
- **書き出すもの:** `lib/spring_gen/json_schemas.spring.classes.dart`。アプリケーションの `.spring.dart` ライブラリの part です。メインのビルダーが、そのクラスのイントロスペクションをモジュールに渡し、リモートのスキーマをリソースとして埋め込みます。
- **何もしない場合:** `spring.json.schemas` が設定されていないとき。
- **オプション:** なし。

## spring_prefetch

`spring.resources.prefetch.locations` のファイルを、Flutter の Web アプリが一度だけダウンロードする 1 つのファイルに書き出します。[まとめてダウンロードする](resources.md#まとめてダウンロードする) を参照してください。

- **読むもの:** `spring.resources.prefetch.locations` (プロファイルなし) と、その glob に一致する `lib/resources/` のテキストファイル。
- **書き出すもの:** `lib/resources/spring_gen/prefetch/resources.json` を部分ごとに 1 行で、ディスクに書きます (宣言された出力はありません)。埋め込みはしません。`flutter: assets:` にないときは警告します。
- **何もしないとき:** locations がないとき。以前に書いたファイルは消します。
- **オプション:** なし。

## spring_search_index

`spring.search.markdown` の検索インデックスを書き出し、アプリはそれを作る代わりに読みます。[ビルドが書くインデックス](../spring-search-dart/searching.md#ビルドが書くインデックス) を参照してください。

- **読むもの:** `spring.search.markdown[n].*`、`spring.search.analyzers.*`、`spring.search.default-language` (プロファイルなし) と、その `resources:` の場所にある Markdown ファイル。アプリ自身の `spring_search_dart` で分割・解析します。ビルダーはその `bin/search_index.dart` をアプリのパッケージで実行するので (最長 3 分)、ジェネレーターは検索に依存せず、それを持たないパッケージには何も書きません。
- **書き出すもの:** 言語ごとに `lib/resources/spring_gen/search/<language>.json` をディスクに書きます (宣言された出力はありません。言語はページを読んで初めてわかるからです)。なくなった言語のファイルは消します。メインのビルダーはこれを埋め込みません。Flutter アプリはそのディレクトリを `flutter: assets:` に書き、ないときは警告されます。
- **何もしないとき:** `spring.search.markdown` がないとき、`spring.search.prebuilt: false` または `spring.search.enabled: false` のとき、`resources:` 以外の場所のとき。アナライザーがアプリ自身のビーンである言語にはファイルはできません。
- **オプション:** なし。

## spring_metadata

エディターやツールが読むメタデータを書き出します。[エディター向けのメタデータ](metadata.md) を参照してください。

- **読むもの:** `lib/` と `bin/` の `.dart` ファイル (生成ファイルを除く) と `lib/resources/`。
- **書き出すもの:** `lib/spring_gen/spring_metadata.json`。説明とデフォルトを持つ設定プロパティ、Bean、プロファイル、値のヒント、Flutter ではテーマ、ローダーの種類、ルートです。
- **何もしない場合:** `lib/` や `bin/` のどのファイルも Spring のコードに触れていないとき。`ComponentScan`、`SpringBootApplication`、`AutoConfigurationModule`、`ConfigurationProperties`、手書きの `BeanDefinition<`、`@Component`、`@Service`、`@Configuration`、`@Bean`、`@ThemeLoaderKind`、`@ScreenRoute`、`@RouteShell` です。
- **エラー時:** メインのビルダーと同じく、ソースにエラーがある間は既存のファイルを残します。
- このファイルからルートを読む `spring_flutter_seo` **より前に動きます**。
- **オプション:** なし。

## spring_flutter_keys

Flutter アプリの設定の型付きキー `context.theme` と `context.messages` を書き出します。[型付きキー](flutter/typed-keys.md) を参照してください。

- **読むもの:** `lib/resources/` のすべての `.yml`、`.yaml`、`.properties` ファイル (すべてのプロファイル、すべてのテーマ)、`spring.config.import` が依存関係から指定する `resources:` のファイル、`lib/` の `@ThemeLoaderKind` クラス、依存関係の `spring_metadata.json` に列挙されたローダーの種類。
- **書き出すもの:** `lib/spring_gen/theme.spring.keys.dart` (`spring.flutter.theme.*` プロパティがある場合) と `lib/spring_gen/messages.spring.keys.dart` (`messages*.properties` ファイルがある場合)。どちらも、パッケージの `@SpringBootApplication` ライブラリ、なければ最も外側の `@ComponentScan` の `.spring.dart` の `part of` です。
- **何もしない場合:** `pubspec.yaml` に `spring_boot_starter_flutter` で始まる依存関係名がないとき、またはテーマのプロパティもメッセージファイルもないとき。`@ComponentScan` や `@SpringBootApplication` を持つライブラリがなければ、何も書き出されず、警告がその理由を伝えます。一つのパッケージに無関係なスキャンルートがあると、その名前とともに失敗します。
- **オプション:** なし。

## spring_flutter_web

`flutter run` が Web 向けに読むファイル `web_dev_config.yaml` を書き出します (Flutter 3.38 以降)。[Web 開発サーバー](flutter/web-dev-server.md) を参照してください。

- **読むもの:** アプリがブラウザーで読むのと同じように、`lib/resources/` の設定ファイル (`application.*`、`application-web.*`、アクティブなプロファイル、`spring.config.import`)。
- **書き出すもの:** パッケージのディレクトリの `web_dev_config.yaml`。宣言された出力ではありません。ビルダーは自身のヘッダー `# GENERATED FILE - DO NOT MODIFY BY HAND.` で始まるファイルだけを書き込み、削除し、プロパティがなくなるとそれを削除します。同名の手書きファイルがあり、かつプロパティもある場合はビルドが失敗し、どちらかを取り除くよう求めます。
- **何もしない場合:** 設定ファイルが `spring.flutter.web.dev-server.*` キーも `spring.flutter.security.web.mode` も設定していないとき。その場合は設定の読み込みすら行われないので、純粋な Dart パッケージのビルドを失敗させることはありません。
- **オプション:** なし。

## spring_flutter_page_loader

アクティブなテーマの `splash` のページローダーを `web/index.html` に書き込み、Flutter が起動する前にブラウザーがアプリの見た目を表示できるようにします。[ページローダー](flutter/page-loader.md) を参照してください。

- **読むもの:** `lib/resources/` (テーマ)、`web/index.html`、アプリ独自のローダーの種類の `web:` HTML ファイル。
- **書き出すもの:** `web/index.html` の `<!-- spring:loader:start -->` と `<!-- spring:loader:end -->` の間のブロック。マーカーがなければ `<body>` の後に挿入され、ファイルの残りには決して触れません。ブロックはビルドのたびに書き直され、テーマにスプラッシュがなければマーカーごと取り除かれます。
- **何もしない場合:** パッケージが `spring_boot_starter_flutter` (名前がそれで始まる任意の依存関係) に依存していないとき、または `web/index.html` が存在しないとき (作られることはありません)。使えないもの (たとえば読めないローダーの `web:` ファイル) のほとんどは、エラーではなく警告です。
- ページが `web/index.html` のコピーである `spring_flutter_seo` **より前に動きます**。
- **オプション:** なし。

## spring_flutter_seo

Flutter Web アプリはキャンバスに描画し、その HTML にはテキストがないため、検索エンジン、リンクプレビュー、言語モデルが読むページを書き出します。[検索エンジン向けのページ](flutter/seo.md) を参照してください。

- **読むもの:** `spring.flutter.web.seo.*` (`web` プロファイル付き)、`lib/resources/` の Markdown ファイル、`web/index.html`、`lib/spring_gen/spring_metadata.json` のルート。
- **書き出すもの:** `web/` の中に、ページごとの `<path>/index.html`、`<path>.md`、`sitemap.xml`、`robots.txt`、`llms.txt`、`llms-full.txt`。ルートページは `web/index.html` の `spring:seo` マーカーの間に書かれます。書き出したファイルは `web/.spring-seo` に列挙されるので、なくなったページは次のビルドで削除されます。
- **何もしない場合:** `spring.flutter.web.seo.enabled` が `true` で、かつ `web/index.html` が存在する場合を除いて (プロパティが設定されていてもページがなければ警告します)。プロパティがなくなると、以前に書き出したページは取り除かれます。
- **オプション:** なし。

## spring_flutter_deep_links

アプリのディープリンクをプラットフォームのファイルに書き込み、ドメインが配信するファイルも書き出します。[ディープリンク](flutter/deep-links.md) を参照してください。

- **読むもの:** `spring.flutter.navigation.deep-links.*`。プラットフォームごとに、そのプラットフォームのプロファイル (`ios` と `mobile`、`android` と `mobile`、`macos` と `desktop`) で読まれます。
- **書き出すもの:** `ios/Runner/Info.plist`、`ios/Runner/Runner.entitlements` (存在する場合)、`macos/Runner/Info.plist`、`android/app/src/main/AndroidManifest.xml` の `spring:deep-links:start` と `spring:deep-links:end` の間のブロック。そして `apple-app-site-association` と `assetlinks.json` (Web 版のあるアプリでは `web/.well-known/` に、それ以外では `build/spring/well-known/` に)。手で変更されたブロックはビルドを失敗させます。
- **何もしない場合:** どの設定ファイルも `deep-links` に触れていないとき。プロパティがなくなったブロックは取り除かれます。
- **オプション:** なし。

## ビルダーを無効にする

パッケージの `build.yaml` (`pubspec.yaml` の隣) で、`build_runner` の `enabled` 設定を使います。

```yaml
# build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_flutter_seo:
        enabled: false
      spring_core_dart_generator:spring_test:
        enabled: false
```

ビルダーを残したまま、見るファイルを制限するには `generate_for` を使います。

```yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        generate_for: [example/**]
```

### 有効のままにすべきもの

| ビルダー | 無効にできるか |
|---|---|
| `spring_core_dart` | アプリケーションや `@ComponentScan` モジュールを持つパッケージではできません。コードがそれが書き出すファイルをインポートするからです。手書きのパッケージ (スターター) は無効にするか、サンプルに限定できます。 |
| `spring_flutter_keys` | テーマのプロパティやメッセージファイルを持つ Flutter アプリでは、**`spring_core_dart` が動いている間はできません**。メインのビルダーは、`theme.spring.keys.dart` と `messages.spring.keys.dart` の `part` 行を、ファイルが存在するかを確認せずに書きます (別のフェーズで書き出されるので確認できません)。そのため、キーのビルダーがないと、生成されたライブラリは存在しない part を指し、コンパイルできません。 |
| `spring_metadata` | できます。ただし、`spring_flutter_seo` はそのファイルからルートを取り、アプリのキーのビルダーはそこでライブラリのローダーの種類を見つけ、エディターは補完を失います。ローダーの種類やルートを宣言するライブラリでは有効のままにしてください。 |
| `spring_search_index` | できます。その場合、アプリは `spring.search.prebuilt: false` のときと同じく検索インデックスを自分で作ります。 |
| `spring_json_schemas` | できます。ただしその場合、`spring.json.schemas` はクラスを書き出さず、メインのビルダーもモジュールにそのイントロスペクションを渡しません。 |
| `spring_test` | `@SpringBootTest` や `@DataTest` を使うテストがなければできます。 |
| `spring_flutter_web`、`spring_flutter_page_loader`、`spring_flutter_seo`、`spring_flutter_deep_links` | できます。アプリが所有するファイルにだけ書き込みます。無効にしたものは、以前に書き出したものを更新も削除もしなくなります。 |
| `spring_properties` | デフォルトで無効です。 |

## Spring (Java) との対応

Spring Boot には、同様の役割を果たすビルド時のツールが二つあります。`META-INF/spring-configuration-metadata.json` を書き出すアノテーションプロセッサー `spring-boot-configuration-processor` (`spring_metadata` に相当) と、Bean 定義の Java ソースを書き出す Maven と Gradle のプラグインの Spring AOT エンジン (`spring_core_dart` に相当) です。Flutter のビルダーに相当するものは Spring にはありません。

## 関連項目

- [生成の仕組み](how-it-works.md)
- [オプション](options.md)
- [Flutter](flutter/index.md)
