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 返回退出码,默认成功。
原理流程
- 定义命令类并声明 signature 与 description。
- 框架注册命令到 Artisan 应用。
- 执行时解析输入参数,容器解析 handle 依赖。
- 执行 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 内补充业务规则。
原理流程
- 在 signature 中声明参数与选项结构。
- Artisan 解析命令行输入,匹配签名定义。
- 必填参数缺失时直接报错,不进入 handle。
- 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。
原理流程
- 命令类构造函数声明依赖类型。
- Artisan 通过容器构造命令实例。
- handle 调用前反射方法参数并解析。
- 业务逻辑使用注入的服务。
代码或图示
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 等待输入;交互方法只用于人工执行场景。进度条适合批量处理,表格用于核对小批量结果,详细记录进日志与导出文件。
原理流程
- 判断运行环境是否可交互。
- 批量任务启动进度条并按步推进。
- 关键节点输出级别化信息。
- 结束输出摘要统计,详细错误进日志。
代码或图示
$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 内捕获并返回合适码。
原理流程
- handle 正常结束返回 SUCCESS。
- 可预期失败返回 FAILURE 或业务退出码。
- 未捕获异常向上抛出,框架输出错误并以非零码退出。
- 上层调度/脚本按退出码记录成败。
代码或图示
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 请求解耦。
原理流程
- 构造命令名与参数数组。
Artisan::call解析命令实例并执行 handle。- 返回退出码,输出经
output()读取。 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。
原理流程
- 在调度注册处创建调度条目。
- 定义任务类型(命令/队列任务/闭包)与频率。
- cron 每分钟触发
schedule:run。 - 调度器比对当前时间与表达式,到期任务执行。
代码或图示
// 调度定义示例(注册位置以当前版本骨架为准)
$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 表达式,可读性高于手写表达式。多个时间约束可链式追加,方法组合后的最终表达式以调度器生成结果为准(待确认组合优先级)。
原理流程
- 选择与业务周期匹配的便捷方法。
- 需要指定时刻时链式
dailyAt('HH:mm')。 - 调度器把方法转换为内部时间约束。
- 每分钟触发时比对是否到期。
代码或图示
$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 不同,它解决单实例内并发重入。
原理流程
- 到点触发,任务先尝试获取互斥锁。
- 锁被占用则跳过本次执行。
- 拿到锁后执行任务,结束释放锁。
- 进程崩溃时锁靠 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。
原理流程
- 每个实例 cron 触发
schedule:run。 - 任务执行前尝试获取共享分布式锁。
- 抢到锁的实例执行任务。
- 任务结束释放锁,锁 TTL 兜底崩溃场景。
代码或图示
$schedule->command('mail:digest')
->daily()
->onOneServer()
->withoutOverlapping();
常见误区
- 缓存用文件驱动又开
onOneServer:各实例本地文件不共享,锁互不感知,任务仍会重复执行。 - 锁不带 TTL:持锁实例崩溃后其他实例长期无法抢到锁。
追问
- 抢到锁的实例宕机怎么办?答:锁 TTL 过期后其他实例可接管;任务本身需具备幂等性,接管重跑不能产生重复副作用。
onOneServer与withoutOverlapping能同时用吗?答:可以,分别解决跨实例选主与单实例重入;两者锁机制是否合并以当前版本实现为准。
06.5.4.12-011 调度任务的输出如何落盘与通知?
一句话结论
调度器可把任务标准输出写入指定文件(output 方法),追加或覆盖;支持失败时邮件/Webhook 通知,输出与钩子结合用于任务结果留存与告警。
概念解释
命令自身的 info/error 输出进入标准输出,调度器按输出配置收集。长时间运行任务的日志应同时写入应用日志,控制台输出只作为调度留存。
原理流程
- 注册任务时配置输出文件路径。
- 任务执行产生标准输出。
- 调度器把输出追加/覆盖到文件。
- 失败钩子按配置发送通知。
代码或图示
$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 等回调(方法名以当前版本为准),分别在执行前、成功后、失败后与收尾阶段触发,用于记录状态、发送通知与清理。
概念解释
钩子挂在调度条目上,与任务内部异常处理互补:调度层钩子关心执行结果(退出码),任务内部钩子关心业务步骤。通知、审计记录适合放调度钩子。
原理流程
- 任务到期执行,先触发
before。 - 命令/任务执行完成,按退出码触发
onSuccess或onFailure。 after无论成败执行,finally做收尾。- 钩子内上报监控与通知渠道。
代码或图示
$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 而不互斥。
原理流程
- 系统 cron 每分钟执行
php artisan schedule:run。 - 调度器读取所有注册条目。
- 比对时间条件,到期任务入队或执行。
- 进程退出,等待下一分钟触发。
代码或图示
# 每分钟触发调度器(路径由部署环境定位,不写死到项目文档)
* * * * * 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 的重试、积压与监控体系。触发失败与任务执行失败分别在调度层与队列层观测。
原理流程
- 到点调度器把 job 实例投递到指定连接/队列。
- 调度进程立即返回,不等待任务完成。
- 队列 worker 认领并执行。
- 任务成败在队列面板与失败存储中查看。
代码或图示
$schedule->job(new GenerateDailyReport, 'reports')
->everyFifteenMinutes()
->onOneServer();
// 命令类也可指定队列执行方式(以版本 API 为准)
$schedule->command('report:rollup')->hourly()->withoutOverlapping();
常见误区
- 调度重命令直接同步执行:任务跑超时会阻塞同进程后续条目。
- 队列化后忽略队列积压:触发成功不代表任务按时完成,需观察队列等待与失败。
追问
- 队列任务错过触发时间怎么办?答:调度器只在触发时刻投递,不补投错过的执行;需要补跑应设计手动重放命令。
- job 投递可指定连接吗?答:可在 job 类属性或调度链式方法指定;具体链式方法名以当前版本为准(待确认)。
06.5.4.12-015 调度任务的时区与边界时间如何处理?
一句话结论
调度器默认使用应用配置时区,timezone() 可为单任务覆盖;跨时区业务必须明确时间基准,避免服务器时区、应用时区、业务时区不一致导致错过执行。
概念解释
cron 表达式解释基于调度时区。任务执行时长跨越时间边界时,按触发时刻判断是否到期;业务日历(节假日、月末)在任务内二次校验。
原理流程
- 读取应用默认时区配置。
- 单任务用
timezone()覆盖时按指定时区解释表达式。 - 触发时刻比对表达式与目标时区。
- 任务内部按业务时区处理日期数据。
代码或图示
$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 入口。
原理流程
- 常驻调度进程启动并引导应用。
- 进程内按间隔遍历调度条目。
- 到期任务执行或投递队列。
- 进程退出由管理器重启,崩溃后不影响 cron 模式备份。
代码或图示
# 常驻调度命令(命令名以当前版本为准,未确认前不要写入生产脚本)
php artisan schedule:work
常见误区
- 常驻调度进程无人托管:崩溃后定时任务整体停摆,必须接 systemd/容器重启策略。
- 同时配置 cron 入口与常驻进程:双重触发导致任务重复执行,二选一。
追问
- 常驻进程内状态如何隔离?答:与常驻运行时思路一致,任务间避免单例残留;调度任务多为短生命周期命令,作用域按任务划分。
- 如何验证调度入口生效?答:
schedule:list查看条目,手动触发一条测试任务观察执行记录与输出文件。
06.5.4.12-017 大批量命令如何控制内存与执行节奏?
一句话结论
批量数据处理用 chunk/cursor 分批读取,避免一次性加载模型集合;处理节奏配合限速、提交频率与内存观测,命令结束前输出统计;常驻或长任务需设内存上限与中断处理。
概念解释
与 06.5.4.7 Eloquent 查询优化与 N+1 治理 衔接:命令侧关注分批加载、批间释放、进度与失败记录,避免单批过大撑爆内存。
原理流程
- 按主键范围或条件分批查询。
- 每批处理后释放模型引用。
- 记录成功/失败条目,失败进入补偿清单。
- 定期检查内存,必要时分批退出由调度重跑。
代码或图示
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 命令与调度如何接入监控告警?
一句话结论
监控维度包括:任务是否按时执行、退出码成败、耗时、输出与失败摘要;调度钩子上报执行事件,队列化任务结合队列积压与失败面板;告警按失败、超时、连续未执行分级。
概念解释
只看“进程在跑”不够,要观测到“任务按预期完成”。未执行(调度入口故障)、执行失败(非零退出)、执行超时(耗时超阈值)三类问题分别告警。
原理流程
- 钩子记录任务开始/结束时间与退出码。
- 上报指标:任务名、耗时、状态。
- 告警规则匹配失败、超时、漏执行。
- 失败通知携带任务名、输出摘要与业务标识。
代码或图示
$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 请求,可用参数控制数据范围。开发时先用小数据集跑通,再放开全量;输出与日志结合定位问题步骤。
原理流程
- 本地直接执行命令加调试选项。
- 必要时 tinker 手动构造依赖调用服务方法。
- 测试中
Artisan::call断言退出码与数据库状态。 - 小批量 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 与积压、多实例部署入口。
概念解释
检查覆盖命令本身、调度配置、部署环境与监控闭环。任何一项缺失都可能表现为“任务偶尔不跑”或“失败无人知晓”。
原理流程
- 本地与预发执行命令,核对退出码、输出与数据结果。
schedule:list核对表达式、频率与下次时间。- 检查锁存储共享性、输出目录权限与轮转策略。
- 验证失败告警、心跳与队列 worker,灰度观察首个执行周期。
代码或图示
# 发布前核对调度清单(命令名以版本为准)
php artisan schedule:list
php artisan orders:export --dry-run
常见误区
- 多实例只在一台配 cron 却没选主:单实例故障即调度中断,应明确调度实例冗余策略。
- 队列化任务没起对应 worker:到点投递成功但无人消费,积压持续增长。
追问
- 配置变更后需要重启什么?答:传统 cron 入口无需重启进程;常驻调度进程需重载;代码与配置更新后确认调度入口加载新版本。
- 回滚时调度条目如何处理?答:旧版本代码的命令名与参数必须兼容;回滚前确认新条目不会指向已下线命令,避免触发不存在任务报错。