ランナー
ランナーとは、アプリケーションの起動後に一度 run メソッドが呼ばれる Bean です。データベースのマイグレーション、キャッシュのウォームアップ、コマンドラインツールの処理などに使います。ランナーは Spring Boot と同じく、@Order で並べられ、一つずつ順に実行されます。
使う理由
起動時の処理にはすべての Bean が存在している必要があり、多くの場合、決まった順序で行わなければなりません。ウォームアップがスキーマを読む前に、スキーマをマイグレーションしておく必要があります。ランナーはコンテキストの準備ができた後に呼ばれ、次のランナーは前のランナー (その Future を含む) が終わってから始まります。失敗したランナーは、アプリケーションを中途半端に起動したままにせず、レポートとともに停止させます。
例
// 他の何かがデータベースに触れる前に、スキーマを最新にしておく必要がある。
@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 を実装していればその例外から来ます。シャットダウンと終了コード を参照してください。
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 を再起動します。ホットリロード を参照してください。
Spring (Java) との対応
@Component
@Order(1)
class Migrations implements ApplicationRunner {
public void run(ApplicationArguments args) { db.migrate(); }
}
インターフェースも順序も同じです。Future を返すランナーは次のランナーの前に待たれます。Java ではこれは必要ありません。