罗罗编程学习记录
本页内容 展开查看

06.5.4.9 队列驱动与 Horizon

所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.5 PHP 后端 / 06.5.4 Laravel

覆盖范围

  • 队列连接与驱动差异、任务类与 Queueable 用法
  • 重试次数、退避策略、超时与失败任务处理
  • 队列优先级、并发消费与任务序列化要求
  • Horizon 架构、配置、指标看板与积压告警

队列基础概念(投递消费、幂等、延迟任务、死信处理)见 06.5.1.4 缓存队列与任务调度;本页聚焦 Laravel 队列配置纵深与 Horizon 运维。

06.5.4.9-001 Laravel 支持哪些队列连接,各自适用场景是什么?

一句话结论

Laravel 队列连接由 config/queue.php 的 connections 定义,常见 sync、database、redis、sqs、amqp 等;sync 用于调试与同步执行,database 适合低量无中间件环境,redis 是自建队列的主力,sqs/amqp 适合托管消息与复杂路由。

概念解释

连接(connection)是队列驱动的配置入口,队列(queue)是同一连接下的逻辑分组。不同驱动在延迟精度、可见性超时、失败重试语义上实现不同,选型取决于现有中间件、吞吐量与运维成本。

原理流程

  1. 读取 config/queue.php 的 default 连接名。
  2. 投递任务时按任务指定的连接或默认连接序列化入队。
  3. queue:work 进程按连接配置拉取任务。
  4. 驱动差异体现在消息存储、延迟到期检查与认领/释放机制上。

代码或图示

// config/queue.php 节选:多连接定义
'default' => env('QUEUE_CONNECTION', 'redis'),
'connections' => [
    'database' => ['driver' => 'database', 'table' => 'jobs', 'queue' => 'default', 'retry_after' => 90],
    'redis' => ['driver' => 'redis', 'connection' => 'default', 'queue' => 'default', 'retry_after' => 90],
],

常见误区

  • 把队列名和连接名混为一谈:连接是中间件通道,队列是通道内的逻辑桶,二者可独立指定。
  • 在生产环境用 database 连接扛高并发:数据库表轮询压力大,吞吐与延迟都不如专用队列中间件。

追问

  • retry_after 与任务 timeout 是什么关系?答:retry_after 是驱动层面任务被认领后多久未完成重新放回队列的秒数,任务自身 timeout 是 worker 判超时的上限;前者应大于后者,避免未跑完被重复认领。默认值与字段名以当前版本 config/queue.php 为准。
  • 如何在不换代码的前提下切换连接?答:改 .env 中 QUEUE_CONNECTION,任务代码通过连接配置解析,不改投递语句。

06.5.4.9-002 任务类(Job)由哪些接口与特征组成?

一句话结论

可入队任务类实现 ShouldQueue 接口(或继承 Queueable 配套的基类),内部 handle 方法由 worker 通过容器解析执行;Queueable 特征提供指定连接、队列、延迟、超时等链式方法。

概念解释

实现 ShouldQueue 只声明“应异步执行”,任务本身仍是普通 PHP 类,依赖由容器注入。handle 方法的参数解析与控制器动作类似,可声明类型提示由容器提供。

原理流程

  1. 定义任务类,实现 Illuminate\Contracts\Queue\ShouldQueue。
  2. 引入 Queueable 特征,获得连接/队列/延迟等配置方法。
  3. 投递时序列化任务属性入队。
  4. worker 反序列化后经容器解析 handle 依赖并执行。

代码或图示

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class SendOrderNotification implements ShouldQueue
{
    use InteractsWithQueue, Queueable;

    public function __construct(public readonly Order $order) {}

    public function handle(Notifier $notifier): void
    {
        $notifier->notifyOrder($this->order);
    }
}

常见误区

  • 在任务构造函数里做重业务:构造函数在投递侧执行,重逻辑会拖慢主请求;重初始化应放 handle。
  • 让任务持有请求对象或会话:worker 进程没有请求上下文,序列化与反序列化后取不到会话数据。

追问

  • ShouldQueue 接口里有方法需要实现吗?答:它是标记接口(marker interface),不强制实现方法;行为配置通过类属性与 Queueable 方法提供,具体签名以当前版本契约为准。
  • 不实现 ShouldQueue 的类能被投递吗?答:不能作为队列任务分发;直接调用 handle 可在本地同步执行调试,但不走队列流程。

