SpringApplication

SpringApplication はアプリケーションを起動します。設定を読み、スターターの Bean とともに Bean を生成し、起動時のタスクを実行します。その順序は決まっており、文書化されています。Spring Boot の SpringApplication に当たります。

ほとんどのアプリケーションは自分でこれを生成しません。main に @SpringBootApplication() を付けると、ジェネレーターが springApplication ゲッターと、それを呼ぶ関数を書き出します。

使う理由

Bean で組み立てたプログラムには、毎回同じ手順が必要です。プロパティを集め、ログレベルを設定し、アプリケーションの Bean とライブラリの Bean でコンテキストを生成し、起動の失敗を読みやすく報告し、起動時の処理を実行します。手で書くと 1 ページ分のコードになり、どのプロジェクトも少しずつ間違えます。SpringApplication はそれを Spring Boot の順序で一度だけ行うため、スターターやテストはそれを当てにできます。

例

// bin/main.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

import 'spring_gen/main.spring.dart';

@SpringBootApplication()
void main(List<String> args) => runApplication(args);

生成されるファイルには、特に次のものが含まれます。

// bin/spring_gen/main.spring.dart (生成されたもの)
SpringApplication get springApplication => SpringApplication(
      [$application],                      // パッケージのすべての Bean
      autoConfigurations: [                // 依存関係の中で見つかったもの
        springBootStarterLoggingAutoConfiguration,
        springBootAutoConfiguration,
      ],
      dartDefines: {...},                  // 指定された --dart-define の値
      fingerprint: ...,                    // ホットリロード用。デバッグとプロファイルのビルドだけ
    );

ConfigurableApplicationContext runApplication(List<String> args) => ...;
Future<ConfigurableApplicationContext> runApplicationAsync(List<String> args) => ...;
// main.spring.debug.dart (デバッグとプロファイルのビルドだけ):
ConfigurableApplicationContext reloadApplication(ConfigurableApplicationContext context, {bool runners = true}) => ...;

何かを変えるには、ゲッターを使います。

// Bean が存在する前に起こるイベントのリスナー。
@SpringBootApplication()
void main(List<String> args) => (springApplication
      ..addListener<ApplicationEnvironmentPreparedEvent>(
        (event) => print(event.environment.activeProfiles),
      ))
    .run(args);

@SpringBootApplication

パラメーター 型 意味
exclude List<Type> 適用しない自動構成クラス。Type は単純名で比較される
excludeName List<String> 適用しない自動構成クラスまたはモジュールを名前で指定する ('JacksonAutoConfiguration'、'springBootAutoConfiguration'、'package:x/src/y.dart#CacheAutoConfiguration')

bin/ のトップレベルの main 関数 (Flutter では lib/main.dart) に付けます。パッケージごとに一つです。自動構成 と ジェネレーター: @SpringBootApplication を参照してください。

起動の手順

run(args) は次のことを順に行います。

  1. 開始。 ApplicationStartingEvent を発行します。コマンドライン引数、--dart-define の値、OS の環境変数、run(properties:)、デフォルトプロパティをプロパティソースとして追加し、${random.*} も追加します。
  2. Environment。 早期の EnvironmentPostProcessor (SPRING_APPLICATION_JSON) を実行し、設定ファイル (ロケーション、プロファイル、インポート) を読み、その他のポストプロセッサー (名前が変わったプロパティ のチェック) を実行してから、ApplicationEnvironmentPreparedEvent を発行します。
  3. ロギング。 logging.level.* を SpringLog に適用し (ログレベル を参照)、バナーを出力します。
  4. コンテキスト。 アプリケーションのモジュールから、続いて自動構成をその順序でコンテキストを生成します。これにより、スターターの @ConditionalOnMissingBean はアプリケーションの Bean を認識できます。ApplicationArguments を Bean として登録し、@ConfigurationProperties のバインドを登録します。initializers を実行し、ApplicationContextInitializedEvent と ApplicationPreparedEvent を発行します。
  5. Bean。 コンテキストをリフレッシュします。すべてのシングルトンが (遅延でない限り) 生成され、ContextRefreshedEvent が発行されます。
  6. 待機。 AsyncStartup を実装する Bean (ポートをバインドする Web サーバー) を待ちます。どれかが失敗すると起動が失敗します。ランナーも ApplicationReadyEvent もありません。
  7. 起動完了。 Started neon-books in 0.07 seconds をログに出し、ApplicationStartedEvent と LivenessState.correct を発行します。
  8. ランナー。 ApplicationRunner と CommandLineRunner の Bean を順に呼びます (ランナー を参照)。
  9. 準備完了。 ApplicationReadyEvent と ReadinessState.acceptingTraffic を発行します。

