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

06.5.4.12 Artisan 命令与调度任务

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

覆盖范围

  • 自定义命令结构、签名参数选项、依赖注入与输出
  • 命令注册方式、退出码与可调用入口
  • 调度器定义、频率表达式、互斥与单实例
  • 任务输出、钩子、监控、队列化与多实例防重复

调度基础概念(cron 触发、多实例锁、队列化选择)见 06.5.1.4 缓存队列与任务调度;本页聚焦 Laravel 命令与调度器纵深。

06.5.4.12-001 Artisan 命令类的基本结构是什么?

一句话结论

命令类继承基础 Command,通过 $signature 定义命令名与参数选项,$description 写说明,handle 方法承载执行逻辑;框架在执行时经容器解析命令并注入 handle 依赖。

概念解释

签名是命令行契约:参数用花括号 {},选项用大括号加问号 {--},可选参数与默认值在签名或类属性中声明。handle 返回退出码,默认成功。

原理流程

  1. 定义命令类并声明 signature 与 description。
  2. 框架注册命令到 Artisan 应用。
  3. 执行时解析输入参数,容器解析 handle 依赖。
  4. 执行 handle,按返回退出码结束。

代码或图示

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ExportOrders extends Command
{
    protected $signature = 'orders:export {--date= : 导出日期} {--dry-run}';
    protected $description = '按日期导出订单数据';

    public function handle(): int
    {
        $date = $this->option('date') ?: today()->toDateString();
        $this->info("导出日期:{$date}");
        return Command::SUCCESS;
    }
}

常见误区

  • 在构造函数里执行业务逻辑:构造阶段参数尚未完全解析,重逻辑应放 handle。
  • 命令名用空格或不符合 kebab 风格:签名名应简洁稳定,避免与框架内置命令冲突。

追问

  • 命令在哪里注册?答:Laravel 11 起骨架目录有调整,命令通常自动从约定目录加载;旧版本在 Console Kernel 中手动 commands 注册,注册方式以当前版本骨架为准(待确认)。
  • handle 不返回退出码会怎样?答:默认按成功处理;需要显式失败时返回 Command::FAILURE 或对应退出码常量。

06.5.4.12-002 签名中的参数与选项如何定义和校验?

一句话结论

必填参数写 {name},可选参数写 {name?} 或 {name=default},选项写 {--name}、{--name=} 带值选项、{--name=*} 数组选项;argument() 与 option() 读取,缺失必填参数由框架在执行前拦截。

概念解释

参数按位置传入,选项以 -- 形式出现。数组选项可重复传入;布尔选项不带值,存在即 true。参数合法性校验可在 handle 内补充业务规则。

原理流程

  1. 在 signature 中声明参数与选项结构。
  2. Artisan 解析命令行输入,匹配签名定义。
  3. 必填参数缺失时直接报错,不进入 handle。
  4. handle 通过 argument()/option() 取值并做业务校验。

代码或图示

protected $signature = 'report:send
    {user : 接收用户 ID}
    {--channels=* : 通知渠道}
    {--force : 跳过确认}';

public function handle(): int
{
    $userId = (int) $this->argument('user');
    $channels = $this->option('channels') ?: ['mail'];
    $force = (bool) $this->option('force');
    // 业务校验:用户存在、渠道合法
    return Command::SUCCESS;
}

常见误区

  • 把选项当位置参数取值:option('x') 读不到位置传入的值。
  • 数组选项未按重复形式传入:单个值与数组类型处理不一致,取值后统一转换。

追问

  • 如何给参数写帮助说明?答:签名参数后用冒号附描述,php artisan list 与命令帮助中展示;描述文本同时服务于运维文档。
  • 选项默认值在哪里设置?答:签名内联默认值,或在 handle 中读取后回退;布尔选项默认 false。

06.5.4.12-003 命令的依赖注入如何完成?

一句话结论

命令构造函数可声明类型提示由容器注入,handle 方法参数同样经容器解析;服务依赖优先构造注入,命令专用的轻量依赖可在 handle 签名中声明。

概念解释

与控制器、监听器一致,命令是容器解析的类。构造注入适合全流程使用的服务,方法注入适合 handle 才需要的依赖;不要在命令里到处 app()->make。

原理流程

  1. 命令类构造函数声明依赖类型。
  2. Artisan 通过容器构造命令实例。
  3. handle 调用前反射方法参数并解析。
  4. 业务逻辑使用注入的服务。