06.5.4.9-003 如何在投递时指定连接、队列与延迟?

一句话结论

通过 dispatch(...)->onConnection(...)->onQueue(...)->delay(...) 链式方法,或在任务类属性上预设;连接决定走哪个驱动,队列决定逻辑分组,延迟决定任务何时可被消费。

概念解释

链式配置在投递时覆盖类内默认值。队列分组便于按优先级分配不同 worker 数量:邮件、通知等低优先队列与支付等高优先队列分开消费。

原理流程

  1. 构造任务实例并调用 dispatch。
  2. 链式调用覆盖连接、队列、延迟参数。
  3. 序列化时把这些参数写入任务消息头。
  4. worker 按消息头中的队列名拉取。

代码或图示

SendOrderNotification::dispatch($order)
    ->onConnection('redis')
    ->onQueue('notifications')
    ->delay(now()->addMinutes(2));

// 类内预设默认值
class ReportExport implements ShouldQueue
{
    public string $connection = 'redis';
    public string $queue = 'exports';
}

常见误区

  • 延迟值传字符串而不是 DateTime/Carbon:驱动对延迟参数类型有要求,时间对象或秒数更稳妥,具体接受类型以驱动实现为准。
  • 用 delay 实现业务定时补偿:延迟到期后任务仍只执行一次,状态补偿应在 handle 内校验业务状态。

追问

  • 闭包任务如何指定队列?答:dispatch(function () { ... })->onQueue('...'),闭包同样被序列化;生产环境更推荐独立任务类以便追踪与重试。
  • 同一任务能否同时进多个队列?答:一次投递只进入一个队列;需要多路消费应分别投递或在投递侧按场景选择队列名。

06.5.4.9-004 任务重试次数 tries 与 attempts 如何配合?

一句话结论

类属性 tries(或命令行 --tries)设置最大尝试次数,运行时 $job->attempts() 返回当前是第几次执行;超过上限仍失败的任务进入失败任务流程,不会无限重试。

概念解释

每次 worker 认领任务算一次尝试。抛出异常后任务按退避策略回到队列,attempt 计数加一;达到 tries 上限仍未成功,任务被标记失败并写入失败存储。

原理流程

  1. worker 认领任务,attempt 为当前已尝试次数。
  2. handle 执行成功,任务从队列删除。
  3. 执行抛异常,按退避时间重新入队。
  4. attempt 达到 tries 上限,任务转入失败存储。

代码或图示

class RetryableImport implements ShouldQueue
{
    public int $tries = 5;

    public function handle(Importer $importer): void
    {
        if ($this->job?->attempts() === 1) {
            // 首次执行可做一次性准备动作
        }
        $importer->run($this->payload);
    }
}

常见误区

  • 以为 tries = 1 表示执行一次后永久成功:它只允许一次尝试,失败即进入失败流程。
  • 在 handle 里依赖 attempt 做幂等分支却不持久化去重:重试场景下分支判断不可靠,幂等仍需业务键去重。

追问

  • 命令行 --tries 与类属性谁优先?答:命令行参数作用于 worker 消费的队列范围,任务类属性针对单个任务;二者优先级合并规则以当前版本队列源码为准,排查时以实际生效值为准。
  • 不限重试次数可以吗?答:不建议,缺少上限的毒消息会反复占用 worker;可恢复错误也应配合退避与最终失败处理。

06.5.4.9-005 退避(backoff)策略有哪几种写法?

一句话结论

退避可以是固定秒数、递增秒数数组,或接收任务实例的闭包;数组按尝试次数依次取间隔,闭包可根据异常类型与业务状态动态返回等待秒数。

概念解释

退避决定失败后多久重新入队。固定间隔实现简单,数组能实现指数/阶梯退避,闭包适合区分瞬时故障(限流、网络抖动)与永久错误(数据非法)的场景。

原理流程

  1. 任务执行失败抛出异常。
  2. 框架读取任务的 backoff 配置。
  3. 数组按 attempt 取下一个间隔,闭包调用后返回秒数。
  4. 任务带延迟重新入队,等待到期再被认领。

代码或图示

class FlakyApiCall implements ShouldQueue
{
    // 第一次失败等 3 秒,之后 10、30、60 秒
    public array $backoff = [3, 10, 30, 60];

