Spring との違い

Spring (Java) はアプリケーションの起動時に Bean を見つけます。クラスパスをスキャンしてアノテーション付きのクラスを探し、リフレクションでそのアノテーションとコンストラクターを読み、メモリー上に新しいクラスとしてプロキシを作ります。Spring for Dart はプログラミングモデル (同じ意味を持つ同じアノテーション) を保ちつつ、その発見をビルド時に移します。spring_core_dart_generator は build_runner の実行中にアノテーションを読み、オブジェクトを生成して結び付ける素の Dart コードを書き出します。このページでは、それによって何が変わり、なぜ変わり、何が同じままかを列挙します。

使う理由

Dart には、アプリが動く場所でのリフレクションがありません。dart:mirrors は Flutter、AOT コンパイルされた実行ファイル、Web では使えず、Dart はプログラムの実行中にクラスを作れません。そのため、Spring が起動時にクラスを見て知ることは、すべてプログラムのコンパイル前にわかっていなければなりません。

以下の違いのほとんどはこの一つの事実から来ています。コストになるものもあります (ビルドを実行しなければならない、ビルドはソースにあるものしか見ない)。利点になるものもあります (アプリの実行前にエラーがわかる、起動時のスキャンがない、ミニファイやツリーシェイキングに耐えるコード)。

例

両方での同じサービスです。

// Spring (Java): 起動時にクラスパスのスキャンで見つかり、リフレクションで生成される。
@Service
class Greeter {
  Greeter(@Value("${greeting.suffix:!}") String suffix, Clock clock) { ... }
}
// Spring for Dart: 同じアノテーション...
@Service()
class Greeter {
  Greeter(@Value(r'${greeting.suffix:!}') this.suffix, this.clock);
  final String suffix;
  final Clock clock;
}

...そしてビルドは、Spring がリフレクションで実行するコードを書き出します (簡略化。実際のファイルは _i1. のようなインポートのプレフィックスを使います)。

// lib/spring_gen/beans.spring.dart (生成)
BeanModule get $appBeans => BeanModule(r'appBeans', [
  BeanDefinition<Greeter>(
    name: r'greeter',
    types: const [Greeter],
    dependencies: const [
      Dependency.value(r'${greeting.suffix:!}'),
      Dependency(Clock, name: r'clock'),
    ],
    create: (r) => Greeter(
      r.value<String>(r'${greeting.suffix:!}'),
      r.dependency<Clock>(name: r'clock'),
    ),
  ),
]);

コンテキストは起動時にこのリストを読みます。値の解決、Clock Bean の検索、条件のチェック、ライフサイクルの実行は、Spring と同じく実行時に行われます。生成されるのは、発見と生成のコードだけです。

一覧

項目 Spring (Java) Spring for Dart
Bean の発見 起動時のクラスパスのスキャン トップレベル変数の @ComponentScan(): ビルドがそのファイルのディレクトリとその下をスキャンする
Bean の生成 コンストラクター、フィールド、セッターへのリフレクション 生成されたコンストラクター呼び出しとクロージャー
AOP プロキシ 起動時に作られる JDK 動的プロキシまたは CGLIB サブクラス ビルド時に生成されるプロキシクラス
フルモードの @Configuration クラス、@Lookup 起動時の CGLIB サブクラス 生成されたサブクラス
イントロスペクション (JSON、バリデーション、SpEL) 任意のクラスへのリフレクション ビルドが使われると見たものについての生成された記述
自動構成 クラスパス上の META-INF/spring/...AutoConfiguration.imports 各依存関係の lib/spring_auto_configuration.dart。パッケージ設定を通して見つける
Bean より前に必要なスターターのファクトリー クラスパス上の META-INF/spring.factories。SpringFactoriesLoader.loadFactories(type, classLoader) が読む @AutoConfigurationModule の factories: ジェネレーターが生成される springApplication にコピーする public な定数
バイナリーからモジュールを外す 不要: JVM では未使用のクラスのコストは小さい AutoConfigurationBuild: プロパティによるビルド時の判定
リソース クラスパス上のファイル 生成コードに埋め込まれる lib/resources/
--dart-define / システムプロパティ 実行時に任意のキー 生成された定数キーのリスト
設定のメタデータ アノテーションプロセッサー spring-boot-configuration-processor spring_metadata ビルダー
間違ったアノテーション 主に起動時に見つかる ビルドがソースの場所とともに見つける

発見: クラスパスの代わりにビルド時のスキャン