いずれかの手順が失敗すると、ApplicationFailedEvent が発行され、APPLICATION FAILED TO START のレポートがログに出され (失敗レポート を参照)、エラーが再スローされます。

run と runAsync

呼び出し 設定ファイル 戻るタイミング 用途
runApplication(args) / springApplication.run(args) 同期的に読む 同期部分が終わるとすぐ。Future を返すランナーはその後も続く Dart VM 上のサーバーとツール
runApplicationAsync(args) / springApplication.runAsync(args) 非同期に読む (Flutter のアセット、HTTP のインポート) Spring Boot の run と同じく、最後のランナーの後 Flutter、HTTP の設定、起動を待つ main

runAsync は Bean も refreshAsync() で生成するため、非同期の @PostConstruct メソッドはランナーの開始前に待たれます。

どちらも、テストやツール向けの同じ名前付きパラメーターを受け取ります。

パラメーター 意味
systemEnvironment OS の環境変数を置き換える
properties コマンドラインを含む他のすべてのソースより優先されるプロパティ
additionalProfiles この起動で有効にするプロファイル。アプリケーション自身の additionalProfiles の後に追加される
hotReload 現在のコードでのアプリケーション (生成される関数は () => springApplication を渡す)。ホットリロード 用、および同じアプリケーションを別の isolate で起動するため

hotReload があると、コンテキストは ApplicationLaunch Bean (springApplicationLaunch) を持ちます。アプリケーションがどのように起動されたかを、引数、プロパティ、プロファイルとともに表し、同じものを再び起動できるようにします。Web サーバーの isolate のプール は、その各 isolate をこれで起動します (ApplicationLaunch.start)。生成された runApplication または runApplicationAsync で起動したアプリケーションはこの Bean を持ちます。素の springApplication.run(args) で起動したものは持たず、そのサーバーは isolate を追加できません。hotReload が返すものは他の isolate に渡るので、その周囲のものを何も使ってはなりません。

コンストラクター

ジェネレーターは modules、autoConfigurations、autoConfigurationMetadata、exclude、excludeName、dartDefines、fingerprint を埋めます。その他のパラメーターは、アプリケーションを自分で生成するコードのためのものです。

パラメーター デフォルト 意味
modules 必須 アプリケーション自身の Bean モジュール。最初に登録される
autoConfigurations [] スターターのモジュール。その後に、自動構成の順序で登録される
autoConfigurationMetadata {} 各モジュールの @AutoConfigurationModule: order、before、after、factories
exclude、excludeName [] 適用しない自動構成
registerShutdownHook false SIGINT または SIGTERM でコンテキストを閉じる。spring.main.register-shutdown-hook が優先される (シャットダウン を参照)
initializers [] Bean の生成前に Ordered の順で実行される ApplicationContextInitializer
failureAnalyzers [] 起動が失敗したときに最初に問い合わせる。Bean が存在する前にも使われる
listeners [] すべての起動時イベントのリスナー。addListener と addListeners もある
defaultProperties {} 最も優先度の低いプロパティソース。setDefaultProperties もある
additionalProfiles [] 常に有効なプロファイル。設定されたものより前に置かれる
environmentPostProcessors [] Bean が存在する前に Environment を変更するコード
addressResolvers [] 設定によるダウンロード (テーマ、画像) のために、組み込みのものより先に問い合わせる RemoteAddressResolver。コンテキストはこのチェーンを remoteAddresses Bean として持つ
applicationStartup ApplicationStartup.none 起動の各段階を記録する (spring.boot.application.starting、...environment-prepared、...context、Bean ごとに一つの spring.beans.instantiate)。計測するには BufferingApplicationStartup を渡す
dartDefines {} --dart-define の値。コマンドラインより下位のプロパティソース
banner なし バナーファイルがないときに出力するバナー
bannerMode BannerMode.console バナーの出力先。spring.main.banner-mode が優先される
resourceLoader DefaultResourceLoader 設定ファイル、バナー、resources: を読む。他のロケーションには ProtocolResolver を持つものを渡す
fingerprint なし 生成されたコードのハッシュ。ホットリロード用。ジェネレーターはデバッグとプロファイルのビルドでだけ渡します (main.spring.debug.dart にあります)
out ログ ログの代わりに失敗レポートのテキストを受け取る

