
# ランナー

ランナーとは、アプリケーションの起動後に一度 `run` メソッドが呼ばれる Bean です。データベースのマイグレーション、キャッシュのウォームアップ、コマンドラインツールの処理などに使います。ランナーは Spring Boot と同じく、`@Order` で並べられ、一つずつ順に実行されます。

## 使う理由

起動時の処理にはすべての Bean が存在している必要があり、多くの場合、決まった順序で行わなければなりません。ウォームアップがスキーマを読む前に、スキーマをマイグレーションしておく必要があります。ランナーはコンテキストの準備ができた後に呼ばれ、次のランナーは前のランナー (その `Future` を含む) が終わってから始まります。失敗したランナーは、アプリケーションを中途半端に起動したままにせず、レポートとともに停止させます。

## 例

```dart
// 他の何かがデータベースに触れる前に、スキーマを最新にしておく必要がある。
@Component()
@Order(1)
class Migrations implements ApplicationRunner {
  Migrations(this.db);

  final Database db;

  @override
  Future<void> run(ApplicationArguments args) => db.migrate(); // 待たれる
}

// Migrations が終わってから始まる。
@Component()
@Order(2)
class Warmup implements ApplicationRunner {
  Warmup(this.catalog);

  final Catalog catalog;

  @override
  Future<void> run(ApplicationArguments args) => catalog.loadBestsellers();
}

// コマンドラインの処理: dart run bin/main.dart --dry-run books.csv
@Component()
class Importer implements ApplicationRunner {
  Importer(this.books);

  final BookStore books;

  @override
  Future<void> run(ApplicationArguments args) async {
    final dryRun = args.containsOption('dry-run');
    for (final file in args.nonOptionArgs) {
      await books.importCsv(file, save: !dryRun);
    }
  }
}
```

## 2 つの種類

| インターフェース | `run` が受け取るもの | 用途 |
|---|---|---|
| `ApplicationRunner` | `ApplicationArguments`: 解析済みのオプションと通常の引数 | ほとんどのランナー |
| `CommandLineRunner` | `List<String>`: `main` が受け取ったとおりの引数 | 引数を自分で解析するコード |

どちらも `void` または `Future` を返せます。両方を実装する Bean は、両方として呼ばれます。

## 順序とタイミング

- ランナーは `@Order` (または `Ordered`) の小さい順に並べられます。順序のないランナーは最後になります。
- 各ランナーは、その `Future` を含めて終わってから次のランナーが始まります。
- `ApplicationStartedEvent` と `AsyncStartup` の Bean (待ち受けを始めた Web サーバー) の後、`ApplicationReadyEvent` の前に実行されます。
- その間にコンテキストが閉じられると、残りのランナーはスキップされます。
- `runApplication` は同期部分が終わると戻り、非同期のランナーはその後も続きます。`await runApplicationAsync(args)` は最後のランナーの後に完了します。

## ランナーが失敗したとき

失敗はエラーとともに `Application run failed` として報告され、`ApplicationFailedEvent` が発行され、コンテキストが閉じられます。`runApplication` では、非同期の失敗はどの `try` の外でも再スローされ、プログラムは 0 以外のコードで終了します。`runApplicationAsync` では、返された `Future` が失敗します。

失敗時の終了コードは、`ExitCodeExceptionMapper` の Bean から、または例外自身が `ExitCodeGenerator` を実装していればその例外から来ます。[シャットダウンと終了コード](shutdown.md) を参照してください。

## ApplicationArguments

`SpringApplication` は引数を一度だけ解析し、その結果を Bean として登録します。そのため、どの Bean でも注入できます。

| メンバー | 意味 |
|---|---|
| `sourceArgs` | `main` が受け取ったとおりの引数 |
| `optionNames` | 指定されたオプションの名前 (`--dry-run` なら `dry-run`) |
| `containsOption(name)` | 値の有無にかかわらず、オプションが指定されたかどうか。名前はダッシュなし |
| `getOptionValues(name)` | 値を順に (`--tag=a --tag=b` なら `['a', 'b']`)。値のない `--name` なら `[]`。指定されていなければ `null` |
| `nonOptionArgs` | 通常の引数: `--` で始まらないもの、および単独の `--` の後のすべて |

オプションは `--name=value` か、値のない `--name` です。区切りになるのは最初の `=` だけです。`-v` は通常の引数です。オプションはプロパティでもあるため、`--server.port=8081` は `server.port` を設定します。ほとんどの設定は、ここからではなく `@Value` や `@ConfigurationProperties` で読みます。

## ランナーとホットリロード

Flutter のホットリロードがコンテキストを再起動する (Bean や設定が変わった) と、Spring Boot DevTools の再起動後と同じく、デフォルトでランナーが再び実行されます。`reloadApplication(context, runners: false)` は、マイグレーション、アナリティクスのイベント、ネットワーク呼び出しを繰り返さずに Bean を再起動します。[ホットリロード](hot-reload.md) を参照してください。

## Spring (Java) との対応

```java
@Component
@Order(1)
class Migrations implements ApplicationRunner {
  public void run(ApplicationArguments args) { db.migrate(); }
}
```

インターフェースも順序も同じです。`Future` を返すランナーは次のランナーの前に待たれます。Java ではこれは必要ありません。

## 関連項目

- [SpringApplication](spring-application.md)
- [イベント](events.md)
- [シャットダウンと終了コード](shutdown.md)
- [コマンドライン](configuration/sources.md)
