自動構成

スターターは、アプリケーションにコードを書かせることなく、それに依存するすべてのアプリケーションに Bean を追加します。そのために使うのが 自動構成モジュール です。スターターの lib/spring_auto_configuration.dart にある、@AutoConfigurationModule() を付けた BeanModule 変数です。ジェネレーターは、アプリケーションの @SpringBootApplication の出力を書き出すとき、アプリケーションが依存するすべてのパッケージでこれらのモジュールを探し、生成された springApplication に渡します。

使う理由

Spring Boot は起動時に自動構成を見つけます。クラスパスの META-INF/spring/...AutoConfiguration.imports ファイルを読むのです。Dart には実行時に読むクラスパスがなく、Flutter、Web、AOT 実行ファイルにはリフレクションもありません。そこでジェネレーターはこの手順をビルド時に行います。各依存関係の決まった名前のファイルを読み、見つけたモジュールへの素の参照を書き出します。

その結果、スターターを pubspec.yaml に追加するだけで十分ですが、スターターのモジュールが現れるにはアプリケーションを再ビルド (dart run build_runner build) する必要があります。

モジュールを宣言する (スターターの作者向け)

スターターはモジュールを lib/spring_auto_configuration.dart に置きます。ファイル名は決まっています。各モジュールは、@AutoConfigurationModule() を付けた BeanModule 型の public なトップレベル変数 です。通常、モジュールはスターター自身の lib/ の @ComponentScan から来ます。

// パッケージ `neon_cache` の lib/src/cache_beans.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'package:neon_cache/spring_gen/src/cache_beans.spring.dart';

// lib/src/ の下のすべての Bean クラスがこのモジュールに入る。
@ComponentScan()
final BeanModule neonCacheBeans = $neonCacheBeans;
// lib/src/cache_auto_configuration.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

@AutoConfiguration()
class CacheAutoConfiguration {
  @Bean()
  @ConditionalOnMissingBean() // アプリケーション自身の Cache が優先される
  Cache cache(@Value(r'${neon.cache.size:100}') int size) => InMemoryCache(size);
}
// lib/spring_auto_configuration.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'package:neon_cache/src/cache_beans.dart';

@AutoConfigurationModule(requires: '^0.7.0')
final BeanModule neonCacheAutoConfiguration = neonCacheBeans;

手書きの BeanModule(...) でもかまいません。spring_boot_starter_flutter はモジュールを手で書いています。

before、after、excludeName で使われるモジュールの名前は、その BeanModule の名前です。@ComponentScan モジュールでは、spring_auto_configuration.dart の変数が何という名前であっても、スキャン変数の名前 (上の neonCacheBeans) になります。Spring for Dart のスターターは両方に同じ名前 (springBootStarterCacheAutoConfiguration) を付けています。

@AutoConfigurationModule は次の引数を受け取り、すべて省略可能です。

引数 型 デフォルト 意味
order int 0 自動構成モジュールの中での位置。小さいものが先です (Spring Boot の @AutoConfigureOrder)。
before List<String> [] このモジュールより後に登録されるモジュール、または短い名前による @AutoConfiguration クラス。それらの条件はこのモジュールの Bean を見ます。未知の名前は無視されます。
after List<String> [] このモジュールより前に登録されるモジュール、または短い名前による @AutoConfiguration クラス。未知の名前は無視されます。
requires String? null: 任意のバージョン スターターが動作する spring_boot_dart のバージョン。pub のバージョン範囲 (^0.7.0、'>=0.7.0 <0.9.0') で書きます。ビルド時にチェックされます。
build AutoConfigurationBuild? null: 常に モジュールをビルドに含めるかどうかを、アプリケーションのプロパティに決めさせます。ビルドから外されるモジュール を参照してください。
platform ModulePlatform? null: どこでも native、web、server のいずれか: モジュールはそのプラットフォームの定数の下に列挙され、ほかのプラットフォームのコンパイラーはそれを落とします。一つのプラットフォームだけのモジュール を参照してください。
factories List<Object> [] Bean が一つも存在しないうちにアプリケーションが型で見つける定数。生成されるアプリケーションにコピーされます。ファクトリー を参照してください。

アプリケーションがモジュールを見つける方法

