生成の仕組み
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 が起動時に見つける間違い (置き場所の誤ったアノテーション、解析できないポイントカット、生成コードが名前を書けない型) は、ソースを指すビルドエラーになります。
構成要素
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 |
ビルダーごと | ビルダーがどの入力を見て、どのファイルを書き出せるか (パスの対応 を参照)。 |
runs_before |
三つのビルダーに | ジェネレーターが求める唯一の順序 (順序 を参照)。 |
ビルダーの順序
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 を無効にしてはいけません (ビルダー を参照)。
ファイルの置き場所
メインのビルダーは、四つのソースルートの .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) を持つライブラリと、オブジェクトのメソッド の 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 でインポートします。
// 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のもの) があれば、ステップは アプリケーション を組み立てます。一つのファイルに二つ以上あるとビルドが失敗します。 - そうでなく、トップレベル変数に
@ComponentScanがあれば、ステップは モジュール を組み立てます。一つのファイルに二つ以上あるとビルドが失敗し、private な変数や名前が$で始まる変数でも失敗します。 - それ以外では何も書き出されません。
3. スキャンするファイルを見つける
ファイルの場所が、どのファイルが出力に属するかを決めます。このディレクトリが スキャンルート です。
@ComponentScanファイルでは、そのファイルのディレクトリ。@SpringBootApplicationファイルでは、lib/とmainのディレクトリ (example/の下のエントリーポイントではexample/のみ)。
スキャンルートの下のすべての .dart ファイルはグロブで見つけられ、パスでソートされるので、出力はどのマシンでも同じです。生成された .spring.dart ファイルは除外されます。ルートの下で自身の @ComponentScan を宣言するファイルは、そのディレクトリを所有します。そのファイル群は除外され、代わりにそのモジュールがインポートされます (入れ子のスキャン を参照)。
4. リソースを読む
lib/resources/ のファイルが読まれ、テキストまたは base64 として埋め込まれます (埋め込みリソース を参照)。Flutter アプリでは、ビルダーは型付きキーのファイルの part 行も決めます。
5. スキャン: 要素からモデルへ
各ライブラリが解決され、スキャナーはその宣言をモデルに変えます。コンポーネントクラスと @Bean メソッドごとに一つの Bean モデル (コンストラクター、注入ポイント、条件、ライフサイクルメソッド、イベントリスナー、プロキシを含む) と、@Configurable クラス、イントロスペクション、@PropertySource、@Log、データリポジトリ、Flutter ウィジェットのモデルです。
要素モデルだけでは足りない答えもあるため、ビルダーはライブラリをスキャンする前に、いくつかの本体の構文木も解決します。
@Beanメソッドの本体。DataSourceを返すと宣言され、HikariDataSource(url)を返す@BeanメソッドはHikariDataSourceを登録します。本当の型を見つけるために本体が読まれます。- フィールドの初期化子。クラスがフィールドに与える値のためです。
ObjectMapperの呼び出し。どのクラスが JSON から読まれ、JSON に書かれるかを知り、使われるものだけにイントロスペクションを付けるためです (実行されるものだけ を参照)。
スキャナーはすべての宣言の検証も行います。エラーがあってもスキャンは止まりません。すべてのライブラリの問題が集められ、まとめて報告されます。スキャンの後、ビルダーは二つの無条件の Bean が名前やエイリアスを共有していないかを確認し、@Value('asset:...') の値を pubspec.yaml と照合し、何か問題が見つかればビルドを失敗させます。ビルド時のチェック を参照してください。
6. AOP
ビルダーは、どの Bean に生成されたプロキシクラスを付けるかを決めます。アプリケーションではすべてのモジュールのアドバイスがわかるので、どのポイントカットにも一致しえない Bean のプロキシを省けます (AOP プロキシ を参照)。アプリケーションでは、自動構成 を列挙するために、すべての依存関係の lib/spring_auto_configuration.dart も読みます。
7. 出力と整形
エミッターは code_builder でモデルを Dart に変えます。
- 生成されるクラス (
.spring.proxies.dartの part に入る AOP プロキシ、@Configurationと@Lookupのサブクラス、リポジトリクラス)。 - Bean ごとに一つの
BeanDefinition、埋め込みリソース、インポートされたモジュール、その他のモジュール引数を持つゲッターBeanModule get $<name>。 - イントロスペクション対象のクラスの記述 (専用のライブラリ
.spring.introspection.dartに入ります)、および@ConfigurationPropertiesのバインダーだけが使う記述 (.spring.properties.dart)。 - アプリケーションでは、
springApplication、runApplication、ホットリロードの関数。 BuildContextの拡張 (Flutter) と@Logの拡張。
すべてのライブラリはプレフィックス (_i1.、_i2. など) 付きでインポートされるので、コードの名前が生成された名前と衝突することはありません。スキャンされたライブラリがパッケージの公開ライブラリを通して型をインポートしている場合、生成ファイルもパッケージの src/ ファイルではなく同じ公開ライブラリをインポートします。結果は dart_style で整形され、次のヘッダーで始まります。
// 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 を参照)。
8. 書き出し
テキストは出力パスに書き出されます。ステップが失敗した場合は既存のファイルが残ります (下記 を参照)。
コアのフォルダー
ジェネレーターのコア (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と同じように読まれます (キーで決まるジェネレーターのパート を参照)。組み込みのパートでキーを取るものはまだありません。 - ジェネレーターをパートに分けても、生成コードは変わりませんでした。 クリーンビルドの時間も同じです。
- フレームワークの外のパートのための公開された登録は、まだありません。
| パート | 待つパッケージ | 行うこと |
|---|---|---|
| データのメタデータ | 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_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 に削除され、手で書いた同名のファイルを上書きしてしまいます。これらのビルダーは自分でファイルを管理し、マーカーの間やヘッダーの後ろに書き、自分が書いていない内容には決して触れません。ビルダー を参照してください。
インクリメンタルビルド
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 ワークスペースのすべてのパッケージをビルドする場合も同じです。詳しくは エラーと生成ファイル を参照してください。
ビルダーを制限する
パッケージは、自身の build.yaml で build_runner の通常の設定を使い、ビルダーの対象を絞ったり無効にしたりできます。Spring for Dart のスターターはこれを行っています。アプリケーションなのはサンプルだけで、残りは手で書かれています。
# 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
各ビルダーが何をし、どれを有効のままにすべきかは ビルダー を参照してください。
Spring (Java) との対応
Spring はコンテキストの起動時にクラスパスをスキャンします。ClassPathBeanDefinitionScanner がベースパッケージのクラスファイルを読み、ConfigurationClassPostProcessor が @Bean メソッドを解析し、リフレクションが Bean を生成します。Spring 6 AOT は代わりにこの解析をビルド中に行い (BeanFactoryInitializationAotProcessor)、Bean を登録する Java ソースを書き出せます。主に GraalVM ネイティブイメージ向けです。Dart はほとんどのプラットフォームで他の方法を提供しないため、ジェネレーターは常に Spring AOT のように動きます。