Laravel によるモダナイゼーション：キュー、冪等性、安全な移行

検証できるほど小さな範囲を選ぶ

段階的な移行は各リリースの範囲を小さくできますが、リスクがなくなるわけではありません。入力、出力、担当者がはっきりしている限定的な業務フローから始めましょう。トラフィックを移す前に、既存のデータモデル、外部への副作用、レポートとの依存関係を洗い出します。

エラー率、応答レイテンシ、キューの滞留時間、完了した注文数などの業務成果を基準値として記録します。制御された一部のリクエストを新しい実装に振り向け、明確な戻り道を残しておきます。依存関係上どうしても必要な場合を除き、ストレージ、フレームワーク、決済、UI を同時に移行するのは避けましょう。

重要な書き込みはトランザクションで行う

権限と入力を検証したうえで、有効な最小限の状態遷移をデータベーストランザクション内で保存します。「注文ごとに外部参照は一つ」といった不変条件には一意制約を使います。行ロックや条件付き更新は、正しく使えば同時に起きる状態遷移を守れます。

Redis のロックで作業を調整することはできますが、リースの期限切れ、クラッシュ、範囲を誤ったキーによって処理が重なることがあります。データベースの制約の代わりにはなりません。どのシステムがどの不変条件を担うかを文書化し、同時リクエストで検証しましょう。

データがコミットされてからディスパッチする

ワーカーは、元になったトランザクションがコミットされる前に動き出すことがあります。Laravel にはコミット後にディスパッチする仕組みがあり、ジョブが未コミットやロールバック済みのレコードを読むのを防げます。Laravel 12 のアプリケーションでの基本的なパターンは次のとおりです。

DB::transaction(function () use ($validated) {
    $order = Order::create($validated);
    ProcessOrder::dispatch($order->id)->afterCommit();
});

この例は意図的に不完全です。認可、重複リクエストの処理、業務上の検証はこの周りに置きます。また、コミット後のディスパッチでも、データベースのコミットと外部キューへの受け渡しの間の障害の隙間はなくなりません。確実な配信が必要なフローでは、トランザクショナル・アウトボックスと再試行するパブリッシャーを検討してください。

「少なくとも1回」実行される前提でジョブを設計する

ジョブは複数回実行されうるものと考えます。冪等性キーを保存し、完了した操作を記録し、外部プロバイダーに冪等性の仕組みがあればそれを使います。外部への副作用が成功する前にジョブを完了扱いにしてはいけません。結果が不確かな場合は、請求や発送をやみくもに繰り返すのではなく、突き合わせて確認します。

• タイムアウト、再試行回数の上限、バックオフは操作ごとに設定します。
• ワーカーのタイムアウトはキューの再試行間隔より短くし、停止処理の余裕も持たせて、試行の重複を減らします。
• 失敗したジョブとキューの滞留時間を監視します。HTTP 202 は「受け付けた」という意味であり、「完了した」ではありません。
• 長時間動くワーカーはリリース時に再起動し、意図したコードを読み込ませます。

障害とロールバックをリハーサルする

重複した Webhook、外部呼び出し後のワーカーのクラッシュ、データベースのデッドロック、キューの停止、デプロイの失敗を試します。HTTP レスポンスだけでなく、結果として残ったレコードと副作用を確認します。受け付けたまま完了しなかった処理を突き合わせる仕組みも用意しましょう。

両方のアプリケーションが稼働している間は、後方互換性のあるスキーマ変更を使います。リリース前にロールバックの条件を定め、新しいアプリケーションが書いたデータを旧アプリケーションが読めるか確認します。同期の設計を明示的に行うまでは、各レコードの信頼できる情報源を一つに保ちます。

出典と参考資料

• Laravel 12：キュー、コミット後のディスパッチ、タイムアウト
• Laravel 12：データベーストランザクション

あわせて読みたい

レンダリング戦略を比較するか、Laravel への移行についてご相談ください。