ジェネレーターはアプリケーション (main に @SpringBootApplication() を持つライブラリ) を組み立てるとき、次のことを行います。

  1. 到達可能なパッケージを列挙します。 アプリケーションの pubspec.yaml を読みます。その dependencies (エントリーポイントが example/ や tool/ のように lib/ と bin/ の外にある場合は dev_dependencies も) です。次に、それらの各パッケージの pubspec.yaml の dependencies を読み、これを繰り返します。pub ワークスペースではパッケージ設定にワークスペースのすべてのメンバーが列挙されますが、数えられるのはこの方法で到達したパッケージだけなので、アプリが依存していない兄弟パッケージのモジュールを受け取ることはありません。pubspec.yaml を読めない場合、ジェネレーターはモジュールを見落とすより、設定のすべてのパッケージを対象にします。
  2. 到達可能な各パッケージの lib/spring_auto_configuration.dart を読みます (ある場合)。アプリケーション自身のパッケージはスキップされますが、example/ の下のエントリーポイントは例外です。スターターのサンプルは、それに依存する任意のアプリケーションと同じく、スターター自身のモジュールを使います。
  3. @AutoConfigurationModule を付けたすべてのトップレベル変数を取ります。 それぞれについて requires をチェックし (下記)、build を判定します (ビルドから外されるモジュール を参照)。
  4. パッケージ名、次に変数名でソートします。そのため出力はどのマシンでも同じです。
  5. それらを springApplication に書き込みます。order、before、after、factories のいずれかを設定しているモジュールにはその値も書きます。

インポートのプレフィックス (_i63.) を外して簡略化した出力です。

// bin/spring_gen/main.spring.dart (生成)
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    neonCacheAutoConfiguration,                // パッケージ neon_cache
    springBootAutoConfiguration,               // パッケージ spring_boot_dart
    springBootStarterLoggingAutoConfiguration, // パッケージ spring_boot_starter_logging
  ],
  autoConfigurationMetadata: {
    neonCacheAutoConfiguration: const AutoConfigurationModule(
      order: 5,
      after: ['springBootAutoConfiguration'],
    ),
  },
  // dartDefines, fingerprint (デバッグとプロファイルのビルド)
);

order、before、after、factories のないモジュールは autoConfigurationMetadata にエントリーを持ちません。どのモジュールもそれらを設定していなければ、マップは省略されます。

登録の順序

ジェネレーターが書くリストは、パッケージと名前でソートされているだけです。モジュールが 登録される 順序は、Spring Boot の AutoConfigurationSorter と同じく、起動のたびに SpringApplication が決めます。

  1. order (エントリーがなければ 0)、次に名前の順。
  2. その後、before と after がモジュールを移動させます。それらの間に循環があると起動が失敗します。

自動構成モジュールはアプリケーション自身の Bean の後に登録されるので、スターターの @ConditionalOnMissingBean はアプリケーションの Bean を見て身を引きます。

requires のチェック

requires は、スターターが想定している spring_boot_dart のバージョンの範囲です。ジェネレーターはそれを使用中のバージョン (spring_boot_dart の定数 springBootVersion) と比べ、一致しなければ、後で生成コードや実行時のコードのエラーで失敗する代わりに、ビルドを止めます。これは Java で Spring Boot の BOM や Spring Cloud の互換性検証機能が担う仕事です。

チェックは見つかったすべてのモジュールに対して行われ、ビルド条件で外されるモジュールも対象です。

状況 ビルドエラー
範囲が使用中のバージョンを許さない Incompatible starter: neon_cache requires spring_boot_dart ^0.8.0, but 0.7.1 is used. に続けて Upgrade spring_boot_dart to a version in ^0.8.0, or use a version of neon_cache made for spring_boot_dart 0.7.1 (see its CHANGELOG / pub.dev versions).
範囲を解析できない neon_cache: invalid requires 'not a range' (...).
spring_boot_dart がアプリケーションの依存関係にない neon_cache requires spring_boot_dart ^0.7.0, but spring_boot_dart is not a dependency of this application.

エラーはスターターのモジュール変数を指します。

ファクトリー

@AutoConfigurationModule の factories は、Bean が一つも存在しないうちにアプリケーションが型で見つける定数です (ファクトリー を参照)。Spring Boot は、そうしたエントリーを実行時にクラスパス上の META-INF/spring.factories から SpringFactoriesLoader.loadFactories(type, classLoader) で読みます。Dart にはスキャンするクラスパスがないため、ジェネレーターは各ファクトリーを、書かれたとおりの定数として、それ自身のパッケージからインポートして、生成される springApplication の autoConfigurationMetadata にコピーします。