    // 动态退避示例:闭包接收任务与异常
    // public function backoff(int $attempt, \Throwable $e): int { return min(60, 2 ** $attempt); }
}

常见误区

  • backoff 数组长度短于 tries:超出数组的取值行为以框架实现为准,建议数组长度与最大尝试次数对齐。
  • 所有异常都用相同退避:参数错误、数据缺失这类永久失败应快速失败进入失败流程,而不是反复重试。

追问

  • backoff 与 retry_after 冲突时听谁的?答:退避是重新入队的延迟时间,retry_after 是驱动层面未完成任务的可见性超时,两者作用环节不同,需分别配置且 retry_after 大于预计最长执行时间。
  • 闭包退避能返回多少?答:返回等待秒数(int),具体返回类型与参数签名以当前版本任务基类文档为准,不确定时标注待确认并核对源码。

06.5.4.9-006 任务超时 timeout 与 retryUntil 分别约束什么?

一句话结论

timeout 限制单次执行的最大秒数,超时后 worker 中断该任务;retryUntil 限制任务从入队起的最晚可重试时间,超过该时间即使未达 tries 上限也不再重试。

概念解释

timeout 是单次运行上限,保护 worker 不被卡死任务长期占用;retryUntil 是整体生命周期上限,适合“超过业务时间窗就无意义”的任务(例如验证码、限时通知)。

原理流程

  1. worker 认领任务前配置单次 timeout。
  2. 执行中超过 timeout,任务判超时并进入重试/失败流程。
  3. 每次重试前检查 retryUntil 时间点。
  4. 已过截止时间的任务不再入队,直接失败。

代码或图示

class LimitedTimePromotion implements ShouldQueue
{
    public int $timeout = 60;

    public function retryUntil(): \DateTime
    {
        return now()->addHours(2);
    }
}

常见误区

  • timeout 设得过大:卡死任务长时间占 worker,应配合外部进程监控与内存限制。
  • 只配 tries 不配 retryUntil:有时间窗要求的任务在窗门外仍被反复重试,产生无意义副作用。

追问

  • 超时后任务一定会被重试吗?答:取决于剩余尝试次数与 retryUntil;超时视为执行失败,按重试策略处理,达到上限则进失败存储。
  • worker 命令行 --timeout 与任务属性谁优先?答:任务级属性覆盖 worker 默认值;生效顺序以当前版本队列源码为准,部署前在测试环境核对一次。

06.5.4.9-007 失败任务如何存储、查看与手动重试?

一句话结论

失败任务写入失败存储(默认 failed_jobs 表,redis 等驱动可配置对应存储),用 queue:failed 查看列表,queue:retry 按 ID 或全量重试,queue:forget 清除单条;失败时可注册 failed 监听做补偿告警。

概念解释

失败存储保留任务载荷、异常堆栈、连接与队列名、失败时间。重试时按原始载荷重新序列化入队,attempt 计数是否清零以当前版本行为为准(待确认)。

原理流程

  1. 任务达到重试上限或被判永久失败。
  2. 框架把任务快照与异常写入失败存储。
  3. 运维用失败命令排查载荷与堆栈。
  4. 修复问题后按 ID 重试,或丢弃无法补偿的任务。

代码或图示

php artisan queue:failed
php artisan queue:retry 17
php artisan queue:forget 17
php artisan queue:flush
// 任务内失败钩子示例
public function failed(\Throwable $exception): void
{
    report($exception);
    // 记录业务补偿标记,通知运维渠道
}

常见误区

  • 把失败表当补偿队列:失败任务不会自动重放,必须有人或流程触发 retry;永久错误直接 flush 会丢失现场。
  • 重试前不看异常堆栈:同一环境问题未修复时重试只会再次失败,毒消息重新积压。

追问

  • 失败表需要迁移吗?答:database 连接作为失败存储时需先执行 queue:failed-table 迁移(命令名以当前版本为准);驱动自带失败存储时不依赖本地表。
  • 如何批量重试某一队列的失败任务?答:queue:retry 支持按 ID 或 all;按队列筛选重试的参数形式以命令帮助 queue:retry --help 为准。

06.5.4.9-008 队列优先级如何通过多队列消费实现?

一句话结论

