自動構成とスターター
スターターとは、出来上がった Bean を持ち込むライブラリです。pubspec.yaml に追加して build_runner を実行すれば、自分でコードを書かなくてもその機能が使えます。スターターはそれらを自動構成として提供します。アプリケーション自身の Bean の後に登録され、条件 で守られているため、自分の Bean が常に優先されます。
使う理由
Web サーバー、キャッシュ、ロギングの設定には、正しく結び付けた十数個の Bean が必要です。それをアプリケーションごとに書くのは繰り返しが多く、間違いやすい作業です。自動構成なら、ライブラリがそれを一度だけ書き、各アプリケーションは必要なものだけを上書きします。独自の Cache Bean を宣言すれば、スターターの @ConditionalOnMissingBean(Cache) が身を引きます。
例
スターター neon_cache:
// パッケージ neon_cache の lib/spring_auto_configuration.dart (ファイル名は固定)
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'spring_gen/src/cache.spring.dart';
@AutoConfigurationModule(requires: '^0.7.0')
final BeanModule neonCacheAutoConfiguration = $neonCacheBeans;
// neon_cache の lib/src/cache.dart
@AutoConfiguration()
class CacheAutoConfiguration {
@Bean()
@ConditionalOnMissingBean(Cache) // アプリケーション自身の Cache が優先される
@ConditionalOnProperty('neon.cache.enabled', matchIfMissing: true)
Cache cache(@Value(r'${neon.cache.size:100}') int size) => InMemoryCache(size);
}
neon_cache に依存するアプリケーションは、コードなしで Cache Bean を得ます。独自のものを宣言するアプリケーションは、自分のものだけを得ます。
// アプリケーションの Bean: スターターの cache() は登録されない。
@Bean()
Cache cache() => RedisCache();
スターターの見つけ方
@SpringBootApplication() を持つアプリケーションをビルドすると、ジェネレーターは依存関係グラフのすべてのパッケージ (直接のものと推移的なもの) をたどり、lib/spring_auto_configuration.dart があればそれを読み、アノテーションの付いたモジュールを生成される springApplication に列挙します。
// アプリケーションの bin/spring_gen/main.spring.dart (生成されたもの)
SpringApplication get springApplication => SpringApplication(
[$application],
autoConfigurations: [
neonCacheAutoConfiguration, // neon_cache で見つかったもの
springBootAutoConfiguration, // spring_boot_dart
],
// スターターが order、before、after、factories を設定している場合のみ
autoConfigurationMetadata: {
neonCacheAutoConfiguration: AutoConfigurationModule(order: 10),
},
);
- 検出は、起動時にクラスパスをスキャンするのではなく、ビルド時に行われます。スターターを追加したら、
build_runnerを再実行してください。 - モジュールを検出するのは
@SpringBootApplicationのアプリケーションだけです。コンテキストを手で生成するアプリケーションは、モジュールを自分で列挙します。
@AutoConfigurationModule
lib/spring_auto_configuration.dart の public なトップレベルの BeanModule 変数に付けます。
| パラメーター | デフォルト | 意味 |
|---|---|---|
order |
0 |
モジュール間での位置。小さいものが先 (Spring Boot の @AutoConfigureOrder) |
before |
[] |
このモジュールの後に登録しなければならないモジュール、または短い名前で指定した @AutoConfiguration クラス |
after |
[] |
このモジュールの前に登録しなければならないモジュールまたはクラス: ['springBootAutoConfiguration'] |
requires |
null: 任意 |
スターターが動作する spring_boot_dart のバージョン。pub の範囲で指定する (^0.7.0)。一致しないとビルドが止まる (バージョン を参照) |
build |
null: 常に |
AutoConfigurationBuild: アプリケーションの設定のプロパティが、そもそもモジュールをビルドに含めるかどうかを決める |
platform |
null: どこでも |
ModulePlatform: native、web、server のいずれか。ほかのプラットフォームでは、コンパイラーがモジュールと、そのモジュールだけが到達するすべてを取り除く |
factories |
[] |
Bean が一つも存在しないうちに、アプリケーションが型で見つける定数。ファクトリー を参照 |
@AutoConfiguration() はスターターの構成クラスを示します。@Configuration の一種で、その @Bean メソッドは自動構成として登録されます。
登録の順序
- 最初にアプリケーション自身のクラス。
- 自動構成モジュール。Spring Boot の
AutoConfigurationSorterと同じく並べ替えます。orderで並べ、同じ順序のモジュールは名前で並べ、その後beforeとafterで移動します。循環があるとAutoConfigure cycle detected between ...で起動が止まります。不明な名前は無視されます。
@AutoConfigurationModule(
order: 10,
after: ['springBootAutoConfiguration'], // モジュールまたは @AutoConfiguration クラス
before: ['neonMetricsAutoConfiguration'],
)
final BeanModule neonCacheAutoConfiguration = $neonCacheBeans;
Bean の条件はその順序でクラスごとに判断されるため、@ConditionalOnMissingBean は、アプリケーションが宣言したもの (@Import したレジストラーの Bean を含む) を認識します。条件 を参照してください。
自動構成を除外する
スターターの Bean が不要な場合は、その条件が実行される前に除外します。
@SpringBootApplication(
exclude: [CacheAutoConfiguration], // クラスで
excludeName: ['springBootStarterCacheAutoConfiguration'], // モジュール名またはクラス名で
)
void main(List<String> args) => runApplication(args);
# 実行時にアノテーションに追加される: カンマ区切りのリストまたは YAML のリスト
spring.autoconfigure.exclude=JacksonAutoConfiguration,CacheAutoConfiguration
excludeのTypeは単純名で比較されるため、別々のライブラリにある同じ名前のクラスはまとめて除外されます。excludeNameとプロパティは、モジュール名 (springBootAutoConfiguration)、短いクラス名、またはpackage:x/src/y.dart#CacheAutoConfigurationを受け取ります。- クラスを除外すると、その Bean、インポートしたレジストラーとセレクター、条件付きの
@PropertySourceが取り除かれます。それが@Importする構成クラスは残ります。モジュールを除外すると、そのすべてが取り除かれます。 - 自動構成でない型を除外すると起動が止まります。不明な名前は無視されます。
組み込みのものは JacksonAutoConfiguration、ValidationAutoConfiguration、MessageSourceAutoConfiguration、LifecycleAutoConfiguration、ApplicationAvailabilityAutoConfiguration、JsonSchemaAutoConfiguration、ObservationAutoConfiguration です (組み込みの Bean を参照)。
ビルドから除かれるモジュール
開発者だけが使う機能 (デバッグパネル) は、リリースに含めるべきではありません。build: を使うと、ジェネレーターの実行時に、アプリケーションの設定がそもそもモジュールをアプリケーションに含めるかどうかを決められます。
@AutoConfigurationModule(
build: AutoConfigurationBuild('spring.flutter.debug.enabled'),
)
final BeanModule debugAutoConfiguration = BeanModule(/* ... */);
プロパティは、build_runner の実行時に、プロファイルなしの application.yml と application.properties から読まれます。
| プロパティ | モジュール |
|---|---|
true |
すべてのビルドに含まれる |
false |
どのビルドにも含まれない: コードはまったくない |
| 未設定 | whenMissing |
whenMissing は BuildInclusion です。
| 値 | 意味 |
|---|---|
notInRelease (デフォルト) |
debug と profile のビルドに含まれる。リリースではコンパイル時に取り除かれる (dart.vm.product) |
always |
すべてのビルドに含まれる |
never |
どのビルドにも含まれない |
ビルドが条件付きで含めるモジュールも、その order、before、after を保ちます。ビルドはプロファイルのファイルを読まないため、プロファイルのファイルでだけ設定されたビルドプロパティには警告が出ます。ビルドから除かれるモジュール を参照してください。
一つのプラットフォームだけのモジュール
一つのプラットフォームでしか動かないコードがあります。Web サーバーには dart:io が必要ですが、ブラウザーにはありません。dart:js_interop を通してブラウザーに到達するコードは、サーバーでは動きません。platform: は、モジュールをそのコードが動く場所に限定します。
@AutoConfigurationModule(platform: ModulePlatform.native)
final BeanModule neonServerAutoConfiguration = BeanModule(/* ... */);
ModulePlatform |
モジュールがある場所 |
|---|---|
native |
dart:io が存在する場所: Dart VM、AOT 実行ファイル、スマートフォンやデスクトップの Flutter アプリ。ブラウザーは含まない |
web |
ブラウザー。JavaScript または WebAssembly にコンパイルされたもの |
server |
Dart VM または AOT 実行ファイル: dart:io が存在し、Flutter の dart:ui は存在しない。Flutter アプリではなく、ブラウザーでもない。アプリに入れてはならないコード、つまり誰でも読めるものに入れてはならないコードのため: 秘密鍵が必要な API など |
| 指定なし | どこでも |
生成されるアプリケーションは、そうしたモジュールを、コンパイラーが知っている定数 (dart.library.io、dart.library.js_interop、dart.library.ui) のもとに列挙します。ほかのプラットフォームではその定数は false で、コンパイラーはモジュールと、そのモジュールだけが到達するすべてを取り除きます。そのため、依存関係が spring_boot_starter_web を持ち込む Flutter の Web アプリはサーバーのコードを持たず、手作業で除外するものもありません。
- 実行時の条件ではありません。もう一方のプラットフォームでは、モジュールの Bean はスキップされるのではなく、プログラムの中にありません。
platform:はbuild:と組み合わせられます。両方がそう言うとき、モジュールは含まれます。-DSPRING_ALL_PLATFORMS=trueを付けてコンパイルしたプログラムは、プラットフォームに関係なくすべてのモジュールを残します。意図してサーバーのコードを Node 上の JavaScript として動かす場合のためです。- モジュール全体に使ってください。どこにでもあるモジュールの中でプラットフォームによって異なる Bean は、ほとんどのスターターがしているように、条件付きインポートで選びます。
- ファミリーのどのモジュールに指定があるかは、一つのプラットフォームだけのモジュール に列挙されています。
Spring に対応するものはありません。JVM のアプリケーションは一つのプラットフォームで動きます。
ファクトリー
Bean が存在するのは、コンテキストが作られてからです。スターターが追加するもののうち、いくつかはそれより前、環境が準備されている間や Flutter アプリがスプラッシュを表示している間に動かなければなりません。Flutter のテーマを読むときに使うデザインライブラリーがその一つです。テーマはスプラッシュのために、Bean が一つも存在しないうちに読まれます。スターターは、そうしたものを定数として factories に列挙します。
@AutoConfigurationModule(factories: [OceanThemeDesign()])
final BeanModule oceanAutoConfiguration = $oceanBeans;
それを必要とするコードは、型を指定して求めます。
// ApplicationEnvironmentPreparedEvent のリスナーの中で
final designs = event.springApplication.factories.load<ThemeDesign>();
SpringApplication.factoriesは、アプリケーションのすべてのモジュールのファクトリーを持つSpringFactoriesです。load<T>()は型Tのものを返します。Orderedを実装しているものはその順に、そうでなければモジュールの順に並びます。どのスターターも持っていなければ空です。- コンテキストは、同じオブジェクトを
springFactoriesBean として持ちます。 - ファクトリーはそれぞれ public な定数です: リテラルの引数による
constコンストラクターの呼び出し (名前付きコンストラクターも可)、トップレベルのconst変数、またはstatic constフィールド。ジェネレーターはそれを生成されるspringApplicationにコピーします。それ以外の形のファクトリーは、説明とともにビルドを止めます。 - アプリケーションがスターターのファクトリーを得るのは、生成されたときです。ファクトリーを持つスターターを追加したら、
build_runnerを再実行してください。
ファクトリーは、Bean より前に存在しなければならないものにだけ使ってください。それ以外はすべて Bean のままにします。Bean ならアプリケーションが置き換えられます。
独自のスターターを書く
どのパッケージもスターターになれます。
- モジュールを宣言します。
lib/spring_auto_configuration.dartに、@AutoConfigurationModuleを付けた public なトップレベルのBeanModule変数を置きます。 - Bean を記述します。 ジェネレーターで (
@AutoConfiguration、@Bean、条件。スターターの@ComponentScanでスキャンされる)、または手書きのBeanDefinitionで記述します。手書きの定義は、その Bean の条件が順序どおりに判断されるよう、source(library#Class) かfactoryMethodNameを必要とします。どちらもないものは即座に判断されます。 - 生成されたコードを公開します。 ジェネレーターはビルド中のパッケージにだけファイルを書き、依存関係には決して書きません。スターターで
dart run build_runner buildを実行し、その*.spring.dartファイルを公開してください。 - テストします。
spring_boot_starter_testのApplicationContextRunnerで、単独の場合、スターターを身を引かせるアプリケーションの Bean がある場合、スターターを無効にするプロパティがある場合をテストします。
// test/cache_auto_configuration_test.dart
test('backs off when the application has a Cache', () {
const ApplicationContextRunner()
.withAutoConfiguration(neonCacheAutoConfiguration)
.withBean<Cache>(RedisCache.new)
.run((context) {
expect(context, hasSingleBean<Cache>());
expect(context.getBean<Cache>(), isA<RedisCache>());
});
});
アプリケーションが他のスターターと一緒に解決できるよう、スターターのサードパーティーの制約は広く保ってください (dio: '>=5.0.0 <7.0.0')。
ファミリーのスターター
| スターター | 依存関係を追加すると得られるもの |
|---|---|
spring_boot_starter_logging |
パターン付きのコンソール出力、ロールオーバー付きのログファイル、logging.* プロパティ、LogBuffer |
spring_boot_starter_web |
HTTP サーバー: @RestController、JSON ボディ、@Valid、ProblemDetail のエラー、SSE、フィルター、CORS |
spring_boot_starter_security |
セキュリティフィルターチェーン、HTTP Basic、フォームログイン、セッション、CSRF、JWT リソースサーバー |
spring_boot_starter_feign |
アノテーションを付けたインターフェースからの HTTP クライアント |
spring_boot_starter_websocket |
WebSocket のクライアントとエンドポイント |
spring_boot_starter_cache |
@Cacheable、@CachePut、@CacheEvict、CacheManager |
spring_boot_starter_scheduling |
@Scheduled メソッドと TaskScheduler |
spring_boot_starter_data |
リポジトリと SQL データベース |
spring_boot_starter_actuator |
ヘルス、情報、メトリクス、その他の管理エンドポイント |
spring_boot_starter_flutter |
Flutter アプリ: SpringApplicationWidget、ウィジェット内の Bean、テーマ、プラットフォームのプロファイル |
spring_boot_starter_test (dev) |
springBootTest、ApplicationContextRunner、Bean のオーバーライド、captureLogs |
Spring (Java) との対応
# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.neon.cache.CacheAutoConfiguration
@AutoConfiguration(after = JacksonAutoConfiguration.class)
@AutoConfigureOrder(10)
class CacheAutoConfiguration { ... }
違い:
- 単位はクラスではなくモジュールです。
order、before、afterは@AutoConfigurationModuleにあり、そこではクラスを短い名前で指定できます。 - スターターはビルド時に検出されます。新しいスターターには再ビルドが必要です。
excludeのTypeは単純名で比較されます。build:(リリースから除かれるモジュール) に対応するものは Spring にはありません。factoriesは Spring のMETA-INF/spring.factoriesのエントリーにあたり、Spring ではSpringFactoriesLoader.loadFactories(type, classLoader)がクラスパス上からそれを見つけます。Dart にはスキャンするクラスパスがないため、ジェネレーターが定数を生成されるアプリケーションにコピーします。