// spring_boot_starter_flutter_material の lib/spring_auto_configuration.dart
@AutoConfigurationModule(factories: [MaterialThemeDesign()])
final BeanModule springBootStarterFlutterMaterialAutoConfiguration = BeanModule(/* ... */);
// アプリの lib/spring_gen/main.spring.dart (生成されたもの。インポートのプレフィックスは省略)
autoConfigurationMetadata: {
  springBootStarterFlutterMaterialAutoConfiguration: const AutoConfigurationModule(
    factories: [MaterialThemeDesign()],
  ),
},

ファクトリーは、生成されるファイルが名前で指せる public な定数でなければなりません。

ファクトリー 書き出される形
リテラルの引数 (null、bool、数値、テキスト)、またはそれ自体がこうした定数である引数による const コンストラクターの呼び出し 同じ呼び出し: MaterialThemeDesign()
名前付きコンストラクターの呼び出し 同じ呼び出し: OceanThemeDesign.dark()
トップレベルの const 変数 その名前: oceanThemeDesign
static const フィールド クラスとフィールド: OceanThemeDesign.standard

それ以外はビルドを止めます: private なクラスや定数、パッケージの lib/ の外で宣言されたもの、こうした定数ではない値。エラーは、ファクトリーに何が使えるかを示します: AutoConfigurationModule.factories: OceanThemeDesign cannot be written into the generated application. A factory is a public constant: a const constructor call with literal arguments, a top-level const variable or a static const field.

アプリケーションがスターターのファクトリーを持つのは、再び生成されてからです。ファクトリーを持つスターター (Flutter のデザインのスターター、spring_boot_starter_flutter_material と spring_boot_starter_flutter_cupertino はそれぞれ一つ持ちます) を追加したら、build_runner を実行してください。

exclude と excludeName

アプリケーションは @SpringBootApplication の引数で自動構成を無効にします。

// bin/main.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'package:neon_cache/neon_cache.dart'; // CacheAutoConfiguration をエクスポートする

import 'spring_gen/main.spring.dart';

@SpringBootApplication(
  // 型による @AutoConfiguration クラス。
  exclude: [CacheAutoConfiguration],
  // BeanModule の名前によるモジュール全体。
  excludeName: ['springBootStarterCacheAutoConfiguration'],
)
void main(List<String> args) => runApplication(args);

ジェネレーターは両方のリストをそのまま引き渡します。

// 生成
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [/* ... */],
  exclude: [CacheAutoConfiguration],
  excludeName: ['springBootStarterCacheAutoConfiguration'],
  // ...
);

SpringApplication は起動のたびに、プロパティ spring.autoconfigure.exclude とともにそれらを適用します。

除外は実行時に働きます。除外されたモジュールのコードも、アプリにはコンパイルされます。モジュールのコードをアプリから外すには、スターターが ビルド条件 を宣言する必要があります。

ビルドから外されるモジュール

スターターは、モジュールをそもそもアプリに含めるかどうかを、ビルド時にアプリケーションに決めさせることができます。

@AutoConfigurationModule(
  build: AutoConfigurationBuild('spring.flutter.debug.enabled'),
)
final BeanModule springBootStarterFlutterDebugAutoConfiguration = BeanModule(/* ... */);

プロパティが true ならモジュールは上記のように列挙され、false なら列挙されず、生成コードに痕跡を残しません。設定されていなければ if (!const bool.fromEnvironment('dart.vm.product')) の下に列挙されるので、リリースビルドではコンパイル時に取り除かれます。詳しくは ビルドから外されるモジュール にあります。

一つのプラットフォームだけのモジュール

platform: ModulePlatform.native を持つモジュールは if (const bool.fromEnvironment('dart.library.io')) の下に、ModulePlatform.web を持つモジュールは if (const bool.fromEnvironment('dart.library.js_interop')) の下に列挙されます。もう一方のプラットフォームのコンパイラーは定数 false を見て、モジュールを、それだけが到達するすべてのものと一緒に落とします。同じ生成ファイルがサーバーのモジュールを列挙していても、ブラウザービルドはサーバーのコードを持ちません。Web スターター、セキュリティスターター、Actuator スターター、WebSocket スターターのサーバー側の半分が native です。完全な表は 一つのプラットフォームだけのモジュール にあります。 ModulePlatform.server を持つモジュール (アプリに入れてはならないコード。Supabase スターターの管理 API など) は if (const bool.fromEnvironment('dart.library.io') && !const bool.fromEnvironment('dart.library.ui')) の下に列挙されるので、Flutter アプリもそれを落とします。

関連項目