
# シャットダウンと終了コード

サーバーやスケジューラーは、停止されるまで動き続けます。きれいに停止するには、プロセスが SIGINT (`Ctrl+C`) や SIGTERM (`kill`、コンテナの停止) を受け取ったときにコンテキストを閉じる必要があります。そうすれば、Web サーバーは実行中のリクエストを完了し、`@PreDestroy` メソッドと `ContextClosedEvent` のリスナーが実行され、プロセスが終了します。一方、コマンドラインツールは自分から終了し、多くの場合、結果を終了コードで呼び出し元に伝える必要があります。

## 使う理由

処理の途中で強制終了されたプロセスは、接続を開いたまま、ファイルを書きかけのまま、リクエストに応答しないまま残します。シグナルでコンテキストを閉じれば、すべての Bean に処理を終える機会が与えられます。終了コードがあれば、シェルスクリプトや CI のジョブは、一部が失敗したバッチに対応できます。

## 例

グレースフルに停止するサーバー:

```properties
# lib/resources/application.properties
spring.main.register-shutdown-hook=true
spring.lifecycle.timeout-per-shutdown-phase=20s
server.shutdown=graceful
```

```dart
@Component()
@Log()
class Outbox {
  // コンテキストが閉じるときに実行される。フックが有効なら Ctrl+C でも。
  @PreDestroy()
  Future<void> flush() async {
    log.info('Sending the last messages');
    await _send();
  }
}
```

一部の項目が失敗したかどうかをシェルに伝えるツール:

```dart
@Component()
class FailedJobs implements ExitCodeGenerator {
  int failed = 0;

  @override
  int getExitCode() => failed > 0 ? 2 : 0;
}

Future<void> main(List<String> args) async {
  final context = await runApplicationAsync(args);   // ジョブのランナーを実行する
  exit(SpringApplication.exit(context));              // dart:io。0 または 2
}
```

## シャットダウンフック

| 設定 | デフォルト | 意味 |
|---|---|---|
| `spring.main.register-shutdown-hook` | `false` | SIGINT または SIGTERM でコンテキストを閉じる。コンストラクターより優先される |
| `SpringApplication(registerShutdownHook: true)` | `false` | 同じことをコードで |

フックが有効な場合、SIGINT ではコンテキストを閉じてプロセスを `exit(130)` で、SIGTERM では `exit(143)` で終了します。コンテキストの `registerShutdownHook()` を使います。コンテキストが他の方法で閉じられると、リスナーは取り除かれます。

Spring Boot と異なり、これは**デフォルトで無効**です。シグナルを待ち受ける Dart プログラムは自分からは終了しないため、処理を終えたツールがいつまでも終了しなくなるからです。停止されるまで動くプログラム (サーバー、スケジューラー、ワーカー) で有効にしてください。`dart:io` を通して待ち受けるため、Web では何もしません。Flutter アプリは代わりにアプリのライフサイクルを通してコンテキストを閉じます。

## シャットダウンのタイムアウト

コンテキストが閉じるとき、`lifecycleProcessor` はライフサイクルの Bean (Web サーバーを含む) をフェーズごとに停止し、各フェーズを最大 `spring.lifecycle.timeout-per-shutdown-phase` だけ待ちます。その後、処理を進め、Bean が破棄されます。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.lifecycle.timeout-per-shutdown-phase` | `Duration` | `30s` | 一つのシャットダウンフェーズにかけてよい時間。たとえば Web サーバーのグレースフルシャットダウン |

このプロセッサーは `LifecycleAutoConfiguration` から来ます。それがない場合 (除外した場合や、手で生成したコンテキスト)、プロパティにかかわらず、コンテキストは Spring Framework のデフォルトである 10 秒待ちます。

## 終了コード

`SpringApplication.exit(context, [generators])` はコンテキストを閉じ、プロセスが終了すべきコードを返します。

1. 2 番目の引数で渡されたジェネレーターと `ExitCodeGenerator` の Bean に、順序 (`Ordered`、`@Order`) に従って問い合わせます。
2. 最初の 0 以外のコードが採用されます。なければ `0` です。
3. 0 以外のコードは、コンテキストが閉じる前に `ExitCodeEvent` として発行されます。
4. 途中の失敗 (クローズを含む) は警告としてログに出され、すでにコードが見つかっていない限り `1` になります。

結果を `dart:io` の `exit` に渡してください。

## 失敗した実行の終了コード

ランナーが失敗した場合、コードは `ExitCodeExceptionMapper` の Bean (コンテキストがまだ有効な間に問い合わせる) から、なければ例外自身が `ExitCodeGenerator` を実装していればその例外から来ます。コードは `ExitCodeEvent` として発行され、`SpringApplication.exitCodeOf(error)` がそれを返します。

```dart
// インポーターのエラーを、運用担当者が知っているコードに対応させる。
@Component()
class ImportErrors implements ExitCodeExceptionMapper {
  @override
  int getExitCode(Object exception) => switch (exception) {
        FileSystemException() => 3,
        FormatException() => 4,
        _ => 0,
      };
}

Future<void> main(List<String> args) async {
  try {
    await runApplicationAsync(args);
  } catch (error) {
    exit(SpringApplication.exitCodeOf(error) ?? 1);
  }
}
```

Bean の生成中に失敗した起動には、マッパーからのコードはありません (コンテキストが有効でないため)。エラーとしてスローされた文字列や数値にも、コードは決してありません。

## Spring (Java) との対応

```java
System.exit(SpringApplication.exit(SpringApplication.run(Job.class, args)));
```

違い:

- シャットダウンフックはデフォルトで無効で、SIGINT と SIGTERM にだけ反応します (Dart には終了フックがありません)。その後、プロセスは `130` または `143` で終了します。
- 失敗した実行の終了コードは、例外ハンドラーに渡されるのではなく、`main` が `exit` に渡せるよう `exitCodeOf` が返します。

## 関連項目

- [ランナー](runners.md)
- [組み込みの Bean](built-in-beans.md)
- [@PreDestroy](../spring-core-dart/beans/pre-destroy.md)
- [Lifecycle](../spring-core-dart/beans/lifecycle.md)
- [Web サーバーのシャットダウン](../spring-boot-starter-web/server/shutdown.md)
