Работа с очередями (Queue) в Laravel 11: руководство для начинающих

Введение

При разработке веб-приложения часто возникают задачи, выполнение которых в рамках одного HTTP-запроса занимает слишком много времени (например, разбор и сохранение большого файла CSV, отправка писем и др.). К счастью, Laravel позволяет легко создавать задания (jobs) и отправлять их в очередь (queue) для асинхронной обработки в фоновом режиме (Очереди Laravel 11.x | Laravel Russian Community). Перемещая трудоемкие операции в очередь, приложение быстрее завершает обработку основного запроса и мгновенно возвращает ответ пользователю, в то время как тяжелая работа выполняется параллельно вне основного потока (Очереди Laravel 11.x | Laravel Russian Community).
В этой статье мы рассмотрим основные понятия системы очередей Laravel (очередь, задание, обработчик), разберемся, зачем они нужны, и покажем, как настроить очереди в Laravel 11 на практике: от выбора драйвера до создания и выполнения jobs, запуска worker-процесса и мониторинга очередей.

Основные понятия очередей Laravel

Очередь (Queue): механизм для отложенного выполнения задач. Очередь хранит список задач (сообщений) в порядке поступления; каждая задача содержит информацию о том, что и как нужно выполнить (Очереди с Laravel - это просто | OTUS). Laravel предоставляет унифицированный API для работы с разными реализациями очередей: от баз данных до Redis, Beanstalkd или Amazon SQS (Очереди Laravel 11.x | Laravel Russian Community). Вы можете выбрать удобный драйвер очереди и Laravel будет добавлять задачи в соответствующее хранилище (например, таблицу БД или память Redis).

Задание (Job): отдельная задача, которая должна быть выполнена в фоне. В Laravel задание представлено классом (в пространстве имен App\Jobs), обычно реализующим интерфейс ShouldQueue. В коде задания вы описываете конкретную работу, которую нужно выполнить (отправить письмо, обработать изображение, пересчитать статистику и т.д.). Когда задание отправляется в очередь, оно сохраняется в хранилище очереди и ожидает выполнения.

Обработчик очереди (Worker): фоновый процесс, который постоянно слушает очередь и извлекает новые задания для выполнения. Worker запускается отдельной командой Artisan и работает непрерывно, беря задачи из очереди по одной и выполняя их код. Проще говоря, worker - это “работник”, обслуживающий очередь: он получает задачи из очереди и выполняет соответствующие действия (Очереди с Laravel - это просто | OTUS). Без запущенного worker ваши задания из очереди не будут выполнены, поэтому этот процесс должен работать постоянно (особенно в продакшене).

Зачем использовать очереди?

Главная причина использовать очереди: повышение производительности и отзывчивости приложения. За счёт переноса тяжёлых операций в фон приложения увеличивается скорость работы: пользователь получает ответ практически мгновенно, а ресурсоёмкая логика выполняется асинхронно в фоне (Очереди с Laravel - это просто | OTUS). Например, вместо ожидания 5–10 секунд, пока сервер отправит email при регистрации, пользователь сразу увидит подтверждение, а само письмо отправится чуть позже в фоне. Кроме того, очереди помогают приложению масштабироваться и обрабатывать больше нагрузок. Вы можете запускать несколько worker-процессов параллельно, благодаря чему больше задач будут выполняться одновременно (Очереди с Laravel - это просто | OTUS). Это позволяет обслуживать больше пользователей без увеличения времени отклика: просто добавляя дополнительных рабочих, вы увеличиваете пропускную способность фоновой обработки. Также система очередей обеспечивает надёжность: если выполнение задания завершится неудачно, Laravel отметит его как проваленное, и вы сможете повторить попытку или обработать ошибку отдельно (не влияя на основной пользовательский поток). Итак, очереди решают проблемы длительных операций и делают приложение более быстрым и устойчивым. Теперь перейдём к практике их использования в Laravel 11.