代码或图示

class SyncCatalog extends Command
{
    public function __construct(private readonly CatalogImporter $importer)
    {
        parent::__construct();
    }

    public function handle(InventoryService $inventory): int
    {
        $this->importer->run();
        $inventory->refresh();
        return Command::SUCCESS;
    }
}

常见误区

  • 构造函数注入后忘记调用 parent::__construct():命令基类初始化可能未完成。
  • handle 参数声明标量并期望容器提供:标量无法自动解析,命令输入应通过 argument/option 取。

追问

  • 命令里能请求 Request 吗?答:CLI 上下文没有 HTTP 请求;需要的输入来自命令参数选项,配置从配置仓库读取。
  • 容器解析失败会怎样?答:抛绑定解析异常,与其他容器解析场景一致;核对依赖绑定与构造参数类型。

06.5.4.12-004 命令输出有哪些方式,如何组织可读输出?

一句话结论

输出方法包括 info/comment/question/error 行式输出、table 表格、progressBar 进度条、ask/anticipate/choice 交互提问;结构化长输出适合写文件或日志,控制台只展示进度与摘要。

概念解释

非交互运行(cron/队列)不能依赖 ask 等待输入;交互方法只用于人工执行场景。进度条适合批量处理,表格用于核对小批量结果,详细记录进日志与导出文件。

原理流程

  1. 判断运行环境是否可交互。
  2. 批量任务启动进度条并按步推进。
  3. 关键节点输出级别化信息。
  4. 结束输出摘要统计,详细错误进日志。

代码或图示

$bar = $this->output->createProgressBar($orders->count());
$bar->start();

foreach ($orders as $order) {
    $this->process($order);
    $bar->advance();
}

$bar->finish();
$this->newLine();
$this->table(['ID', '状态'], $rows);

常见误区

  • 在定时任务里使用交互提问:无人应答会挂起进程,阻塞后续调度。
  • 大批量逐条 info 打印:输出膨胀且拖慢处理,应配合进度条与汇总。

追问

  • 输出颜色与级别对应什么?答:info 绿色、comment 灰/黄、error 红色等,具体样式随输出风格;非 TTY 环境颜色自动降级,行为以控制台实现为准。
  • 如何在脚本中判断是否交互?答:输出对象提供 isDecorated 类判断或检测 TTY;具体方法名以当前版本 Symfony Console 组件为准(待确认)。

06.5.4.12-005 命令退出码如何约定,失败如何向上传递?

一句话结论

SUCCESS(0)表示成功,FAILURE(1)或自定义非零退出码表示失败;调度器、CI、进程管理器根据退出码判断任务成败并触发告警,非零退出码会被上层识别为失败。

概念解释

退出码是命令与外部调用方的契约:cron、systemd、CI 脚本都靠退出码判定结果。业务异常未捕获时框架以错误退出,需要补偿与上报时在 handle 内捕获并返回合适码。

原理流程

  1. handle 正常结束返回 SUCCESS。
  2. 可预期失败返回 FAILURE 或业务退出码。
  3. 未捕获异常向上抛出,框架输出错误并以非零码退出。
  4. 上层调度/脚本按退出码记录成败。

代码或图示

public function handle(): int
{
    if (! $this->sourceAvailable()) {
        $this->error('数据源不可用');
        return Command::FAILURE;
    }

    try {
        $this->run();
    } catch (\Throwable $e) {
        report($e);
        return 2; // 自定义退出码:数据处理失败
    }

    return Command::SUCCESS;
}

常见误区

  • 吞掉异常仍返回 0:上层认为成功,失败任务无人告警。
  • 所有失败都用同一退出码:不同失败类型无法在监控中区分,可约定自定义码段。

追问

  • 调度器如何识别命令失败?答:调度任务钩子与退出码状态结合,onFailure 类回调在非零退出或异常时触发,具体触发条件以调度器实现为准。
  • 退出码范围有限制吗?答:惯例 0 成功,1-255 失败;超出 shell 约定的值可能被截断,自定义码控制在常规范围内。

06.5.4.12-006 如何在代码内部调用命令(Artisan::call)?

一句话结论

Artisan::call('command', ['--option' => value]) 在进程内执行命令并返回退出码,Artisan::queue 可把命令投递到队列执行;适合编排多个命令步骤,但应避免在请求链路同步跑重命令。

概念解释