同一 worker 按命令行 --queue 列出的顺序优先消费靠前队列;高优先队列分配独立 worker 池可避免被慢任务堵塞,队列名只是逻辑分组,优先级体现在消费顺序与并发分配上。

概念解释

Laravel 队列本身不提供消息级优先级字段(具体能力以驱动为准),优先级通过队列划分实现:--queue=high,default 表示只要 high 有任务就先取 high,high 为空再取 default。

原理流程

  1. 投递时把不同业务写入 high、default、low 队列。
  2. worker 按队列名顺序循环认领。
  3. 高优先队列可单独启动更多 worker 进程。
  4. 慢任务集中在低优先队列,不阻塞主链路。

代码或图示

# 先消费 high,再消费 default
php artisan queue:work redis --queue=high,default

# 低优先队列独立进程,限制并发
php artisan queue:work redis --queue=low --tries=3 --max-jobs=1000

常见误区

  • 把所有任务写进 default 队列再谈优先级:没有队列划分,消费顺序无法按业务区分。
  • 高优先队列放了大批量慢任务:即使先被消费,也会长时间占用 worker,慢任务应落到低优先队列异步处理。

追问

  • 队列名能动态生成吗?答:可以用字符串拼接,但应枚举受控的队列名,避免任务散落在不可追踪的临时队列。
  • 多连接如何分配 worker?答:每个 queue:work 进程绑定一个连接,跨连接优先级需要分别规划进程与机器资源。

06.5.4.9-009 worker 进程的并发与生命周期参数有哪些?

一句话结论

queue:work 通过 --queue、--tries、--timeout、--sleep、--memory、--max-jobs、--max-time 等参数控制消费范围、重试、空闲等待、内存上限与进程回收;并发度由启动的进程数量(或进程管理器)决定。

概念解释

单进程串行消费认领的任务;并行度等于 worker 进程数乘以运行时并发能力。--sleep 控制队列为空时轮询间隔,--memory 与 --max-jobs 防止常驻进程内存持续增长后被回收重启。

原理流程

  1. 启动 worker 绑定连接与队列。
  2. 循环认领任务、执行、删除或回队。
  3. 空闲时按 sleep 间隔等待。
  4. 达到内存、任务数或时间上限后进程退出,由进程管理器拉起新进程。

代码或图示

php artisan queue:work redis \
  --queue=high,default \
  --tries=3 \
  --timeout=60 \
  --sleep=3 \
  --memory=128 \
  --max-jobs=1000 \
  --max-time=3600

常见误区

  • 用 queue:listen 与 queue:work 等同:listen 每个任务重建引导,性能较低;work 常驻复用引导,参数语义有差异,具体行为以当前版本命令文档为准。
  • 不设内存上限:常驻 worker 缓慢泄漏最终耗尽内存,应由 supervisor 类管理器按上限回收。

追问

  • 如何水平扩并发?答:增加 worker 进程数或容器副本,按队列吞吐与单任务耗时估算;注意下游数据库、外部接口的连接与限流上限。
  • --sleep=0 有什么风险?答:空队列时高频轮询增加中间件与 CPU 压力,应保留合理等待间隔。

06.5.4.9-010 任务序列化对属性有什么要求?

一句话结论

入队任务的属性必须可被 PHP 序列化;Eloquent 模型通过 SerializesModels 特征处理为模型标识与类名,反序列化时重新从数据库读取,不能把连接、请求、闭包、资源句柄作为持久属性。

概念解释

序列化发生在投递侧,反序列化发生在 worker 侧。持有不可序列化对象会在入队时失败;模型引用序列化只保存主键与连接名,避免把整行数据快照固化。

原理流程

  1. 任务类引入 SerializesModels(队列基类通常已包含)。
  2. 序列化时 Eloquent 属性被转换为模型引用结构。
  3. 消息入队存储。
  4. worker 反序列化时按引用重新加载模型;若记录已被删除,按框架行为抛出或置空(待确认版本细节)。

代码或图示

use Illuminate\Queue\SerializesModels;

class ShipMail implements ShouldQueue
{
    use Queueable, SerializesModels;

    public function __construct(public readonly User $user) {}

    public function handle(Mailer $mailer): void
    {
        $mailer->to($this->user->email)->send(new WelcomeMail());
    }
}

