自動構成
スターターは、アプリケーションにコードを書かせることなく、それに依存するすべてのアプリケーションに 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() を持つライブラリ) を組み立てるとき、次のことを行います。
- 到達可能なパッケージを列挙します。 アプリケーションの
pubspec.yamlを読みます。そのdependencies(エントリーポイントがexample/やtool/のようにlib/とbin/の外にある場合はdev_dependenciesも) です。次に、それらの各パッケージのpubspec.yamlのdependenciesを読み、これを繰り返します。pub ワークスペースではパッケージ設定にワークスペースのすべてのメンバーが列挙されますが、数えられるのはこの方法で到達したパッケージだけなので、アプリが依存していない兄弟パッケージのモジュールを受け取ることはありません。pubspec.yamlを読めない場合、ジェネレーターはモジュールを見落とすより、設定のすべてのパッケージを対象にします。 - 到達可能な各パッケージの
lib/spring_auto_configuration.dartを読みます (ある場合)。アプリケーション自身のパッケージはスキップされますが、example/の下のエントリーポイントは例外です。スターターのサンプルは、それに依存する任意のアプリケーションと同じく、スターター自身のモジュールを使います。 @AutoConfigurationModuleを付けたすべてのトップレベル変数を取ります。 それぞれについてrequiresをチェックし (下記)、buildを判定します (ビルドから外されるモジュール を参照)。- パッケージ名、次に変数名でソートします。そのため出力はどのマシンでも同じです。
- それらを
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 が決めます。
order(エントリーがなければ0)、次に名前の順。- その後、
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 とともにそれらを適用します。
excludeNameは、BeanModuleの名前でモジュールに一致するか (スターターが追加するすべてを取り除きます)、短い名前または完全な名前で@AutoConfigurationクラスに一致します。未知の名前は無視されるので、スターターを取り除いた後も名前を残しておけます。excludeは@AutoConfigurationクラスを指定します。自動構成クラスでない型は起動を失敗させます。
除外は実行時に働きます。除外されたモジュールのコードも、アプリにはコンパイルされます。モジュールのコードをアプリから外すには、スターターが ビルド条件 を宣言する必要があります。
ビルドから外されるモジュール
スターターは、モジュールをそもそもアプリに含めるかどうかを、ビルド時にアプリケーションに決めさせることができます。
@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 アプリもそれを落とします。