内部调用复用命令类与容器,输出默认被捕获;需要查看结果可用 Artisan::output()。队列化调用让重命令异步执行,与 Web 请求解耦。

原理流程

  1. 构造命令名与参数数组。
  2. Artisan::call 解析命令实例并执行 handle。
  3. 返回退出码,输出经 output() 读取。
  4. Artisan::queue 改为入队,由队列 worker 消费。

代码或图示

use Illuminate\Support\Facades\Artisan;

$exitCode = Artisan::call('orders:export', [
    '--date' => '2026-11-19',
    '--dry-run' => true,
]);

if ($exitCode !== Artisan::SUCCESS) {
    report(new \RuntimeException('导出命令失败'));
}

// 异步执行
Artisan::queue('catalog:sync', ['--force' => true]);

常见误区

  • Web 请求内同步调用长命令:阻塞响应,应投递队列。
  • 参数名与签名选项不匹配:选项键带不带 -- 的写法以 call 实现为准,建议对照命令帮助核对。

追问

  • 内部调用会重新引导应用吗?答:同一进程内复用当前应用容器,不重启引导;与独立进程执行命令的环境差异需注意。
  • 命令输出如何在 call 后读取?答:Artisan::output() 返回最近一次捕获的输出文本;连续调用注意输出被覆盖的时机。

06.5.4.12-007 调度器如何定义任务,cron 表达式怎么写?

一句话结论

调度定义在调度注册表(旧版本 Console Kernel 的 schedule 方法,Laravel 11 起位置以骨架为准);用 ->command()、->job()、->call() 注册任务,频率可便捷方法或 cron('* * * * *') 表达式。

概念解释

调度器每分钟由系统 cron 触发一次 schedule:run,内部匹配到期任务。cron 五段:分、时、日、月、周;便捷方法屏蔽常用表达式,复杂周期用原始 cron。

原理流程

  1. 在调度注册处创建调度条目。
  2. 定义任务类型(命令/队列任务/闭包)与频率。
  3. cron 每分钟触发 schedule:run。
  4. 调度器比对当前时间与表达式,到期任务执行。

代码或图示

// 调度定义示例(注册位置以当前版本骨架为准)
$schedule->command('orders:export')->dailyAt('01:30');
$schedule->job(new CleanExpiredCart)->hourly();
$schedule->call(function () {
    // 轻量闭包任务
})->everyFifteenMinutes();

// 原始表达式:每 30 分钟
$schedule->command('report:rollup')->cron('*/30 * * * *');

常见误区

  • 以为调度器自身是常驻定时器:它依赖外部 cron 每分钟拉起;没有入口触发,任务不会执行。
  • 日/周字段混用导致表达式不按预期:例如 dailyAt 与 cron 同时设置时以后设置覆盖前设置,覆盖规则以调度器源码为准。

追问

  • 时区如何影响表达式?答:调度器使用应用配置时区;跨时区业务需明确时区设置,表达式按该时区解释。
  • 每年/每月复杂周期怎么写?答:可用 cron 月份与周字段组合,或便捷方法;无法表达的业务规则在任务内校验日期后跳过。

06.5.4.12-008 常用调度频率便捷方法有哪些?

一句话结论

便捷方法覆盖 everyMinute、everyFiveMinutes、everyFifteenMinutes、hourly、daily、dailyAt、weekly、monthly、quarterly、yearly 等;需要特定时分用 dailyAt,按星期用 weeklyOn 类方法。

概念解释

便捷方法生成等价 cron 表达式,可读性高于手写表达式。多个时间约束可链式追加,方法组合后的最终表达式以调度器生成结果为准(待确认组合优先级)。

原理流程

  1. 选择与业务周期匹配的便捷方法。
  2. 需要指定时刻时链式 dailyAt('HH:mm')。
  3. 调度器把方法转换为内部时间约束。
  4. 每分钟触发时比对是否到期。

代码或图示

$schedule->command('backup:run')->dailyAt('02:00');
$schedule->command('metrics:aggregate')->hourly();
$schedule->command('report:weekly')->weeklyOn(1, '08:00'); // 周一 8 点
$schedule->command('billing:close')->monthlyOn(1, '00:10');

常见误区

  • 链式叠加多个频率方法误以为取并集:最终生效的时间约束以调度器实现为准,不确定时用 schedule:list 核对生成的 cron。
  • 任务执行时间超过间隔:例如每 15 分钟任务跑 20 分钟,会出现重叠,需配合互斥或拆分。