常见误区

  • 把请求快照、上传文件句柄、缓存连接对象存为任务属性:不可序列化或反序列化后失效。
  • 依赖投递时刻的模型状态:反序列化重新读库,任务执行时看到的是最新数据,快照需求应在任务构造时显式拷贝标量字段。

追问

  • 模型被软删除或删除后任务还能跑吗?答:反序列化按引用加载,记录不存在时的处理以当前版本 SerializesModels 实现为准;关键任务应在 handle 内校验记录存在性。
  • 闭包任务序列化有什么限制?答:闭包只能捕获可序列化变量,且调试与追踪能力弱于独立任务类,生产建议使用任务类。

06.5.4.9-011 任务与数据库事务的提交时机如何配合?

一句话结论

默认情况下事务未提交时投递的任务可能在回滚后仍被执行;任务实现 ShouldQueueAfterCommit(或配置 after_commit)可让任务在所属数据库事务提交后才入队,避免回滚后产生孤儿异步动作。

概念解释

Web 请求常在事务内写库并投递任务。若投递先于提交,事务回滚但任务已入队,worker 读到的数据与业务状态不一致。after commit 模式把入队动作延迟到提交成功之后。

原理流程

  1. 事务内写业务数据并分发任务。
  2. 默认模式:任务立即序列化入队。
  3. 启用 after commit:任务先挂起,等待当前事务提交。
  4. 提交成功后统一入队;回滚则任务不入队。

代码或图示

use Illuminate\Contracts\Queue\ShouldQueueAfterCommit;

class NotifyAfterOrder implements ShouldQueueAfterCommit
{
    // 事务提交后才入队
    public function __construct(public readonly Order $order) {}
}

// 全局配置项名称以当前版本 config/queue.php 为准:
// 'after_commit' => true,

常见误区

  • 在事务里发邮件、扣库存却不关心中途回滚:回滚后副作用已经发生,无法靠数据库回滚撤销。
  • 全局开启 after commit 后又依赖任务立即执行:入队被推迟到提交点,耗时会顺延到事务结束之后。

追问

  • 哪些场景不适合 after commit?答:事务很长或需要先投递再做库内补偿的流程;应评估入队延迟对业务时效的影响。
  • 事件监听器队列化受同一规则影响吗?答:队列化监听器遵循相同的事务提交配置,行为随任务投递链路一致,具体以事件与队列源码为准。

06.5.4.9-012 任务幂等在队列纵深层面还需要哪些防护?

一句话结论

重试与重复投递可能让同一任务执行多次,业务侧需要持久化去重键、唯一约束或分布式锁占位;队列框架保证的是投递与重试机制,不保证“恰好执行一次”。

概念解释

去重键用业务单号或事件 ID,先占记录再处理;重复执行时检测到已处理状态直接跳过。与 06.5.1.4 中的幂等基础题衔接,这里聚焦任务内的落地结构。

原理流程

  1. handle 入口按业务键查询处理记录。
  2. 已处理则直接返回成功。
  3. 未处理则加唯一约束占位或抢锁。
  4. 执行副作用并标记完成;失败释放占位供重试。

代码或图示

public function handle(OrderService $orders): void
{
    $lock = Cache::lock("job:notify:{$this->order->id}", 60);

    if (! $lock->get()) {
        return; // 其他 worker 正在处理
    }

    try {
        $orders->notify($this->order);
    } finally {
        $lock->release();
    }
}

常见误区

  • 用任务消息 ID 当幂等键:重试时消息 ID 可能变化,应使用稳定业务标识。
  • 去重记录只存内存:进程重启后丢失,去重必须持久化到数据库或共享缓存。

追问

  • 幂等跳过与失败重试如何区分?答:已成功处理的记录跳过;执行中途失败的占位应释放或标记可重试,不能把未完成状态记为成功。
  • 外部接口本身不幂等怎么办?答:优先使用接口侧的幂等请求号;否则在本地先记录请求与结果,重试前核对状态。

06.5.4.9-013 Horizon 是什么,与原生 queue:work 是什么关系?

一句话结论

Laravel Horizon 是基于 Redis 队列的可视化进程管理器与指标仪表盘,负责配置 supervisor、管理 worker 进程生命周期、采集吞吐与等待指标;底层仍是 Laravel 队列消费协议,horizon 命令替代手工启动多个 queue:work。

概念解释