Выбор и настройка драйвера очереди

Laravel поддерживает различные драйверы очередей (провайдеры хранилища), включая sync (синхронное выполнение, без отложенной очереди), database (реляционная БД), Redis, Beanstalkd, Amazon SQS и другие (Очереди Laravel 11.x | Laravel Russian Community). По умолчанию в .env файле нового приложения Laravel параметр QUEUE_CONNECTION равен sync, что означает выполнение задач сразу, без постановки в очередь. Чтобы включить полноценную очередь, необходимо выбрать и настроить подходящий драйвер в конфигурации. Для начала, в целях простоты, используем драйвер database (базу данных): он не требует установки дополнительных сервисов. Убедитесь, что у вас настроено подключение к базе данных в Laravel. Далее выполните миграцию для таблицы очереди: Laravel имеет специальную миграцию для хранения заданий. Если такая таблица (jobs) ещё не создана, сгенерируйте миграцию командой Artisan и примените её:

php artisan queue:table   # сгенерировать миграцию для таблицы jobs
php artisan migrate       # выполнить миграцию, создаст таблицу jobs

После этого в файле окружения .env укажите драйвер очереди database:

QUEUE_CONNECTION=database

Теперь Laravel будет сохранять отправленные в очередь задания в таблицу jobs вашей базы данных. (Для альтернативных драйверов требуются иные настройки: например, для Redis нужно настроить соединение Redis в config/database.php и установить расширение PHP Redis или пакет predis/predis (Очереди Laravel 11.x | Laravel Russian Community). В случае SQS или Beanstalkd нужно добавить соответствующие зависимости Composer (Очереди Laravel 11.x | Laravel Russian Community) и задать креденшлы. Но эти варианты выходят за рамки базового руководства.)

💡 Примечание: При разработке вы можете оставить QUEUE_CONNECTION=sync для простоты отладки: задания будут выполняться сразу, как обычный вызов метода. Однако для тестирования реальной очереди (и в продакшене) необходимо переключиться на асинхронный драйвер (например, database или redis) и запустить worker.

Создание и отправка задания (Job) в очередь

После настройки драйвера можно создавать задачи и ставить их в очередь. Предположим, мы хотим отправлять приветственное письмо новому пользователю после регистрации, эту отправку мы сделаем через очередь, чтобы не задерживать процесс регистрации.

1. Создание класса задания. Laravel предоставляет Artisan-команду для генерации класса Job. Выполним в консоли:

php artisan make:job SendWelcomeEmail

Laravel создаст файл с классом задания в директории app/Jobs. По умолчанию класс будет реализовывать интерфейс ShouldQueue, а внутри будут заготовлены методы __construct (конструктор) и handle (логика выполнения). Откроем файл app/Jobs/SendWelcomeEmail.php, он может выглядеть примерно так:

<?php
namespace App\Jobs;
use App\Models\User;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;
class SendWelcomeEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
    protected $user;
    public function __construct(User $user)
    {
        // Получаем модель пользователя, которому будем отправлять письмо
        $this->user = $user;
    }
    public function handle()
    {
        // Логика отправки письма
        Mail::to($this->user->email)
            ->send(new WelcomeEmail($this->user));
    }
}

В этом примере наше задание получает пользователя в конструкторе и в методе handle() отправляет ему email (через Mailable WelcomeEmail). Класс WelcomeEmail (находится в app/Mail) - это обычный Mailable, который вы могли бы сгенерировать командой php artisan make:mail WelcomeEmail и настроить шаблон письма. Для простоты деталей Mail опущены, главное здесь: сам факт отправки письма внутри задания. Обратите внимание на использование интерфейса ShouldQueue: он сообщает Laravel, что это задание должно выполняться асинхронно через очередь, а не сраз (Очереди Laravel 11.x | Laravel Russian Community)】. Также в классе используются трейт-методы Dispatchable, Queueable, InteractsWithQueue и SerializesModels: они подключают к классу задания готовую функциональность Laravel (для добавления в очередь, взаимодействия с очередью и серилизации модели пользователя для безопасной передачи через очередь).