追问

  • 如何查看注册后的调度时间表?答:schedule:list(命令名以版本为准)列出任务、表达式与下次执行时间,发布前用它核对。
  • 跳过特定日期怎么做?答:链式 ->when(...) 条件或任务内判断;节假日排除可接入日历判断回调。

06.5.4.12-009 withoutOverlapping 如何防止任务重入?

一句话结论

withoutOverlapping 为调度任务加互斥锁,上一次执行尚未结束时,到点触发会跳过本次;锁带超时时间,防止持锁进程崩溃后任务永久阻塞。

概念解释

互斥基于缓存锁(驱动按缓存配置)。任务启动时抢锁,结束释放;超时时间保证崩溃后锁可自动过期。与多实例 onOneServer 不同,它解决单实例内并发重入。

原理流程

  1. 到点触发,任务先尝试获取互斥锁。
  2. 锁被占用则跳过本次执行。
  3. 拿到锁后执行任务,结束释放锁。
  4. 进程崩溃时锁靠 TTL 过期自动解锁。

代码或图示

$schedule->command('report:rollup')
    ->everyFifteenMinutes()
    ->withoutOverlapping(30); // 锁超时分钟数,参数以版本为准

常见误区

  • 不设锁超时:崩溃后残留锁,后续任务全部跳过。
  • 以为互斥锁跨多实例生效:单实例锁只在本实例缓存内有效,多实例需 onOneServer。

追问

  • 锁存在哪里?答:由应用缓存驱动存储(redis/database 等),驱动不共享时多实例锁不互通;具体键名与 TTL 实现以调度器源码为准。
  • 跳过的任务有记录吗?答:默认跳过不产生执行记录;需要审计时在任务钩子或外部监控中记录跳过原因。

06.5.4.12-010 onOneServer 如何解决多实例重复执行?

一句话结论

多台实例各自配置 cron 时,onOneServer 利用分布式锁保证同一调度任务同一时刻只在一个实例执行;需要共享缓存/锁存储,否则各实例无法互斥。

概念解释

与 06.5.1.4 中的多实例防重复题衔接:调度器在触发前抢分布式锁,抢到的实例执行,其余跳过。锁存储必须是多实例共享的 Redis/database。

原理流程

  1. 每个实例 cron 触发 schedule:run。
  2. 任务执行前尝试获取共享分布式锁。
  3. 抢到锁的实例执行任务。
  4. 任务结束释放锁,锁 TTL 兜底崩溃场景。

代码或图示

$schedule->command('mail:digest')
    ->daily()
    ->onOneServer()
    ->withoutOverlapping();

常见误区

  • 缓存用文件驱动又开 onOneServer:各实例本地文件不共享,锁互不感知,任务仍会重复执行。
  • 锁不带 TTL:持锁实例崩溃后其他实例长期无法抢到锁。

追问

  • 抢到锁的实例宕机怎么办?答:锁 TTL 过期后其他实例可接管;任务本身需具备幂等性,接管重跑不能产生重复副作用。
  • onOneServer 与 withoutOverlapping 能同时用吗?答:可以,分别解决跨实例选主与单实例重入;两者锁机制是否合并以当前版本实现为准。

06.5.4.12-011 调度任务的输出如何落盘与通知?

一句话结论

调度器可把任务标准输出写入指定文件(output 方法),追加或覆盖;支持失败时邮件/Webhook 通知,输出与钩子结合用于任务结果留存与告警。

概念解释

命令自身的 info/error 输出进入标准输出,调度器按输出配置收集。长时间运行任务的日志应同时写入应用日志,控制台输出只作为调度留存。

原理流程

  1. 注册任务时配置输出文件路径。
  2. 任务执行产生标准输出。
  3. 调度器把输出追加/覆盖到文件。
  4. 失败钩子按配置发送通知。

代码或图示

$schedule->command('backup:run')
    ->daily()
    ->output(storage_path('logs/backup.log'), append: true)
    ->emailOutputOnFailure('ops@example.com');

常见误区

  • 输出文件无轮转:长期追加导致日志文件无限增长,应接入日志轮转或定期清理。
  • 通知渠道只在成功时配置:失败无告警,任务静默失败。

追问

  • 输出文件路径用什么函数定位?答:storage_path 等助手函数定位存储目录;调度配置中的路径在部署环境可写。
  • 输出包含敏感信息怎么办?答:命令内应避免输出凭证与个人信息,通知邮件只发摘要与退出状态。

