シャットダウン
アプリケーションが閉じると、サーバーは停止します。server.shutdown=graceful (デフォルト) は、処理中のリクエストを先に完了させます。server.shutdown=immediate はそれらを打ち切ります。
使う理由
デプロイ、再起動、スケールダウンは、クライアントにサービスしている最中にプロセスを止めます。サーバーが即座に閉じると、そのクライアントは壊れた接続を受け取ります。注文が半分だけ保存されたり、アップロードが失われたりするかもしれません。グレースフルシャットダウンは、新しい接続の受け付けを止め、実行中のリクエストを待ち、それから閉じます。その間、ロードバランサーは新しいリクエストを他のインスタンスに送ります。
待つ価値のあるものがない場合、つまりテスト、ツール、開発では immediate を使ってください。
例
# lib/resources/application.yml
server:
shutdown: graceful
spring:
main:
register-shutdown-hook: true # Ctrl+C と SIGTERM でコンテキストを閉じる
lifecycle:
timeout-per-shutdown-phase: 20s # 実行中のリクエストにかけられる時間
server.shutdown=graceful
spring.main.register-shutdown-hook=true
spring.lifecycle.timeout-per-shutdown-phase=20s
一つのリクエストがまだ実行中のときのグレースフルな停止のログ:
INFO Commencing graceful shutdown. Waiting for active requests
INFO Graceful shutdown complete
INFO Web server stopped
プロパティ
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
server.shutdown |
graceful / immediate |
graceful |
サーバーの停止方法。 |
spring.lifecycle.timeout-per-shutdown-phase |
Duration |
30s |
グレースフルな停止が実行中のリクエストを待つ時間。spring_boot_dart のキー。 |
spring.main.register-shutdown-hook |
bool |
false |
SIGINT と SIGTERM でコンテキストを閉じる。spring_boot_dart のキー。 |
server.shutdown
- 型: enum。デフォルト:
graceful。
| 値 | 動作 |
|---|---|
graceful |
新しい接続は受け付けない。実行中のリクエストは、最大 spring.lifecycle.timeout-per-shutdown-phase まで完了できる。その後、残ったものは閉じられる。 |
immediate |
すべての接続が即座に閉じられる。実行中のリクエストは打ち切られ、そのクライアントには壊れた接続が見える。 |
- 変更する理由: 素早く止まるべきテストやツールには
immediate。 - 例:
server.shutdown=immediate。 - 誤った値:
server.shutdown=neverは、server.shutdownを名指しするバインディングの失敗で起動を止めます。
spring.lifecycle.timeout-per-shutdown-phase
- 型:
Duration。デフォルト:30s。 - ここでの動作: グレースフルな停止が実行中のリクエストを待つ最長の時間。
- さらに: Spring Boot と同じく、コンテキストのライフサイクルプロセッサーの各フェーズのタイムアウトでもあります。そのため、Bean はリクエストが完了した (または時間切れになった) 後にだけ破棄されます。まだデータベース接続を使っているリクエストの下で、プールが閉じられることはありません。
- 変更する理由: プラットフォームがより早くプロセスを殺す場合は短くする (Kubernetes は
terminationGracePeriodSeconds(デフォルト 30 秒) の後に SIGKILL を送ります。このキーはそれより小さくしてください)。リクエストが長い場合 (レポート、アップロード) は長くする。 - 例:
spring.lifecycle.timeout-per-shutdown-phase=20s。
spring.main.register-shutdown-hook
- 型:
bool。デフォルト:false(Spring Boot:true)。 - 動作: プロセスが SIGINT (
Ctrl+C) または SIGTERM (docker stop、Kubernetes) を受け取ると、コンテキストを閉じます。その後、サーバーはserver.shutdownの指定どおりに停止し、@PreDestroyメソッドが実行されます。VM のみです。 - 設定しない場合、 シグナルでプロセスは即座に終了します。グレースフルシャットダウンはまったく行われません。シグナルを待ち受けると Dart のプログラムが生き続けるため、デフォルトでは無効です。
- すべてのサーバーアプリケーションで
trueにしてください。
一つずつ見る動作
- コンテキストが閉じます。 そのライフサイクルプロセッサーが、
SmartLifecycleBean をフェーズごとに、大きいフェーズから停止します。サーバーのフェーズはSmartLifecycle.defaultPhase - 2048なので、デフォルトのフェーズの Bean はそれより先に停止します。 - 新しい接続はありません。 サーバーは待ち受けソケットを閉じます。
- 長く続くやり取りは、どちらのモードでもここで終わります。
- 開いている WebSocket セッションは、
1001(going away)、理由Server stoppingで閉じられます。 - 開いているイベントストリーム (
text/event-stream) と NDJSON ストリーム (application/x-ndjson) は閉じられます。それらは自分では終わらないので、待ってもタイムアウトを使い切るだけです。ブラウザーのEventSourceは別のインスタンスに再接続します。
- 開いている WebSocket セッションは、
- グレースフル: サーバーは、実行中のすべてのリクエストが完了してレスポンスが送られ、接続がアイドルになるまで待ちます。待つのは最大
spring.lifecycle.timeout-per-shutdown-phaseです。- リクエストが実行中だった場合は、
Commencing graceful shutdown. Waiting for active requests、続いてGraceful shutdown completeと記録します。 - 時間切れになると、
Graceful shutdown aborted with one or more requests still activeと記録し、すべての接続を強制的に閉じます。そのクライアントには壊れた接続が見えます。 - 実行中のリクエストがなければ、これらの行なしで閉じます。
- リクエストが実行中だった場合は、
- immediate: すべての接続がすぐに強制的に閉じられます。
- 完了。
Web server stoppedと記録されます。停止に失敗した場合はWeb server failed to stopが警告として記録され、シャットダウンは続行します。 - Bean が破棄されます (
@PreDestroy、close())。フェーズが終わった後です。
バイトストリームや StreamingResponseBody は、ここでは通常のリクエストです。グレースフルな停止は、タイムアウトの範囲でそれを待ちます。
ルールと特殊なケース
- グレースフルな停止によって 実行中のハンドラーが中断されることはありません。 Dart は実行中のコードを止められません。リクエストは時間内に完了するか、時間切れになったときに接続が閉じられるかのどちらかです。
- サーバーの起動中の停止 は、ソケットが開くのを待ってから閉じます。待ち受けたまま残るサーバーはありません。
- Flutter アプリでは、アプリがバックグラウンドに移るとコンテキストが一時停止します。サーバーは同じように停止し (ポートを解放し)、アプリが戻ると再び起動します。
spring.flutter.lifecycle.pause-in-background=falseで動かし続けられます。 - テストでは、テストがリクエストを開いたままにした場合、
server.shutdown=immediateで各テストのコンテキストが早く閉じます。
Spring (Java) との対応
server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=20s
重要な違い:
- キーとデフォルトは同じです。Spring Boot 3.4 以降と同じく、グレースフルシャットダウンがデフォルトです。
spring.main.register-shutdown-hookはデフォルトでfalseです。設定しないと、シグナルはグレースフルな停止なしにプロセスを終了させます。- 開いているイベントストリームと WebSocket セッションは、どちらのモードでもシャットダウンの開始時に閉じられます。Spring ではそれらはコンテナーに任されます。
- Spring Boot は処理を二つの Bean、
WebServerStartStopLifecycleとWebServerGracefulShutdownLifecycleに分けます。ここでは一つの Bean、webServerStartStopLifecycleが両方を行います。