生成の仕組み

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

ビルド時に行う理由

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

構成要素

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. ライブラリの解決

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

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

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

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

4. リソースを読む

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

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

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

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

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

6. AOP

ビルダーは、どの Bean に生成されたプロキシクラスを付けるかを決めます。アプリケーションではすべてのモジュールのアドバイスがわかるので、どのポイントカットにも一致しえない Bean のプロキシを省けます (AOP プロキシ を参照)。アプリケーションでは、自動構成 を列挙するために、すべての依存関係の 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 で整形され、次のヘッダーで始まります。

// 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) に属します。

パート 待つパッケージ 行うこと
データのメタデータ 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 ファイルはパートのものより後に来ます。各スターターのページ「ビルドに含まれるもの」は、そのスターターのためにどのパートが動くかを挙げています。たとえば データスターターのページ です。

他のビルダー

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

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

インクリメンタルビルド

build_runner は、ステップが読むすべてのファイルを記録します。入力、解決するライブラリ (とそれがインポートするもの)、グロブが見つけたファイル、pubspec.yaml、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 のように動きます。

関連項目