ビルダー
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 |
lib/、bin/、test/、example/ のすべての .dart ファイル |
<root>/spring_gen/<path>.spring.dart |
ファイルに @ComponentScan または @SpringBootApplication がある |
spring_properties |
lib/ のすべての .dart ファイル |
lib/spring_gen/<path>.spring.dart |
パッケージが有効にする (デフォルトでは無効) |
spring_test |
test/**_test.dart |
test/spring_gen/<name>.test.spring.dart |
ファイルに @SpringBootTest または @DataTest クラスがある |
spring_prefetch |
パッケージ | lib/resources/spring_gen/prefetch/resources.json |
spring.resources.prefetch.locations が設定されている |
spring_search_index |
パッケージ | lib/resources/spring_gen/search/<language>.json |
spring.search.markdown が設定されている |
spring_json_schemas |
パッケージ | lib/spring_gen/json_schemas.spring.classes.dart |
spring.json.schemas が設定されている |
spring_metadata |
パッケージ | lib/spring_gen/spring_metadata.json |
lib/ または bin/ に Spring のコードがある |
spring_flutter_keys |
パッケージ | lib/spring_gen/theme.spring.keys.dart、lib/spring_gen/messages.spring.keys.dart |
パッケージが spring_boot_starter_flutter に依存し、テーマのプロパティまたはメッセージファイルがある |
spring_flutter_web |
パッケージ | web_dev_config.yaml (宣言なし) |
spring.flutter.web.dev-server.* または spring.flutter.security.web.mode が設定されている |
spring_flutter_page_loader |
パッケージ | web/index.html のブロック (宣言なし) |
パッケージが spring_boot_starter_flutter に依存し、web/index.html がある |
spring_flutter_seo |
パッケージ | web/ のページ、sitemap.xml、robots.txt、llms.txt (宣言なし) |
spring.flutter.web.seo.enabled が true で、web/index.html が存在する |
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変数 にはBeanModule、@SpringBootApplicationのmainには アプリケーション 全体です。 - 何もしない場合: どちらのアノテーションもないすべてのファイル。そのようなファイルは解決すらされません。
- オプション:
| オプション | 値 | デフォルト | ページ |
|---|---|---|---|
aop_proxies |
all、interfaces、none |
all |
AOP プロキシ |
aop_prune |
true、false |
true |
AOP プロキシ |
aop_defer |
true、false |
false |
AOP プロキシ |
dart_defines_exclude |
プロパティ名のプレフィックスのリスト | [] |
--dart-define キー |
間違った値 (未知の aop_proxies モード、真偽値でない値、dart_defines_exclude のワイルドカード) は ArgumentError でビルドを失敗させます。すべてのオプションは オプション にあります。
# 自分のパッケージの 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で有効にし、メインのビルダーをサンプルに限定します。
# 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
テストのビルダーです。テスト を参照してください。
- 読むもの: 各
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 のクラス を参照してください。
- 読むもの:
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 つのファイルに書き出します。まとめてダウンロードする を参照してください。
- 読むもの:
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.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
エディターやツールが読むメタデータを書き出します。エディター向けのメタデータ を参照してください。
- 読むもの:
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 を書き出します。型付きキー を参照してください。
- 読むもの:
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 開発サーバー を参照してください。
- 読むもの: アプリがブラウザーで読むのと同じように、
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 が起動する前にブラウザーがアプリの見た目を表示できるようにします。ページローダー を参照してください。
- 読むもの:
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 にはテキストがないため、検索エンジン、リンクプレビュー、言語モデルが読むページを書き出します。検索エンジン向けのページ を参照してください。
- 読むもの:
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
アプリのディープリンクをプラットフォームのファイルに書き込み、ドメインが配信するファイルも書き出します。ディープリンク を参照してください。
- 読むもの:
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 設定を使います。
# build.yaml
targets:
$default:
builders:
spring_core_dart_generator:spring_flutter_seo:
enabled: false
spring_core_dart_generator:spring_test:
enabled: false
ビルダーを残したまま、見るファイルを制限するには generate_for を使います。
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 にはありません。