06.5.4.12-012 调度任务有哪些前后钩子?

一句话结论

调度条目支持 before、after、onSuccess、onFailure、finally 等回调(方法名以当前版本为准),分别在执行前、成功后、失败后与收尾阶段触发,用于记录状态、发送通知与清理。

概念解释

钩子挂在调度条目上,与任务内部异常处理互补:调度层钩子关心执行结果(退出码),任务内部钩子关心业务步骤。通知、审计记录适合放调度钩子。

原理流程

  1. 任务到期执行,先触发 before。
  2. 命令/任务执行完成,按退出码触发 onSuccess 或 onFailure。
  3. after 无论成败执行,finally 做收尾。
  4. 钩子内上报监控与通知渠道。

代码或图示

$schedule->command('report:send')
    ->daily()
    ->before(fn () => logger()->info('report start'))
    ->onFailure(fn () => logger()->error('report failed'))
    ->finally(fn () => logger()->info('report finished'));

常见误区

  • 在钩子中再跑重逻辑:钩子执行在调度进程内,阻塞会拖延后续调度匹配。
  • 钩子与任务内重复上报:成败状态以退出码为准,避免双份告警。

追问

  • 闭包钩子能注入依赖吗?答:回调由容器调用,可声明类型提示参数;与其他容器回调解析方式一致。
  • 任务被互斥跳过时钩子会触发吗?答:跳过属于未执行,成功/失败钩子是否触发需核对调度器实现(待确认),审计跳过应另加监控。

06.5.4.12-013 调度器的系统入口如何配置?

一句话结论

生产环境在服务器 crontab 中每分钟调用一次 schedule:run,调度器内部判断各任务是否到期;不需要为每个任务单独配置系统 cron。容器部署时由独立调度容器或宿主 cron 触发。

概念解释

单一入口把所有 Laravel 调度条目收拢到一条 cron。多实例部署时入口可放在所有实例(配合 onOneServer),或专用调度实例;不能在每个实例都配独立任务 cron 而不互斥。

原理流程

  1. 系统 cron 每分钟执行 php artisan schedule:run。
  2. 调度器读取所有注册条目。
  3. 比对时间条件,到期任务入队或执行。
  4. 进程退出,等待下一分钟触发。

代码或图示

# 每分钟触发调度器(路径由部署环境定位,不写死到项目文档)
* * * * * cd /path/to/project && php artisan schedule:run >> /dev/null 2>&1

常见误区

  • 每个任务配一条系统 cron:绕过 Laravel 调度器,互斥、钩子、输出配置全部失效。
  • Web 访问触发调度:依赖有人访问才执行,不可靠且可被外部触发。

追问

  • 容器化部署 cron 放哪里?答:可起一个专用调度容器跑 schedule:run 入口,或在宿主 cron 调容器命令;调度容器与应用副本共享代码与配置。
  • schedule:run 本身并发吗?答:单次触发内任务按注册顺序执行或队列化;长时间任务会占用当前触发进程,重任务应投递队列。

06.5.4.12-014 调度任务如何队列化执行?

一句话结论

$schedule->job(JobClass) 把队列任务作为调度条目,到点投递到队列由 worker 消费;避免重任务阻塞调度进程,调度器只负责到点触发,执行耗时与队列 worker 能力解耦。

概念解释

命令类任务仍可由调度进程直接执行;队列化 job 走 06.5.4.9 队列驱动与 Horizon 的重试、积压与监控体系。触发失败与任务执行失败分别在调度层与队列层观测。

原理流程

  1. 到点调度器把 job 实例投递到指定连接/队列。
  2. 调度进程立即返回,不等待任务完成。
  3. 队列 worker 认领并执行。
  4. 任务成败在队列面板与失败存储中查看。

代码或图示

$schedule->job(new GenerateDailyReport, 'reports')
    ->everyFifteenMinutes()
    ->onOneServer();

// 命令类也可指定队列执行方式(以版本 API 为准)
$schedule->command('report:rollup')->hourly()->withoutOverlapping();

常见误区

  • 调度重命令直接同步执行:任务跑超时会阻塞同进程后续条目。
  • 队列化后忽略队列积压:触发成功不代表任务按时完成,需观察队列等待与失败。

追问

  • 队列任务错过触发时间怎么办?答:调度器只在触发时刻投递,不补投错过的执行;需要补跑应设计手动重放命令。
  • job 投递可指定连接吗?答:可在 job 类属性或调度链式方法指定;具体链式方法名以当前版本为准(待确认)。