2. Отправка задания в очередь. После того как класс задания создан и реализован, его можно поставить в очередь из любого места вашего кода (например, из контроллера, обработчика события или даже из Artisan-команды). В нашем случае, после успешной регистрации нового пользователя, добавим отправку задания SendWelcomeEmail в очередь. Предположим, у нас есть метод контроллера регистрации пользователя:

// После валидации и создания пользователя...
$user = User::create([
    'name'  => $data['name'],
    'email' => $data['email'],
    'password' => Hash::make($data['password']),
]);
// Помещаем задачу отправки письма в очередь
SendWelcomeEmail::dispatch($user);

Здесь вызывается статический метод dispatch() у нашего класса задания. Этот метод (предоставляется трейтом Dispatchable) упаковывает объект задания и отправляет его в настроенную очеред (How To Work With Queues And Jobs In Laravel 11)】. В результате новая запись появится в таблице jobs (для драйвера database) или в памяти Redis и т.п., то есть задание сохраняется для последующей обработки. Вы также можете использовать функцию-хелпер dispatch() или фасад Queue для отправки, но вызов MyJob::dispatch() - наиболее читаемый и рекомендуемый способ.

💡 Совет: В методе dispatch() можно указывать дополнительные параметры, например очередь или подключение, если вы хотите отправить задание не в очередь по умолчанию. Пример: SendWelcomeEmail::dispatch($user)->onQueue('emails'); отправит задание в именованную очередь `email (Очереди Laravel 11.x | Laravel Russian Community)8】. Однако для простоты у начинающих можно обойтись очередью по умолчанию. После dispatch'а управление сразу возвращается к вашему коду: задание пока не выполнено, оно просто ожидает в очереди. Чтобы его выполнить, необходимо запустить worker.

Запуск обработчика очереди (Worker)

Теперь, когда задание отправлено в очередь, его должен подобрать и выполнить worker. Laravel предоставляет Artisan-команду для запуска воркера:

php artisan queue:work

Эта команда запускает постоянный процесс, который начинает прослушивать очередь и вытаскивать из неё задания для выполнен (Очереди Laravel 11.x | Laravel Russian Community) (Очереди Laravel 11.x | Laravel Russian Community)3】. После запуска queue:work процесс не завершится автоматически: worker будет работать бесконечно, пока вы не остановите его (Ctrl+C) или не закроете терминал. В ходе работы вы будете видеть в консоли вывод о выполненных задачах (добавьте флаг -v или --verbose, чтобы видеть ID заданий в outpu (Очереди Laravel 11.x | Laravel Russian Community)9】.

Для тестирования на локальной машине откройте второй терминал/вкладку: в одном выполняйте обычные запросы (например, php artisan serve для запуска сервера), а в другом запустите php artisan queue:work. Теперь при создании нового пользователя ваше задание попадёт в очередь, и запущенный worker сразу же его вытащит и выполнит (отправит письмо).

В production-среде worker должен работать постоянно в фоне. Простого запуска команды в терминале недостаточно, так как при выходе из сессии он остановится. Laravel рекомендует использовать менеджер процессов (Supervisor на Linux) для управления worker'а (Очереди Laravel 11.x | Laravel Russian Community)3】. С помощью Supervisor вы можете настроить автоматический перезапуск воркера при сбоях и запуск нескольких параллельных процессов. Альтернативно, можно воспользоваться пакетом Laravel Horizon (если вы используете драйвер Redis), Horizon сам управляет процессами воркеров. Выберите подходящий способ, чтобы гарантировать постоянную работу фоновых обработчиков очереди.

Несколько полезных команд для управления очередями через Artisan:

• php artisan queue:listen: тоже запускает воркер, но перезапускает фреймворк при каждом задании. Проще использовать queue:work, поэтому queue:listen обычно не применяют.
• php artisan queue:restart: аккуратно перезапускает все запущенные воркеры (они завершат текущие задания и перезапустятся). Полезно при развёртывании новой версии кода.
• php artisan queue:stop: останавливает воркер после завершения текущего задания. Можно использовать для контролируемого выключения процесса.

Мониторинг и управление очередью

После настройки очереди и запуска воркера важно уметь отслеживать состояние задач: выполнены ли они успешно, не случилось ли ошибок, сколько задач скопилось в очереди и т.д. Laravel предоставляет несколько средств для мониторинга очередей.

1. Проверка и повтор ошибок. Если какое-то задание завершается с исключением, Laravel пометит его как проваленное и сохранит в специальном хранилище неудачных задач (по умолчанию это таблица failed_jobs в БД, если вы выполните миграцию для неё командой php artisan queue:failed-table). Просмотреть список неудачных задач можно командой:

php artisan queue:failed

Каждая запись содержит информацию о классе задания, данных и сообщении об ошибке. Разобрав причину, вы можете повторно запустить провалившееся задание командой php artisan queue:retry <ID_задачи> или удалить его из списка через `php artisan queue:forget <ID (How To Work With Queues And Jobs In Laravel 11)5】. В логах Laravel (storage/logs) также фиксируются ошибки заданий, не забывайте их проверять при отладке.

