
# アプリケーション: @SpringBootApplication

`main` に付ける `@SpringBootApplication()` (`spring_boot_dart` のもの) は、アプリケーションに必要な唯一のアノテーションです。それを宣言するライブラリに対して、ジェネレーターはアプリケーションの起動に必要なすべてを含む `.spring.dart` ファイルを書き出します。

- パッケージのすべての Bean を含むモジュール。
- `springApplication`: Bean、依存関係にあるすべてのスターターの自動構成、`lib/resources/` のファイル、`--dart-define` キー。
- `runApplication`、`runApplicationAsync`、ホットリロードの関数。

```dart
// bin/main.dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

import 'spring_gen/main.spring.dart'; // ジェネレーターが書き出す

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

`dart run build_runner build` は `bin/spring_gen/main.spring.dart` を書き出します。Flutter アプリでは、`main` は `lib/main.dart` にあり、ファイルは `lib/spring_gen/main.spring.dart` です。

## 使う理由

Spring Boot では、メインクラスに付けた `@SpringBootApplication` が、そのクラスのパッケージからのコンポーネントスキャンと、クラスパス上のすべてのスターターからの自動構成を有効にします。その後、`SpringApplication.run` が起動時に両方を見つけます。

Dart はどちらも実行時には見つけられません。検索するクラスパスも、読む `META-INF/spring/...AutoConfiguration.imports` もないからです。そこでジェネレーターは両方の検索をビルド時に行い、その結果を一つの値 `springApplication` として書き出します。`main` はそれを実行するだけです。他には何も要りません。`@ComponentScan` も、モジュールのリストも、スターターの登録も不要です。`pubspec.yaml` にスターターを追加して `build_runner` を実行すれば十分です。

## スキャンされるもの

スキャンはパッケージ全体に及びます。

| `main` の場所 | スキャンされるディレクトリ |
|---|---|
| `bin/main.dart` | `lib/` と `bin/` |
| `lib/main.dart` (Flutter) | `lib/` |
| `test/app/main.dart` | `lib/` と `test/app/` |
| `example/main.dart`、`example/shop/bin/main.dart` | `example/` のみ |

生成された `$application` ゲッターのドキュメントコメントがそれらを示します: "Beans found by `@ComponentScan` in `lib/ and bin/`."

`example/` の下のエントリーポイントは、ライブラリやスターターのサンプルです。スキャンされるのは `example/` だけで、パッケージ自身の自動構成は他の依存関係のものと同じように追加されます。パッケージの `lib/` は、それに依存する任意のアプリケーションに届くのと同じ方法でサンプルに届きます。

それらのディレクトリの下のすべての `.dart` ファイルが、パスでソートされ、生成ファイルを除いてスキャンされます。Bean は `application` という名前の一つのモジュールに入り、ゲッター `$application` として宣言されます。

### 入れ子の @ComponentScan ルート

スキャンされるディレクトリの中の `@ComponentScan` ファイルは、そのディレクトリを所有します。その Bean は独自のモジュールにとどまり、`$application` は代わりにそのモジュールをインポートします (最も外側のスキャンのみ。[入れ子のスキャン](component-scan.md#入れ子のスキャン) を参照)。リポジトリのサーバーガイドは、すべての Bean を一つのスキャンルートの背後の `lib/src/` に置いているので、そのアプリケーションモジュールは空で、それをインポートするだけです。

```dart
// lib/src/app.dart
@ComponentScan()
final BeanModule appBeans = $appBeans;
```

```dart
// bin/spring_gen/main.spring.dart (抜粋、プレフィックスはそのまま)
/// Beans found by `@ComponentScan` in `lib/ and bin/`.
_i1.BeanModule get $application => _i1.BeanModule(
  r'application',
  [],
  imports: [_i2.appBeans],
  resources: const { /* lib/resources/ のファイル */ },
);
```

## 生成されるファイル

ファイルには、次の順で、生成されたクラス (AOP プロキシとその他のサブクラス)、`$application`、`springApplication`、四つの起動とリロードの関数、そして `@Log` と Flutter の拡張が含まれます。

### springApplication

サーバーガイドの `bin/spring_gen/main.spring.dart` の抜粋です。Web、セキュリティ、WebSocket、Feign、キャッシュ、スケジューリングのスターターを使うアプリケーションです (153 個の `--dart-define` エントリーを二つに短縮しています)。

```dart
/// The `@SpringBootApplication` of the current code (a getter, so it is
/// up to date after a hot reload).
_i3.SpringApplication get springApplication => _i3.SpringApplication(
  [$application],
  autoConfigurations: [
    _i4.springBootAutoConfiguration,
    _i5.springBootStarterCacheAutoConfiguration,
    _i6.springBootStarterFeignAutoConfiguration,
    _i7.springBootStarterLoggingAutoConfiguration,
    _i8.springBootStarterOauth2ClientAutoConfiguration,
    _i9.springBootStarterSchedulingAutoConfiguration,
    _i10.springBootStarterSecurityAutoConfiguration,
    _i10.springBootStarterSecurityOAuth2ClientAutoConfiguration,
    _i11.springBootStarterWebAutoConfiguration,
    _i12.springBootStarterWebsocketAutoConfiguration,
    _i13.springSecurityCoreAutoConfiguration,
  ],
  autoConfigurationMetadata: {
    _i10.springBootStarterSecurityAutoConfiguration:
        const _i3.AutoConfigurationModule(
          after: ['springBootStarterOauth2ClientAutoConfiguration'],
        ),
    _i10.springBootStarterSecurityOAuth2ClientAutoConfiguration:
        const _i3.AutoConfigurationModule(
          before: ['springBootStarterOauth2ClientAutoConfiguration'],
        ),
  },
  dartDefines: {
    if (const bool.hasEnvironment('DEBUG'))
      'DEBUG': const String.fromEnvironment('DEBUG'),
    if (const bool.hasEnvironment('LOGGING_FILE_NAME'))
      'LOGGING_FILE_NAME': const String.fromEnvironment('LOGGING_FILE_NAME'),
    // ...
  },
  fingerprint: !const bool.fromEnvironment('dart.vm.product')
      ? _$fingerprint
      : null,
);
```

その引数:

| 引数 | 書かれる条件 | 内容 |
|---|---|---|
| 最初の引数 | 常に | `[$application]`。パッケージの Bean のモジュールです。 |
| `autoConfigurations` | 依存関係に自動構成がある | すべての依存関係の `lib/spring_auto_configuration.dart` の `@AutoConfigurationModule` 変数。パッケージ順、次に名前順にソートされます。[自動構成](auto-configurations.md) を参照してください。 |
| `autoConfigurationMetadata` | モジュールが `order`、`before`、`after` を設定している | そのようなモジュールごとの値。ランタイムはそれでモジュールをソートします。 |
| `exclude`、`excludeName` | `@SpringBootApplication` が設定している | 除外する自動構成 ([下記](None#exclude-と-excludename) を参照)。 |
| `dartDefines` | 実際には常に | `--dart-define` が設定しうるプロパティごとに一つのエントリー。[--dart-define キー](dart-defines.md) を参照してください。 |
| `fingerprint` | デバッグとプロファイルのビルド | ホットリロードのための、生成コードのハッシュ (デバッグ用 part にあります)。リリースビルドでは `null` ([下記](None#ホットリロード) を参照)。 |

`springApplication` は変数ではなくゲッターです。ホットリロードがその本体を置き換えた後、次の呼び出しは新しいコードからアプリケーションを組み立てます。

アプリケーションがビルドから、またはリリースビルドから外すことをスターターが許しているモジュールは、アプリケーションの `application.properties` や `application.yml` からビルド時に決められます ([ビルドから外されるモジュール](optimizations/build-conditions.md) を参照)。リリースビルド以外でだけ残されるモジュールは定数の条件の背後に書かれるので、リリースビルドはそれと、それだけが使うすべてをコンパイル時に取り除きます。

```dart
// seo_site サンプルの lib/spring_gen/main.spring.dart (抜粋)
autoConfigurations: [
  _i5.springBootAutoConfiguration,
  _i6.springBootStarterFlutterAutoConfiguration,
  if (!const bool.fromEnvironment('dart.vm.product'))
    _i6.springBootStarterFlutterDebugAutoConfiguration,
  _i7.springBootStarterFlutterNavigationAutoConfiguration,
  _i8.springBootStarterLoggingAutoConfiguration,
],
```

数えられるのは、`pubspec.yaml` ファイルから読まれる、アプリケーションの依存関係 (直接、または他のパッケージを通して) だけです。pub ワークスペースではパッケージ設定にワークスペースのすべてのメンバーが列挙されますが、アプリケーションは依存していない兄弟パッケージの自動構成を受け取りません。

スターターは、動作する `spring_boot_dart` のバージョンを宣言できます (`requires`)。使われているバージョンがその範囲外なら、ビルドはスターター、範囲、バージョン、アップグレードすべきものを示して失敗します。

### runApplication と runApplicationAsync

```dart
/// Starts the application: config files, environment, context, runners
/// (asynchronous runners go on one after another after it returns;
/// [runApplicationAsync] waits for them).
ConfigurableApplicationContext runApplication(List<String> args) =>
    springApplication.run(args, hotReload: () => springApplication);