06.5.4.12-015 调度任务的时区与边界时间如何处理?

一句话结论

调度器默认使用应用配置时区,timezone() 可为单任务覆盖;跨时区业务必须明确时间基准,避免服务器时区、应用时区、业务时区不一致导致错过执行。

概念解释

cron 表达式解释基于调度时区。任务执行时长跨越时间边界时,按触发时刻判断是否到期;业务日历(节假日、月末)在任务内二次校验。

原理流程

  1. 读取应用默认时区配置。
  2. 单任务用 timezone() 覆盖时按指定时区解释表达式。
  3. 触发时刻比对表达式与目标时区。
  4. 任务内部按业务时区处理日期数据。

代码或图示

$schedule->command('report:cn-daily')
    ->dailyAt('09:00')
    ->timezone('Asia/Shanghai');

常见误区

  • 服务器系统时区与应用时区不一致却不配置:调度按应用时区解释,系统 cron 拉起时刻仍受系统时间影响。
  • 任务内用服务器本地时间计算日期:应统一用应用时区 Carbon 方法。

追问

  • 夏令时会造成漏跑或重复吗?答:时区切换日时间跳变可能影响日级任务,边界场景需在业务日历中验证;具体行为受操作系统与时区库影响。
  • 多租户跨时区报表怎么调度?答:按租户时区分组,或任务内按租户时区生成数据,调度触发只按统一基准时间。

06.5.4.12-016 常驻调度进程与传统 cron 入口有何区别?

一句话结论

部分版本提供常驻调度监听命令,进程内按时间间隔检查到期任务,替代每分钟由系统 cron 拉起 schedule:run;两者都需要进程管理器保障存活,常驻模式省去频繁引导进程的开销。

概念解释

传统 cron 每分钟新起 PHP 进程引导应用再匹配任务;常驻调度进程引导一次后循环检查。命令名、支持版本与行为以当前版本文档为准(待确认),不确定时沿用标准 cron 入口。

原理流程

  1. 常驻调度进程启动并引导应用。
  2. 进程内按间隔遍历调度条目。
  3. 到期任务执行或投递队列。
  4. 进程退出由管理器重启,崩溃后不影响 cron 模式备份。

代码或图示

# 常驻调度命令(命令名以当前版本为准,未确认前不要写入生产脚本)
php artisan schedule:work

常见误区

  • 常驻调度进程无人托管:崩溃后定时任务整体停摆,必须接 systemd/容器重启策略。
  • 同时配置 cron 入口与常驻进程:双重触发导致任务重复执行,二选一。

追问

  • 常驻进程内状态如何隔离?答:与常驻运行时思路一致,任务间避免单例残留;调度任务多为短生命周期命令,作用域按任务划分。
  • 如何验证调度入口生效?答:schedule:list 查看条目,手动触发一条测试任务观察执行记录与输出文件。

06.5.4.12-017 大批量命令如何控制内存与执行节奏?

一句话结论

批量数据处理用 chunk/cursor 分批读取,避免一次性加载模型集合;处理节奏配合限速、提交频率与内存观测,命令结束前输出统计;常驻或长任务需设内存上限与中断处理。

概念解释

与 06.5.4.7 Eloquent 查询优化与 N+1 治理 衔接:命令侧关注分批加载、批间释放、进度与失败记录,避免单批过大撑爆内存。

原理流程

  1. 按主键范围或条件分批查询。
  2. 每批处理后释放模型引用。
  3. 记录成功/失败条目,失败进入补偿清单。
  4. 定期检查内存,必要时分批退出由调度重跑。

代码或图示

Order::query()->chunk(200, function ($orders) {
    foreach ($orders as $order) {
        $this->process($order);
    }
    $orders->flush(); // 释放模型引用,方法名以版本为准
});

常见误区

  • get() 全量加载后遍历:万级以上数据内存直接打满。
  • 批内失败中断整批:应记录失败条目继续处理,末尾汇总补偿。

追问

  • chunk 与 cursor 如何选?答:chunk 按主键分页重读,cursor 用游标逐条遍历;大数据量下按查询条件与内存表现选择,细节见查询优化页。
  • 长命令被中断后能续跑吗?答:记录已处理水位(主键/时间),重跑时从断点继续;幂等设计保证重跑安全。