Horizon 只支持 Redis 连接(支持范围以当前版本文档为准),它把进程拓扑、队列分配、内存/任务上限、监控面板集中到一处;原生 queue:work 适合无 Redis 或不需要面板的简单部署。

原理流程

  1. 安装 Horizon 并发布配置、迁移。
  2. horizon 命令按配置启动各 supervisor 与其管理的 worker 进程。
  3. worker 消费 Redis 队列并回传指标给 Horizon 存储。
  4. Web 仪表盘展示队列积压、吞吐、失败与进程状态。

代码或图示

# 启动 Horizon 守护进程
php artisan horizon

# 查看 Horizon 状态与进程
php artisan horizon:status

常见误区

  • 以为 Horizon 是独立队列协议:它仍是 Redis 队列的管理与观测层,任务类与队列代码无需为 Horizon 改写。
  • 在非 Redis 连接上期望 Horizon 面板:驱动支持范围受限,其他连接用原生 worker 与外部监控。

追问

  • Horizon 进程崩溃后谁拉起?答:Horizon 内部按 supervisor 配置管理子进程;宿主机仍需 systemd 或容器编排保证 horizon 主进程退出后被重启。
  • Horizon 面板如何鉴权?答:通过配置中的中间件/网关规则限制访问,具体配置项以当前版本 Horizon 文档为准。

06.5.4.9-014 Horizon 配置如何划分 supervisor、连接与队列?

一句话结论

config/horizon.php 中 defaults 定义 supervisor 模板(进程数、队列、内存、超时、最大任务数),environments 按环境覆写,balance 策略控制进程在多队列间的分配方式。

概念解释

supervisor 是一组 worker 的管理单元,可绑定连接与队列列表;balance 策略(simple 或 auto,具体取值以版本为准)决定队列负载不均时如何调整 worker 分配。

原理流程

  1. defaults 中定义每个 supervisor 的进程数、队列、try、timeout。
  2. environments 按 local/production 覆盖配置。
  3. Horizon 启动时为每个 supervisor 拉起对应数量的 worker。
  4. 运行中按 balance 策略与队列积压调整消费分配。

代码或图示

// config/horizon.php 节选结构(字段名以实际发布配置为准)
'supervisors' => [
    'high-priority' => [
        'connection' => 'redis',
        'queue' => ['high'],
        'processes' => 8,
        'tries' => 3,
        'timeout' => 60,
        'memory' => 128,
    ],
],
'balance' => 'simple',

常见误区

  • 把所有队列塞进一个 supervisor:进程数无法按队列负载分别调整,高优先与慢任务互相影响。
  • production 直接沿用 local 配置:本地与生产的进程数、内存上限应在 environments 中区分。

追问

  • processes 如何估算?答:按队列峰值任务数、单任务耗时与下游承载能力估算;先压测观察吞吐与等待时间,再调整副本。
  • balance=auto 与 simple 差异?答:simple 按固定队列顺序消费,auto 根据各队列积压动态调整进程分配;具体算法以 Horizon 源码为准。

06.5.4.9-015 Horizon 仪表盘能看到哪些核心指标?

一句话结论

面板按连接与队列展示吞吐(每分钟任务数)、等待时长(waits)、积压任务数、失败任务、最近任务详情与 worker 进程状态;指标用于判断消费能力是否跟得上投递速度。

概念解释

吞吐是已完成速率,等待是队列中任务从入队到被认领的停留时间,积压是当前待消费数量。等待与积压持续上升说明 worker 不足或存在慢任务/阻塞。

原理流程

  1. worker 执行任务时回传成功、失败与耗时数据。
  2. Horizon 聚合到按队列维度的指标存储。
  3. 仪表盘轮询或实时展示各队列指标。
  4. 运维按积压与等待定位扩容或排查慢任务。

代码或图示

# 命令行查看整体积压与状态(子命令以当前版本为准)
php artisan horizon:status
php artisan horizon:list

常见误区

  • 只看总吞吐不看队列维度:某个低优先队列积压可能被整体平均值掩盖。
  • 把等待时间等同于任务执行时长:等待是排队停留,执行耗时需结合任务记录与外部监控区分。

