
# SpringApplication

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

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

## 使う理由

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

## 例

```dart
// 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);
```

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

```dart
// 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}) => ...;
```

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

```dart
// 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`) に付けます。パッケージごとに一つです。[自動構成](auto-configuration.md) と [ジェネレーター: @SpringBootApplication](../spring-core-dart-generator/spring-boot-application.md) を参照してください。

## 起動の手順

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

1. **開始。** `ApplicationStartingEvent` を発行します。コマンドライン引数、`--dart-define` の値、OS の環境変数、`run(properties:)`、デフォルトプロパティをプロパティソースとして追加し、`${random.*}` も追加します。
2. **Environment。** 早期の `EnvironmentPostProcessor` (`SPRING_APPLICATION_JSON`) を実行し、設定ファイル (ロケーション、プロファイル、インポート) を読み、その他のポストプロセッサー ([名前が変わったプロパティ](configuration/sources.md#名前が変わったプロパティ) のチェック) を実行してから、`ApplicationEnvironmentPreparedEvent` を発行します。
3. **ロギング。** `logging.level.*` を `SpringLog` に適用し ([ログレベル](logging-levels.md) を参照)、バナーを出力します。
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 を順に呼びます ([ランナー](runners.md) を参照)。
9. **準備完了。** `ApplicationReadyEvent` と `ReadinessState.acceptingTraffic` を発行します。

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

## 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` を渡す)。[ホットリロード](hot-reload.md) 用、および同じアプリケーションを別の isolate で起動するため |

`hotReload` があると、コンテキストは `ApplicationLaunch` Bean (`springApplicationLaunch`) を持ちます。アプリケーションがどのように起動されたかを、引数、プロパティ、プロファイルとともに表し、同じものを再び起動できるようにします。Web サーバーの [isolate のプール](../spring-boot-starter-web/server/isolates.md) は、その各 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` が優先される ([シャットダウン](shutdown.md) を参照) |
| `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 として持ちます。[ファクトリー](auto-configuration.md#ファクトリー) を参照してください。

## 起動ログ

INFO で、`spring_boot_dart.SpringApplication` のもとに:

```text
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 のアセットのように非同期にしか読めないバナーも出力されます。

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

## 遅延起動

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

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

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

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

## Bean の上書き

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

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

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

## Spring (Java) との対応

```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 にはありません。

## 関連項目

- [ランナー](runners.md)
- [イベント](events.md)
- [失敗レポート](failure-analysis.md)
- [外部設定](configuration/index.md)
- [ジェネレーター: @SpringBootApplication](../spring-core-dart-generator/spring-boot-application.md)
- [ApplicationContext](../spring-core-dart/beans/application-context.md)
