ランナー

ランナーとは、アプリケーションの起動後に一度 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 は、両方として呼ばれます。

順序とタイミング

ランナーが失敗したとき

失敗はエラーとともに 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 ではこれは必要ありません。

関連項目