/// Like [runApplication], reading config files asynchronously (Flutter assets)
/// and completing once every runner has finished.
Future<ConfigurableApplicationContext> runApplicationAsync(
  List<String> args,
) => springApplication.runAsync(args, hotReload: () => springApplication);
```

`main` からどちらかを呼びます。これらは `hotReload: () => springApplication` を渡すので、ランタイムはホットリロードの後に現在のコードからアプリケーションを組み立て直せます。

Flutter アプリは、代わりにゲッターをルートウィジェットに渡します。

```dart
// lib/main.dart
@SpringBootApplication()
void main() => runApp(SpringApplicationWidget(application: () => springApplication));
```

同じパッケージの他のエントリーポイントも、独自のアノテーションなしで生成ファイルをインポートし、これらの関数を使えます。サーバーガイドの `bin/advanced.dart` は `spring_gen/main.spring.dart` をインポートし、別の引数で `runApplicationAsync([...])` を呼びます。

### ホットリロード

ホットリロードだけが使うものは、専用の part `lib/spring_gen/main.spring.debug.dart` にあり、ライブラリは `!const bool.fromEnvironment('dart.vm.product')` の下でだけそれを参照します。リリースビルド (`dart compile exe`、AOT、Flutter のリリース) はそれを一切コンパイルしません。デバッグとプロファイルの実行は、ホットリロードも含めて従来どおり動きます。

```dart
// lib/spring_gen/main.spring.debug.dart (generated)
const _$fingerprint = '3ada566f';