progressListener (フィールド) は、スプラッシュ画面のために、起動がどこまで進んだかを通知されます。done、total、fraction (0 から 1 まで、決して戻らない) を持つ StartupProgress で、生成された Bean 定義と呼ばれたランナーを数えます。

factories (フィールド) は、すべての自動構成モジュールの factories を持つ SpringFactories で、Bean が一つも存在しないうちに動くコードのためのものです。springApplication.factories.load<ThemeDesign>() は一つの型のものを返します。コンテキストはそれを springFactories Bean として持ちます。ファクトリー を参照してください。

起動ログ

INFO で、spring_boot_dart.SpringApplication のもとに:

Starting neon-books using Dart 3.13.5 with PID 4242
The following 1 profile is active: "prod"
Started neon-books in 0.07 seconds

Flutter では、1 行目は using Flutter 3.50.0 (Dart 3.14.0) になります。有効なプロファイルがない場合は No active profile set, falling back to 1 default profile: "default" です。名前は spring.application.name で、設定されていなければ application です。spring.main.log-startup-info=false でこれらの行は出なくなります。spring_boot_starter_logging がなくても、SpringLog は INFO 以上をコンソールに書くため、どちらの場合もこれらの行は表示されます。

バナー

バナーはコンテキストの生成前に出力されます。

  1. spring.banner.location のファイル (デフォルトは resources:banner.txt、つまり lib/resources/banner.txt)。
  2. なければ SpringApplication(banner:)。
  3. それもなければ組み込みの SpringBootBanner。

spring.main.banner-mode (または bannerMode:) は console (出力する。デフォルト)、log (INFO でログに出す)、off のいずれかです (YAML が off から作る false も使えます)。ファイルの中の ${spring-boot.version}、${spring-boot.formatted-version}、その他の ${...} は置き換えられます。runAsync では、Flutter のアセットのように非同期にしか読めないバナーも出力されます。

# lib/resources/banner.txt
NEON Books ${spring-boot.formatted-version} on port ${server.port:8080}

遅延起動

spring.main.lazy-initialization=true は、すべてのシングルトンを起動時ではなく最初に使われたときに生成します。起動は短くなり、コマンドラインツールやモバイルアプリには助かりますが、壊れた Bean は後で、最初に使われたときに失敗します。

LazyInitializationExcludeFilter Bean は、それが除外する Bean を即時生成のままにします。

// キャッシュのウォーマーは、遅延起動でもアプリケーションとともに起動しなければならない。
@Bean()
LazyInitializationExcludeFilter eagerWarmer() =>
    LazyInitializationExcludeFilter.forBeanTypes([CacheWarmer]);

LazyInitializationExcludeFilter.of((name, definition, type) => ...) は Bean ごとに判断します。@Lazy(false) を付けた Bean も即時生成のままです。

Bean の上書き

同じ名前の Bean 定義が二つあると、起動が止まります。

The bean 'cache', defined in package:shop/cache.dart#CacheConfiguration, could not be registered. A bean with that name has already been defined and overriding is disabled.

spring.main.allow-bean-definition-overriding=true にすると、後の定義が前の定義を置き換えます。

コンテキストイニシャライザー

ApplicationContextInitializer は、Bean が生成される前にコンテキストを変更します。ポストプロセッサーやプロパティソースを追加したり、出来上がったオブジェクトを登録したりします。テストツールがこれを使います。

SpringApplication(
  [appBeans],
  initializers: [
    ApplicationContextInitializer.of(
      (context) => context.beanFactory.registerSingleton('clock', FixedClock()),
    ),
  ],
).run(args);

Spring (Java) との対応

SpringApplication application = new SpringApplication(NeonBooks.class);
application.setDefaultProperties(Map.of("server.port", "8080"));
application.setAdditionalProfiles("mobile");
application.addListeners(event -> ...);
application.run(args);

違い:

関連項目