自動構成とスターター

スターターとは、出来上がった 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),
      },
    );

@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 メソッドは自動構成として登録されます。

登録の順序

  1. 最初にアプリケーション自身のクラス。
  2. 自動構成モジュール。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

組み込みのものは 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 アプリはサーバーのコードを持たず、手作業で除外するものもありません。

Spring に対応するものはありません。JVM のアプリケーションは一つのプラットフォームで動きます。

ファクトリー

Bean が存在するのは、コンテキストが作られてからです。スターターが追加するもののうち、いくつかはそれより前、環境が準備されている間や Flutter アプリがスプラッシュを表示している間に動かなければなりません。Flutter のテーマを読むときに使うデザインライブラリーがその一つです。テーマはスプラッシュのために、Bean が一つも存在しないうちに読まれます。スターターは、そうしたものを定数として factories に列挙します。

@AutoConfigurationModule(factories: [OceanThemeDesign()])
final BeanModule oceanAutoConfiguration = $oceanBeans;

それを必要とするコードは、型を指定して求めます。

// ApplicationEnvironmentPreparedEvent のリスナーの中で
final designs = event.springApplication.factories.load<ThemeDesign>();

ファクトリーは、Bean より前に存在しなければならないものにだけ使ってください。それ以外はすべて Bean のままにします。Bean ならアプリケーションが置き換えられます。

独自のスターターを書く

どのパッケージもスターターになれます。

  1. モジュールを宣言します。 lib/spring_auto_configuration.dart に、@AutoConfigurationModule を付けた public なトップレベルの BeanModule 変数を置きます。
  2. Bean を記述します。 ジェネレーターで (@AutoConfiguration、@Bean、条件。スターターの @ComponentScan でスキャンされる)、または手書きの BeanDefinition で記述します。手書きの定義は、その Bean の条件が順序どおりに判断されるよう、source (library#Class) か factoryMethodName を必要とします。どちらもないものは即座に判断されます。
  3. 生成されたコードを公開します。 ジェネレーターはビルド中のパッケージにだけファイルを書き、依存関係には決して書きません。スターターで dart run build_runner build を実行し、その *.spring.dart ファイルを公開してください。
  4. テストします。 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 { ... }

違い:

関連項目