/// For hot reload: [running] if the generated code is unchanged, else a
/// restarted application with the new beans and the same arguments;
/// [runners]: whether ApplicationRunner / CommandLineRunner beans run again.
ConfigurableApplicationContext reloadApplication(
  ConfigurableApplicationContext running, {
  bool runners = true,
}) => springApplication.reload(running, runners: runners);

/// Like [reloadApplication], reading config files asynchronously.
Future<ConfigurableApplicationContext> reloadApplicationAsync(
  ConfigurableApplicationContext running, {
  bool runners = true,
}) => springApplication.reloadAsync(running, runners: runners);
```

ホットリロードはメソッドの本体を置き換えますが `main` を再実行しないので、リロード前に組み立てられたコンテキストは古い Bean を持ち続けます。それが問題になるかを判断するため、ジェネレーターは **フィンガープリント** を書き出します。生成コード (ライブラリとそのファイル) の FNV-1a ハッシュで、デバッグ用 part に書き込まれ、デバッグとプロファイルのビルドで `springApplication` が渡します。リロードの後、`reload` は新しいコードのフィンガープリントを、実行中のコンテキストが起動されたときのものと比べます。

- **同じ。** メソッドの本体だけが変わり、生成コードは変わっていません。実行中のコンテキストがそのまま返され、Bean は状態を保ちます。
- **異なる。** Bean、アノテーション、または `lib/resources/` のファイルが変わりました (リソースはファイルに埋め込まれているので、ハッシュも変わります)。コンテキストは閉じられ、アプリケーションは同じ引数で再起動します。`runners: false` を指定すると、その再起動で `ApplicationRunner` と `CommandLineRunner` の Bean をスキップします。

あえてすべてのビルドに残るものがあります。`runApplication` の `hotReload: () => springApplication` (コンテキストが同じアプリケーションを別のアイソレートで起動する方法でもあり、Web サーバーの `server.isolates.count` が使います)、ゲッター `springApplication` と `$application`、Bean の `source:` 文字列 (起動時のエラーとアクチュエーターが読みます) です。

ハッシュは生成されたテキストそのものから計算されるので、コードが同じである限り、どのマシンでも、ビルドごとにも同じです。これらの関数を呼ぶことはまれです。Flutter のホットリロードでは `SpringApplicationWidget` が呼び、Dart VM では、開発ツールが求めたときに `runApplication` で起動されたコンテキストをランタイムが再起動します。

## exclude と excludeName

`@SpringBootApplication` は、自動構成を無効にする二つのリストを受け取ります。

```dart
@SpringBootApplication(
  exclude: [CacheAutoConfiguration],
  excludeName: ['springBootStarterFeignAutoConfiguration'],
)
void main(List<String> args) => runApplication(args);
```

ジェネレーターはそれらを、クラスへの参照と文字列として `springApplication` にコピーします。

```dart
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [/* ... */],
  exclude: [CacheAutoConfiguration],
  excludeName: [r'springBootStarterFeignAutoConfiguration'],
  // ...
);
```

残りはランタイムが行います。`exclude` は `@AutoConfiguration` クラスを列挙します。そうでない型は起動を失敗させます。`excludeName` は `@AutoConfiguration` クラスの名前か、モジュール全体の名前 (スターターが追加するすべてを取り除く) を受け取ります。未知の名前は無視されます。プロパティ `spring.autoconfigure.exclude` を使うと、再ビルドなしで名前を追加できます。

## 埋め込みリソース

`lib/resources/` のファイルは `resources:` として `$application` に埋め込まれるので、`application.properties`、メッセージバンドル、テンプレートはどのプラットフォームでも見つかります。`main` が `lib/` の外にあるアプリケーションは、パッケージのルートから `main` までの間にある各ディレクトリの `lib/resources/` も受け取り、最も近いものが優先されます。アクチュエーターを使うアプリケーションは `build-info.properties` も受け取ります。[埋め込みリソース](resources.md) を参照してください。

## --dart-define キー

Flutter、Web、AOT 向けにコンパイルされたプログラムは、定数のキーを持つ `--dart-define` しか読めません。そこで `springApplication` は、アプリケーションが読みうるすべてのプロパティを両方の形 (`greeting.punctuation` と `GREETING_PUNCTUATION`) で、それぞれ `if (const bool.hasEnvironment(...))` の背後に列挙します。マップに入るのはビルド時に与えられた define だけで、コマンドライン引数のすぐ下のプロパティソースになります。[--dart-define キー](dart-defines.md) を参照してください。

## ルールとエラー

- 一つのファイルに `@SpringBootApplication` は一つです。同じファイルの二つ目はビルドを失敗させます: `Only one @SpringBootApplication is allowed per file.`
- 一つのパッケージに複数のエントリーポイント (`bin/server.dart`、`bin/worker.dart`) があると、それぞれが独自の生成ファイルを受け取り、それぞれが `lib/` と `bin/` をスキャンします。
- `main` のファイルに `@ComponentScan` 変数を置かないでください。アプリケーションが優先されます。ファイルはアプリケーションの出力を受け取り、変数が読むゲッターは生成されません。
- Bean 名は一意でなければならず、他の [ビルド時のチェック](checks.md) も、どのモジュールとも同じように適用されます。

## Spring (Java) との対応

```java
@SpringBootApplication(exclude = CacheAutoConfiguration.class)
public class ShopApplication {
  public static void main(String[] args) {
    SpringApplication.run(ShopApplication.class, args);
  }
}
```

違い:

- `@SpringBootApplication()` はクラスではなく `main` 関数に付けます。
- コンポーネントスキャンが対象とするのは、Java のパッケージとそのサブパッケージではなく、`lib/` と `main` のディレクトリです。
- 自動構成は、起動時に `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` からではなく、ビルド時に各依存関係の `lib/spring_auto_configuration.dart` から見つけられます。スターターを追加または削除したら `build_runner` を実行してください。
- ホットリロードは生成コードのフィンガープリントを比べます。Spring Boot DevTools はディスク上のクラスファイルが変わると再起動します。

## 関連項目

- [@ComponentScan モジュール](component-scan.md)
- [自動構成](auto-configurations.md)
- [Bean 定義](bean-definitions.md)
- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