Spring は起動時にクラスパスのパッケージをスキャンします。ここでは、スキャンルートは @ComponentScan() を付けたトップレベル変数です。ビルドはそのファイルのディレクトリとその下のすべてのクラスをスキャンし、Bean ごとに一つの BeanDefinition を持つ BeanModule を書き出します。独自の @ComponentScan を持つサブディレクトリはそのスキャンに任されます。@ComponentScan モジュール を参照してください。

Spring のスキャンオプションは、ビルド時に評価されて動きます。includeFilters、excludeFilters (アノテーション、代入可能な型、クラス名に対する正規表現による)、useDefaultFilters、lazyInit です。FilterType.ASPECTJ と FilterType.CUSTOM は存在しません。独自のフィルターはスキャン中に実行されるコードであり、スキャンとはビルドのことだからです。

これによって得られるもの:

そのコスト:

プロキシ: 実行時に作るのではなく生成する

Spring は起動時に AOP プロキシを作ります。インターフェースには JDK 動的プロキシ、クラスには CGLIB サブクラスです。Dart は実行時にクラスを作れないため、ジェネレーターはプロキシを必要としうる Bean ごとにプロキシクラスを書き出します。実装プロキシ、または継承しかできないクラスにはサブクラスプロキシです。起動時には、コンテキストがポイントカットにどの Bean が一致するかを引き続き判断し、何にも一致しない Bean はラップされません。AOP プロキシ を参照してください。

Spring が CGLIB を使う他の場所も同じです。フルモードの @Configuration クラス (ある @Bean メソッドが別のものを呼ぶと共有の Bean を返すため) と、@Lookup メソッドを持つ Bean は、生成されたサブクラスを受け取ります。

そのコストと、ジェネレーターがそれを抑える方法:

イントロスペクション: ビルドが使われると見たものだけ

Spring の ObjectMapper、バリデーション、SpEL は任意のオブジェクトにリフレクションを使います。ここでは、それらは生成された記述 (Introspection) を読みます。プログラムを小さく保つため、クラスはアプリケーションがそれに対して行うことについてだけ記述されます。JSON として書かれるならゲッター、読まれるならコンストラクターとセッター、バリデーションされるなら制約付きのプロパティのゲッター、SpEL 式が呼びうるならメソッドです。実行されるものだけ: イントロスペクション を参照してください。

コスト: Object にキャストしてから JSON として書かれる値のように、ビルドから見えない使い方は、必要な部分のない記述を見つけることになります。それは空のオブジェクトではなく、クラス、足りない部分、修正方法を示すメッセージで失敗します。

Bad state: Book is described without its getters, but it is written out as
JSON. The build described only what it saw used, and did not see that: add
@Introspected() to Book.

クラスに @Introspected() を付けると、リフレクションと同じくすべてが残ります。

自動構成: META-INF の代わりにパッケージ設定

Spring Boot は、クラスパス上のすべての JAR から META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports を読みます。ここでは、@SpringBootApplication ライブラリのビルドが、アプリケーションが直接または間接に依存するすべてのパッケージ (pubspec.yaml ファイルから読まれるので、pub ワークスペースの兄弟パッケージは含まれません) を見て、その lib/spring_auto_configuration.dart を読みます。そこにある @AutoConfigurationModule を付けた各トップレベル変数が自動構成です。生成された springApplication はそれらを列挙します。

// lib/spring_gen/main.spring.dart (生成、簡略化)
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterFlutterAutoConfiguration,
    if (!const bool.fromEnvironment('dart.vm.product'))
      springBootStarterFlutterDebugAutoConfiguration,
    springBootStarterFlutterNavigationAutoConfiguration,
  ],
  // ...
);

リストはパッケージ順、次に名前順です。SpringApplication は起動時に、Spring Boot の AutoConfigurationSorter が @AutoConfigureOrder、@AutoConfigureBefore、@AutoConfigureAfter で行うのと同じく、order、before、after でそれをソートします。@SpringBootApplication の exclude と excludeName、プロパティ spring.autoconfigure.exclude も起動時に引き続き動きます。スターターは受け付ける spring_boot_dart のバージョンを宣言することもでき (requires:)、範囲外のバージョンはビルドを失敗させます。スターターが Bean より前に追加するもの、Spring の META-INF/spring.factories にあたるものは、そのモジュールの factories です。ジェネレーターはその定数を springApplication にコピーし、public な定数でないものはビルドを止めます。自動構成 を参照してください。

ビルド条件: 条件のビルド時版