追问

  • 任务详情能看到载荷吗?答:面板展示任务类、队列、尝试次数与异常信息;载荷内容是否展开受序列化与配置限制,敏感字段不应进入任务载荷。
  • 指标保留多久?答:Horizon 指标存储有保留期配置(trim 规则),历史趋势需对接外部监控系统长期留存。

06.5.4.9-016 队列积压如何定位与扩容?

一句话结论

积压先按队列拆分定位慢任务或下游瓶颈,再判断是 worker 不足、任务卡死还是外部依赖拖慢;扩容手段是增加对应队列的 worker 副本,同时排查单任务耗时、失败重试风暴与中间件性能。

概念解释

积压是投递速率长期大于消费速率的结果。定位顺序:各队列积压量 → 单任务平均耗时 → 异常与重试次数 → 下游数据库/外部接口指标 → worker 内存与进程状态。

原理流程

  1. 查看各队列积压与等待时间,锁定异常队列。
  2. 抽样查看该队列任务类与最近失败记录。
  3. 检查 worker 日志、异常堆栈与下游依赖指标。
  4. 针对性扩容副本、修复慢任务或降级外部依赖。

代码或图示

// 在任务记录中统计耗时,便于定位慢任务
public function handle(Importer $importer): void
{
    $started = microtime(true);
    $importer->run($this->payload);
    logger()->info('import done', [
        'order' => $this->order->id,
        'elapsed_ms' => (int) ((microtime(true) - $started) * 1000),
    ]);
}

常见误区

  • 一积压就盲目加 worker:下游数据库连接与外部限流可能先到上限,扩容反而把依赖打垮。
  • 忽略重试风暴:失败任务反复重新入队会放大积压,应先止血永久失败任务。

追问

  • 慢任务导致的积压怎么拆?答:把大任务拆成可分批的小任务(按块处理、子任务投递),降低单任务占用时间;必要时独立队列与独立 worker 池。
  • 中间件自身积压怎么判断?答:对比投递侧速率与 worker 认领速率,结合 Redis/AMQP/云消息控制台的消息计数与消费组延迟。

06.5.4.9-017 失败任务告警与失败事件监听如何落地?

一句话结论

除人工查看失败表外,可注册队列失败事件监听(任务 failed 方法或全局 Queue::failing 回调),把异常、任务载荷摘要与队列信息推送到告警渠道;告警应区分可重试失败与永久失败。

概念解释

全局失败监听在任务失败钩子之前/之后触发(顺序以源码为准),适合统一上报异常与聚合指标;任务自身 failed 方法适合做单任务补偿标记与业务状态回写。

原理流程

  1. 任务执行最终失败。
  2. 框架调用任务 failed 方法(若定义)。
  3. 全局 failing 回调接收任务实例与异常。
  4. 监听内上报监控渠道并附队列、连接、attempt、业务标识。

代码或图示

use Illuminate\Support\Facades\Queue;

Queue::failing(function ($connection, $job, $exception) {
    report($exception);
    // 告警渠道携带队列名与任务类名,不回传敏感载荷
    logger()->error('queue job failed', [
        'connection' => $connection,
        'queue' => $job->resolveQueue()?->getQueue(),
        'job' => get_class($job),
    ]);
});

常见误区

  • 告警里直接打印完整任务载荷:可能包含手机号、地址等敏感字段,应只上报业务标识与异常摘要。
  • 只告警不区分严重级别:临时网络抖动与数据非法应分级,避免告警疲劳。

追问

  • 失败监听里能重试任务吗?答:可以再次投递新任务,但应在确认根因修复后执行;在失败钩子内自动重试会绕过 tries 上限。
  • 队列事件还能监听哪些?答:任务处理前后、失败、释放回队等事件可用事件监听或队列回调接入,具体事件清单以当前版本队列文档为准。

06.5.4.9-018 队列任务中的依赖注入与服务解析要注意什么?

一句话结论

worker 引导一次后复用容器,任务 handle 的依赖由容器按当前作用域解析;单例服务中持有请求级状态会跨任务残留,任务所需的状态应通过任务属性显式传入,不依赖 Web 请求上下文。

概念解释

与 06.5.4.1 服务容器与绑定解析 衔接:CLI/worker 上下文中没有 Request 实例,会话、当前登录用户等请求态必须在投递前固化为任务属性。

原理流程

  1. worker 启动时引导应用与容器。
  2. 每个任务反序列化后经容器解析 handle 依赖。
  3. 请求级服务按任务作用域重新构造。
  4. 任务结束清理作用域状态,避免带入下一任务。

