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) は次のことを順に行います。
- 開始。
ApplicationStartingEventを発行します。コマンドライン引数、--dart-defineの値、OS の環境変数、run(properties:)、デフォルトプロパティをプロパティソースとして追加し、${random.*}も追加します。 - Environment。 早期の
EnvironmentPostProcessor(SPRING_APPLICATION_JSON) を実行し、設定ファイル (ロケーション、プロファイル、インポート) を読み、その他のポストプロセッサー (名前が変わったプロパティ のチェック) を実行してから、ApplicationEnvironmentPreparedEventを発行します。 - ロギング。
logging.level.*をSpringLogに適用し (ログレベル を参照)、バナーを出力します。 - コンテキスト。 アプリケーションのモジュールから、続いて自動構成をその順序でコンテキストを生成します。これにより、スターターの
@ConditionalOnMissingBeanはアプリケーションの Bean を認識できます。ApplicationArgumentsを Bean として登録し、@ConfigurationPropertiesのバインドを登録します。initializersを実行し、ApplicationContextInitializedEventとApplicationPreparedEventを発行します。 - Bean。 コンテキストをリフレッシュします。すべてのシングルトンが (遅延でない限り) 生成され、
ContextRefreshedEventが発行されます。 - 待機。
AsyncStartupを実装する Bean (ポートをバインドする Web サーバー) を待ちます。どれかが失敗すると起動が失敗します。ランナーもApplicationReadyEventもありません。 - 起動完了。
Started neon-books in 0.07 secondsをログに出し、ApplicationStartedEventとLivenessState.correctを発行します。 - ランナー。
ApplicationRunnerとCommandLineRunnerの Bean を順に呼びます (ランナー を参照)。 - 準備完了。
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 以上をコンソールに書くため、どちらの場合もこれらの行は表示されます。
バナー
バナーはコンテキストの生成前に出力されます。
spring.banner.locationのファイル (デフォルトはresources:banner.txt、つまりlib/resources/banner.txt)。- なければ
SpringApplication(banner:)。 - それもなければ組み込みの
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);
違い:
- モジュールはコンストラクターに渡し、その呼び出しはジェネレーターが書きます。実行時にスキャンするクラスはありません。
runApplicationは非同期のランナーが終わる前に戻ります。runApplicationAsyncは Spring Boot のrunと同じくそれらを待ちます。EnvironmentPostProcessorとFailureAnalyzerは、spring.factoriesではなくコンストラクターに渡します。スターターが Bean より前に追加するそれ以外のものは、その@AutoConfigurationModuleのfactoriesにあり、Spring がSpringFactoriesLoader.loadFactories(type, classLoader)を呼ぶところでfactories.load<T>()で読みます。- 起動ログにはプロセスの稼働時間がなく、バナーは
printで出力されます。 progressListenerに対応するものは Spring にはありません。