06.5.4.12-018 命令与调度如何接入监控告警?

一句话结论

监控维度包括:任务是否按时执行、退出码成败、耗时、输出与失败摘要;调度钩子上报执行事件,队列化任务结合队列积压与失败面板;告警按失败、超时、连续未执行分级。

概念解释

只看“进程在跑”不够,要观测到“任务按预期完成”。未执行(调度入口故障)、执行失败(非零退出)、执行超时(耗时超阈值)三类问题分别告警。

原理流程

  1. 钩子记录任务开始/结束时间与退出码。
  2. 上报指标:任务名、耗时、状态。
  3. 告警规则匹配失败、超时、漏执行。
  4. 失败通知携带任务名、输出摘要与业务标识。

代码或图示

$schedule->command('digest:send')
    ->daily()
    ->onFailure(function () {
        logger()->error('digest task failed', ['task' => 'digest:send']);
    });

常见误区

  • 告警只接异常堆栈:漏执行(cron 未拉起)没有异常可抓,需要心跳类监控证明任务按时跑过。
  • 所有任务同一阈值:快任务与重任务超时基线不同,按历史耗时分别设阈值。

追问

  • 心跳监控怎么做?答:任务成功后上报一条时间戳记录,监控对比距上次成功时间是否超期;外部平台或内部表均可。
  • 调度失败通知渠道接什么?答:复用项目既有通知渠道(邮件/Webhook/IM),配置与环境分离,不在代码中写敏感 webhook 地址。

06.5.4.12-019 命令开发与调试有哪些常用手段?

一句话结论

调试手段:artisan 直接运行命令观察输出、--verbose 提升日志级别、tinker 中解析服务、单元测试调用 Artisan::call、检查参数选项与退出码;复杂数据先小批量 dry-run。

概念解释

命令是最容易独立测试的一层:不依赖 HTTP 请求,可用参数控制数据范围。开发时先用小数据集跑通,再放开全量;输出与日志结合定位问题步骤。

原理流程

  1. 本地直接执行命令加调试选项。
  2. 必要时 tinker 手动构造依赖调用服务方法。
  3. 测试中 Artisan::call 断言退出码与数据库状态。
  4. 小批量 dry-run 核对结果后全量执行。

代码或图示

php artisan orders:export --date=2026-11-19 --dry-run -v
php artisan tinker
public function test_export_command(): void
{
    $this->artisan('orders:export', ['--date' => '2026-11-19'])
        ->assertExitCode(Command::SUCCESS);
}

常见误区

  • 直接在生产全量跑未验证命令:应先预发或小批量 dry-run。
  • 调试输出留在命令默认输出:调试信息按 verbose 级别条件输出。

追问

  • 命令内如何打印变量调试?答:$this->line()/dump() 输出到控制台;长期排查用日志上下文,不依赖手工控制台。
  • 测试如何模拟命令参数?答:artisan() 辅助方法传参数组,断言退出码、输出文本与副作用状态。

06.5.4.12-020 命令与调度上线前要检查哪些事项?

一句话结论

上线前核对:命令参数与退出码约定、调度条目清单与下次执行时间、互斥/单实例锁与共享缓存、输出文件可写与轮转、失败告警与心跳、队列化任务的 worker 与积压、多实例部署入口。

概念解释

检查覆盖命令本身、调度配置、部署环境与监控闭环。任何一项缺失都可能表现为“任务偶尔不跑”或“失败无人知晓”。

原理流程

  1. 本地与预发执行命令,核对退出码、输出与数据结果。
  2. schedule:list 核对表达式、频率与下次时间。
  3. 检查锁存储共享性、输出目录权限与轮转策略。
  4. 验证失败告警、心跳与队列 worker,灰度观察首个执行周期。

代码或图示

# 发布前核对调度清单(命令名以版本为准)
php artisan schedule:list
php artisan orders:export --dry-run

常见误区

  • 多实例只在一台配 cron 却没选主:单实例故障即调度中断,应明确调度实例冗余策略。
  • 队列化任务没起对应 worker:到点投递成功但无人消费,积压持续增长。

追问

  • 配置变更后需要重启什么?答:传统 cron 入口无需重启进程;常驻调度进程需重载;代码与配置更新后确认调度入口加载新版本。
  • 回滚时调度条目如何处理?答:旧版本代码的命令名与参数必须兼容;回滚前确认新条目不会指向已下线命令,避免触发不存在任务报错。