代码或图示

class ReportExport implements ShouldQueue
{
    // 投递前固化用户标识,任务内按标识重新加载
    public function __construct(public readonly int $userId) {}

    public function handle(UserRepository $users): void
    {
        $user = $users->find($this->userId);
        // 不依赖 auth()->user() 或 session()
    }
}

常见误区

  • 任务 handle 里调用 auth()->user():worker 无登录上下文,取到的用户为空或残留。
  • 在单例服务里缓存任务中间产物:下一任务复用时读到上一任务的数据,应使用作用域对象或方法内局部变量。

追问

  • 队列任务能访问配置与缓存吗?答:可以,配置是进程级只读配置,缓存经客户端访问共享存储;不要把缓存连接对象本身存进任务属性。
  • 任务内构造服务与控制器有区别吗?答:解析协议一致,差别只在运行上下文:无 HTTP 请求、无会话、响应对象不存在。

06.5.4.9-019 延迟任务与定时投递在队列侧如何实现?

一句话结论

队列任务通过 delay 指定相对延迟;需要“到点执行”的任务入队时计算到期时间。驱动的延迟到期精度不同:redis 按排序集合到期判断,database 靠轮询扫描,托管消息按各自可见性超时实现。

概念解释

延迟任务不等于定时调度:调度器负责到点触发命令或投递任务,队列负责到期后被消费。与 06.5.4.12 Artisan 命令与调度任务 衔接,本页只看队列侧的延迟语义。

原理流程

  1. 投递时计算延迟时长或目标时间。
  2. 消息写入驱动的延迟结构。
  3. 到期前对 worker 不可见。
  4. 到期后进入可消费队列,被 worker 认领。

代码或图示

// 30 分钟后提醒
ReminderJob::dispatch($order)
    ->delay(now()->addMinutes(30));

// 定时调度中投递队列任务(示例)
// $schedule->job(new CloseExpiredOrder)->everyFifteenMinutes();

常见误区

  • 用大延迟替代业务状态校验:到期执行时业务状态可能已变化,handle 必须先校验是否还需要动作。
  • 假设延迟精度一致:不同驱动最小粒度与重启恢复行为有差异,关键超时场景要核对驱动实现。

追问

  • 延迟任务能取消吗?答:队列消息一旦入队不易按业务键精确撤回;常见做法是任务内校验业务状态后跳过执行,或在投递前用调度状态控制。
  • 驱动重启时延迟任务会丢吗?答:持久化驱动(redis、database、托管消息)消息落盘;纯内存驱动重启丢失,生产不应使用内存驱动。

06.5.4.9-020 队列上线前需要做哪些配置与运维检查?

一句话结论

上线前核对连接配置、失败表迁移、worker 进程管理、队列划分、超时与重试上限、监控告警与日志;上线后观察积压、等待、失败与内存趋势,确认进程管理器能回收与重启 worker。

概念解释

队列运维检查覆盖:中间件连通性、任务序列化兼容性、supervisor/worker 副本与资源上限、失败补偿流程、指标看板与告警阈值、日志脱敏。

原理流程

  1. 核对 config/queue.php 连接、默认队列、retry_after 与超时。
  2. 执行失败存储迁移或确认驱动失败存储可用。
  3. 按业务划分队列并配置 worker 进程与内存/任务上限。
  4. 接入指标与告警,压测观察吞吐、等待、失败与内存曲线。

代码或图示

# 发布前核对(命令名以当前版本为准)
php artisan queue:failed
php artisan horizon:status

# 进程管理示例:systemd 或容器编排保证主进程退出后拉起
# ExecStart=php artisan horizon
# Restart=always

常见误区

  • 上线后没有失败告警:毒消息长期堆积无人知晓,补偿流程缺失。
  • worker 不接进程管理器:内存泄漏崩溃后无人重启,队列静默停消费。

追问

  • 生产队列日志看什么?答:任务开始/结束日志、异常堆栈、重试次数、耗时与内存;避免在日志中记录完整载荷与敏感字段。
  • 灰度发布如何让旧任务平滑过渡?答:发版期间保留旧 worker 消费积压,新代码上线后逐步切换;队列消息结构不兼容时先排空旧队列再发版。