Spring は @Conditional、@Profile、@ConditionalOnProperty を起動時に評価し、Spring for Dart も同様です。条件は Bean 定義に書き込まれ、完全な設定、プロファイル、--dart-define の値、環境変数を使って、コンテキストの起動時に判定されます。

Spring に対応するもののない追加が一つあります。JVM では、条件によって無効になる自動構成のコストは、使われない数個のクラスです。Flutter アプリでは、コンパイルに含まれたすべての行がユーザーに届けられます。そこで @AutoConfigurationModule は build: AutoConfigurationBuild('<property>') を受け取ることができ、ジェネレーターはビルド中に設定ファイルから読んだそのプロパティで判定します。

spring_boot_starter_flutter のデバッグパネルは、spring.flutter.debug.enabled でこれを使っています。プロパティはファイルからだけ読まれ、環境変数や --dart-define からは読まれません。ビルドから外されるモジュール と ビルドが読むプロパティ を参照してください。

Spring 自身のビルド時の処理であるネイティブイメージ向けの Spring AOT は、さらに先まで進みます。条件とプロファイルをビルド時に評価し、Bean の集合を固定します。Spring for Dart はそうしません。AutoConfigurationBuild を除き、条件は実行時に残るので、アプリの起動時に選ばれたプロファイルは引き続きその Bean を変えます。

リソース: クラスパスではなく埋め込み

Spring は JAR から classpath: リソースを読み込みます。Dart のプログラムにはクラスパスがなく、Web 上の Flutter アプリにはファイルシステムがありません。そこでジェネレーターは lib/resources/ のファイルを生成コードに埋め込みます。テキストはテキストとして、その他のファイルは base64 として埋め込み、1 MB を超えるファイルは警告とともにスキップします。そうすると、設定ファイルを含む resources: の場所は、Flutter のアセットを宣言することなく、すべてのプラットフォームで動きます。埋め込みリソース を参照してください。

--dart-define: 定数のキー

Java のプログラムは、実行時に任意のシステムプロパティや環境変数を名前で読みます。Web や AOT 向けにコンパイルされた Dart のプログラムは、定数のキー (const String.fromEnvironment('KEY')) でしか --dart-define の値を読めません。そこで @SpringBootApplication の出力は、アノテーションのプレースホルダー、@ConditionalOnProperty の名前、@ConfigurationProperties のフィールド、設定ファイルのキーから、アプリケーションが読みうるすべてのプロパティ名を両方の形 (shop.currency と SHOP_CURRENCY) で列挙します。

// lib/spring_gen/main.spring.dart (生成、簡略化)
dartDefines: {
  if (const bool.hasEnvironment('LOGGING_LEVEL_ROOT'))
    'LOGGING_LEVEL_ROOT': const String.fromEnvironment('LOGGING_LEVEL_ROOT'),
  // ...
},

コスト: 実行時に文字列から組み立てられたキーのように、ビルドから見えなかったキーは --dart-define で設定できません。設定ファイル、環境変数、コマンドラインでは引き続き設定できます。--dart-define キー を参照してください。

ビルド時のエラー

Spring はほとんどの間違いをコンテキストの起動時に報告します。ジェネレーターは、ビルド中にソースから見えるものをソースの場所とともに報告し、一つのビルドの独立した問題をすべてまとめて列挙します。

ビルド時のチェック を参照してください。

アプリケーション全体に依存するため、Spring と同じく起動時に行われるチェックもあります。足りない Bean や曖昧な Bean、依存の循環は、コンテキストの起動時、自分のオブジェクトが一つも生成される前に報告されます。

ソースのエラーが生成ファイルを削除することはありません。build_runner watch は最後の正常な出力を残すので、それをインポートするファイルが入力中に赤くなることはありません。エラーと生成ファイル を参照してください。

エディター向けのメタデータ

Spring Boot はアノテーションプロセッサーで META-INF/spring-configuration-metadata.json を書き出し、エディターは JAR からそれを読みます。spring_metadata ビルダーは、同種のソース (@ConfigurationProperties クラス、その /// コメントとリテラルのデフォルト、そして Bean とプロファイル) から lib/spring_gen/spring_metadata.json を書き出します。これはパッケージとともに公開されるので、エディターはアプリとそのすべての依存関係のメタデータを読めます。エディター向けのメタデータ を参照してください。

Spring に対応するもののない、ビルドが追加するもの

ジェネレーターはすでにビルド時に設定を読んでいるので、Spring には書く理由のないファイルも書き出します。