2. Laravel Horizon (для Redis). Для продакшена, где требуется удобный мониторинг в реальном времени, существует пакет Laravel Horizon - это красивая панель мониторинга и инструмент управления очередями на базе Red (Очереди Laravel 11.x | Laravel Russian Community)3】. Horizon предоставляет веб-интерфейс, где вы можете видеть текущие задания, завершённые и проваленные задачи, статистику по очередям, время выполнения и т.д. Horizon также упрощает управление воркерами: вы можете настроить число потоков, приоритеты и другие параметры через конфигурацию. Чтобы использовать Horizon, нужно переключиться на драйвер redis и установить пакет:

composer require laravel/horizon

После установки опубликйте конфигурацию Horizon и запустите его: php artisan horizon. В браузере по адресу вашего приложения /horizon откроется dashboard. Все задачи, отправленные в Redis-очередь, будут видны там в режиме реального времени. Подробнее о возможностях Horizon читайте в документации Laravel.

3. Общий мониторинг очереди. Даже без Horizon вы можете оценивать состояние очереди. Например, для драйвера database количество невыполненных заданий - это просто число записей в таблице jobs. Вы можете настроить периодическое логирование размера очереди или использовать метрики (например, через Prometheus + Grafana) для отслеживания. Если очередь резко растёт, значит воркеры не успевают обрабатывать задачи, стоит увеличить число воркеров или мощности. В Laravel также есть Events для очередей: можно подписаться на события начала и завершения задач, чтобы собирать статистику самостоятельно (но это уже более продвинутые сценарии).

На этом базовое знакомство с очередями Laravel 11 можно завершить. Мы рассмотрели, что такое очереди, задания и воркеры, зачем они нужны и как их настроить. Подводя итог:

• Очереди позволяют выполнять задачи асинхронно, разгружая основное приложение.
• Jobs (задания) - это классы, где описана логика задачи; их можно ставить в очередь для отложенного выполнения.
• Workers: фоновые процессы, обрабатывающие очередь; без них задания не выполнятся. Мы научились настраивать очереди (на примере драйвера базы данных), создавать задания и отправлять их в очередь, запускать воркер для обработки, а также отслеживать выполнение задач и справляться с неудачными заданиями. Использование очередей сделает ваше Laravel-приложение более быстрым, масштабируемым и устойчивым к нагрузкам. Экспериментируйте с этой мощной функцией Laravel и переходите на новые уровни производительности!