🐙

LaravelのQueue基礎と使いどころ（初心者向け）

に公開
Laravel
tech

概要

Laravelのキュー（Queue）機能を初めて使ってみました。
「こういうときに使える・使うといい」という選択肢の1つとして知識を蓄積するために、Laravelのキュー（Queue）機能の基本と、どんな場面で使うと効果的かを整理しました。
短時間で「使いどころ」を判断できるよう、具体例と導入手順をまとめます。

導入

Webアプリの処理には、すぐに返したい応答と、裏側で時間をかけて実行したい処理があります。LaravelのQueueは、重い処理をバックグラウンドに回し、ユーザー体験と安定性を両立するための標準機能です。

本文

まずは用語から（超ざっくり）

  • Queue: 仕事の「順番待ちボックス」。DBやRedisに積まれます
  • Job: やりたい処理を1つのクラスにまとめたもの
  • Worker: ボックスからJobを取り出して、ひたすら処理する係

イメージは「受付でチケットを渡す（即応答）→裏で係の人が作業する（時間がかかってもOK）」です。

使いどころの判断（こういうときに使える）

  • 外部API呼び出しが重い: 応答まで数十秒〜数分かかる処理
  • メール送信・通知: ユーザーには即応答し、送信は裏側で
  • 画像/ファイル処理: サムネ生成、PDF作成など時間が読みにくい処理
  • バッチ/集計: 多量データの一括処理、再試行が必要な処理
  • タイムアウト回避: 同期だと落ちやすい処理を安全に分離

仕組みの超要約（初心者向け視点）

  • アプリは「受付」だけやる：すぐレスポンスを返す
  • Jobは「作業指示書」：やることをhandle()に書く
  • Workerは「作業係」：指示書どおりに実行、終わったら次へ

処理フローイメージ

[APIリクエスト] 
    ↓ 0.1秒
[ジョブをキューに投入] ← dispatch()
    ↓ すぐレスポンス返却
[ユーザーに即座に応答]

--- 以下、バックグラウンド ---

[Worker: php artisan queue:work]
    ↓ 常時監視
[キューからジョブ取得]
    ↓
[ジョブ実行（handle()メソッド）]
    ↓ 3分かかってもOK
[結果をDBに保存]
    ↓
[次のジョブを待機]

最小構成の導入手順（Databaseキュー）

  1. マイグレーション実行
    • php artisan queue:table
    • php artisan queue:failed-table
    • php artisan migrate
  2. ジョブ作成
    • php artisan make:job SummarizeArticleJob
  3. 接続設定
    • .env: QUEUE_CONNECTION=database
    • config/queue.php の connections.database を確認
  4. ワーカー起動（開発）
    • php artisan queue:work

実装の勘所（最初に押さえる設定）

  • ShouldQueue: ジョブをキューで実行するためのインターフェイス
  • timeout: 長めに設定（例: 600 秒）
  • tries/backoff: リトライ回数と間隔で安定性確保
  • failed(Throwable $e): 失敗時の後処理（状態更新・通知）
  • Controller側: DBに受付を記録して dispatch() で投入、レスポンスは即返す

参考の最小コード例（雛形）

// app/Jobs/ExampleJob.php
use Illuminate\Contracts\Queue\ShouldQueue;

class ExampleJob implements ShouldQueue
{
    public $timeout = 600; // 10分
    public $tries = 3;     // 3回リトライ

    public function __construct(public int $resourceId) {}

    public function handle(): void
    {
        // 重い処理や外部API呼び出しをここで実行
    }

    public function failed(\Throwable $e): void
    {
        // 失敗時の記録や通知など
    }
}

// Controller例（要点のみ）
Example::create([ 'status' => 'pending' ]);
ExampleJob::dispatch($id); // このタイミングでjobsテーブルにINSERTされる、すぐにレスポンス返却

よくあるつまずきポイント

  • ワーカー未起動: queue:work を立ち上げ忘れでジョブが実行されない
  • 接続未設定: .env の QUEUE_CONNECTION が誤り
  • タイムアウト/リトライ: デフォルト値のままで重い処理が落ちる
  • コード更新後の再起動: php artisan queue:restart を忘れて古いコードが実行される

運用の一言メモ（本番）

  • 本番ではSupervisorなどでWorkerを常駐・監視するのが一般的です（詳細は公式ドキュメントを参照）。

まとめ

  • Queueは「重い/不安定/待たせたくない」処理を裏側に回すための標準機能
  • 最小構成はDatabaseキュー+queue:workで十分に始められる
  • 設計の鍵は「受付と実処理の分離」「失敗時の再試行・後処理」
  • 次のアクション: まず1つの重い処理をジョブ化して、開発環境で queue:work を試す

Discussion