任务调度
简介
过去,您可能为需要在服务器上调度的每个任务编写一个 cron 配置文件条目。然而,这很快就会变成一件麻烦事,因为您的任务计划不再受源代码控制,并且您必须 SSH 进入您的服务器才能查看您现有的 cron 条目或添加其他条目。
Laravel 的命令调度器为管理服务器上的计划任务提供了一种全新的方法。调度器允许您在 Laravel 应用程序本身内流畅且富有表现力地定义命令计划。当使用调度器时,您的服务器上只需要一个 cron 条目。您的任务计划通常在应用程序的 routes/console.php
文件中定义。
定义计划
您可以在应用程序的 routes/console.php
文件中定义所有计划任务。要开始使用,让我们看一个例子。在此示例中,我们将计划一个闭包在每天午夜调用。在闭包中,我们将执行数据库查询以清除表
1<?php2 3use Illuminate\Support\Facades\DB;4use Illuminate\Support\Facades\Schedule;5 6Schedule::call(function () {7 DB::table('recent_users')->delete();8})->daily();
除了使用闭包进行调度外,您还可以调度可调用对象。可调用对象是简单的 PHP 类,其中包含 __invoke
方法
1Schedule::call(new DeleteRecentUsers)->daily();
如果您希望仅将 routes/console.php
文件用于命令定义,则可以使用应用程序 bootstrap/app.php
文件中的 withSchedule
方法来定义计划任务。此方法接受一个闭包,该闭包接收调度器的实例
1use Illuminate\Console\Scheduling\Schedule;2 3->withSchedule(function (Schedule $schedule) {4 $schedule->call(new DeleteRecentUsers)->daily();5})
如果您想查看计划任务的概述以及下次计划运行的时间,可以使用 schedule:list
Artisan 命令
1php artisan schedule:list
调度 Artisan 命令
除了调度闭包外,您还可以调度Artisan 命令和系统命令。例如,您可以使用 command
方法,使用命令的名称或类来调度 Artisan 命令。
当使用命令的类名调度 Artisan 命令时,您可以传递一个额外的命令行参数数组,这些参数应在调用命令时提供给命令
1use App\Console\Commands\SendEmailsCommand;2use Illuminate\Support\Facades\Schedule;3 4Schedule::command('emails:send Taylor --force')->daily();5 6Schedule::command(SendEmailsCommand::class, ['Taylor', '--force'])->daily();
调度 Artisan 闭包命令
如果您想调度由闭包定义的 Artisan 命令,则可以在命令定义后链式调用调度相关的方法
1Artisan::command('delete:recent-users', function () {2 DB::table('recent_users')->delete();3})->purpose('Delete recent users')->daily();
如果您需要将参数传递给闭包命令,则可以将其提供给 schedule
方法
1Artisan::command('emails:send {user} {--force}', function ($user) {2 // ...3})->purpose('Send emails to the specified user')->schedule(['Taylor', '--force'])->daily();
调度队列任务
job
方法可用于调度队列任务。此方法提供了一种便捷的方式来调度队列任务,而无需使用 call
方法来定义闭包以将任务放入队列
1use App\Jobs\Heartbeat;2use Illuminate\Support\Facades\Schedule;3 4Schedule::job(new Heartbeat)->everyFiveMinutes();
可选的第二个和第三个参数可以提供给 job
方法,用于指定应使用的队列名称和队列连接来将任务放入队列
1use App\Jobs\Heartbeat;2use Illuminate\Support\Facades\Schedule;3 4// Dispatch the job to the "heartbeats" queue on the "sqs" connection...5Schedule::job(new Heartbeat, 'heartbeats', 'sqs')->everyFiveMinutes();
调度 Shell 命令
exec
方法可用于向操作系统发出命令
1use Illuminate\Support\Facades\Schedule;2 3Schedule::exec('node /home/forge/script.js')->daily();
调度频率选项
我们已经看到了一些关于如何配置任务以在指定间隔运行的示例。但是,您可以为任务分配更多任务计划频率
方法 | 描述 |
---|---|
->cron('* * * * *'); |
按照自定义的 cron 计划运行任务。 |
->everySecond(); |
每秒运行一次任务。 |
->everyTwoSeconds(); |
每两秒运行一次任务。 |
->everyFiveSeconds(); |
每五秒运行一次任务。 |
->everyTenSeconds(); |
每十秒运行一次任务。 |
->everyFifteenSeconds(); |
每十五秒运行一次任务。 |
->everyTwentySeconds(); |
每二十秒运行一次任务。 |
->everyThirtySeconds(); |
每三十秒运行一次任务。 |
->everyMinute(); |
每分钟运行一次任务。 |
->everyTwoMinutes(); |
每两分钟运行一次任务。 |
->everyThreeMinutes(); |
每三分钟运行一次任务。 |
->everyFourMinutes(); |
每四分钟运行一次任务。 |
->everyFiveMinutes(); |
每五分钟运行一次任务。 |
->everyTenMinutes(); |
每十分钟运行一次任务。 |
->everyFifteenMinutes(); |
每十五分钟运行一次任务。 |
->everyThirtyMinutes(); |
每三十分钟运行一次任务。 |
->hourly(); |
每小时运行一次任务。 |
->hourlyAt(17); |
每小时的第 17 分钟运行一次任务。 |
->everyOddHour($minutes = 0); |
每隔一小时运行一次任务。 |
->everyTwoHours($minutes = 0); |
每两小时运行一次任务。 |
->everyThreeHours($minutes = 0); |
每三小时运行一次任务。 |
->everyFourHours($minutes = 0); |
每四小时运行一次任务。 |
->everySixHours($minutes = 0); |
每六小时运行一次任务。 |
->daily(); |
每天午夜运行一次任务。 |
->dailyAt('13:00'); |
每天 13:00 运行一次任务。 |
->twiceDaily(1, 13); |
每天 1:00 和 13:00 运行任务。 |
->twiceDailyAt(1, 13, 15); |
每天 1:15 和 13:15 运行任务。 |
->weekly(); |
每周日 00:00 运行一次任务。 |
->weeklyOn(1, '8:00'); |
每周一 8:00 运行一次任务。 |
->monthly(); |
每月第一天 00:00 运行一次任务。 |
->monthlyOn(4, '15:00'); |
每月 4 号 15:00 运行一次任务。 |
->twiceMonthly(1, 16, '13:00'); |
每月 1 号和 16 号 13:00 运行任务。 |
->lastDayOfMonth('15:00'); |
每月最后一天 15:00 运行一次任务。 |
->quarterly(); |
每季度第一天 00:00 运行一次任务。 |
->quarterlyOn(4, '14:00'); |
每季度 4 号 14:00 运行一次任务。 |
->yearly(); |
每年第一天 00:00 运行一次任务。 |
->yearlyOn(6, 1, '17:00'); |
每年 6 月 1 日 17:00 运行一次任务。 |
->timezone('America/New_York'); |
设置任务的时区。 |
这些方法可以与附加约束结合使用,以创建更精细的计划,使其仅在每周的特定日期运行。例如,您可以计划一个命令在每周一运行
1use Illuminate\Support\Facades\Schedule; 2 3// Run once per week on Monday at 1 PM... 4Schedule::call(function () { 5 // ... 6})->weekly()->mondays()->at('13:00'); 7 8// Run hourly from 8 AM to 5 PM on weekdays... 9Schedule::command('foo')10 ->weekdays()11 ->hourly()12 ->timezone('America/Chicago')13 ->between('8:00', '17:00');
其他计划约束的列表可以在下面找到
方法 | 描述 |
---|---|
->weekdays(); |
将任务限制在工作日。 |
->weekends(); |
将任务限制在周末。 |
->sundays(); |
将任务限制在星期日。 |
->mondays(); |
将任务限制在星期一。 |
->tuesdays(); |
将任务限制在星期二。 |
->wednesdays(); |
将任务限制在星期三。 |
->thursdays(); |
将任务限制在星期四。 |
->fridays(); |
将任务限制在星期五。 |
->saturdays(); |
将任务限制在星期六。 |
->days(array|mixed); |
将任务限制在特定日期。 |
->between($startTime, $endTime); |
限制任务在开始时间和结束时间之间运行。 |
->unlessBetween($startTime, $endTime); |
限制任务不在开始时间和结束时间之间运行。 |
->when(Closure); |
根据真值测试限制任务。 |
->environments($env); |
将任务限制在特定环境。 |
日期约束
days
方法可用于将任务的执行限制在每周的特定日期。例如,您可以计划一个命令在每周日和周三每小时运行一次
1use Illuminate\Support\Facades\Schedule;2 3Schedule::command('emails:send')4 ->hourly()5 ->days([0, 3]);
或者,您可以在定义任务应运行的日期时,使用 Illuminate\Console\Scheduling\Schedule
类上提供的常量
1use Illuminate\Support\Facades;2use Illuminate\Console\Scheduling\Schedule;3 4Facades\Schedule::command('emails:send')5 ->hourly()6 ->days([Schedule::SUNDAY, Schedule::WEDNESDAY]);
时间范围约束
between
方法可用于根据一天中的时间限制任务的执行
1Schedule::command('emails:send')2 ->hourly()3 ->between('7:00', '22:00');
类似地,unlessBetween
方法可用于排除在一段时间内执行任务
1Schedule::command('emails:send')2 ->hourly()3 ->unlessBetween('23:00', '4:00');
真值测试约束
when
方法可用于根据给定的真值测试结果来限制任务的执行。换句话说,如果给定的闭包返回 true
,则只要没有其他约束条件阻止任务运行,该任务就会执行
1Schedule::command('emails:send')->daily()->when(function () {2 return true;3});
skip
方法可以看作是 when
的反向操作。如果 skip
方法返回 true
,则计划的任务将不会执行
1Schedule::command('emails:send')->daily()->skip(function () {2 return true;3});
当使用链式 when
方法时,只有当所有 when
条件都返回 true
时,计划的命令才会执行。
环境约束
environments
方法可用于仅在给定环境(由 APP_ENV
环境变量定义)中执行任务
1Schedule::command('emails:send')2 ->daily()3 ->environments(['staging', 'production']);
时区
使用 timezone
方法,您可以指定计划任务的时间应在给定的时区内解释
1use Illuminate\Support\Facades\Schedule;2 3Schedule::command('report:generate')4 ->timezone('America/New_York')5 ->at('2:00')
如果您反复为所有计划任务分配相同的时区,则可以通过在应用程序的 app
配置文件中定义 schedule_timezone
选项来指定应分配给所有计划的时区
1'timezone' => 'UTC',2 3'schedule_timezone' => 'America/Chicago',
请记住,某些时区使用夏令时。当夏令时更改发生时,您的计划任务可能会运行两次甚至根本不运行。因此,我们建议尽可能避免时区调度。
防止任务重叠
默认情况下,即使任务的先前实例仍在运行,计划任务也会运行。要防止这种情况,您可以使用 withoutOverlapping
方法
1use Illuminate\Support\Facades\Schedule;2 3Schedule::command('emails:send')->withoutOverlapping();
在此示例中,如果 emails:send
Artisan 命令尚未运行,则每分钟运行一次。如果您有执行时间差异很大的任务,withoutOverlapping
方法特别有用,它可以防止您准确预测给定任务需要多长时间。
如果需要,您可以指定在“防止重叠”锁过期之前必须经过多少分钟。默认情况下,锁将在 24 小时后过期
1Schedule::command('emails:send')->withoutOverlapping(10);
在幕后,withoutOverlapping
方法利用您的应用程序的缓存来获取锁。如有必要,您可以使用 schedule:clear-cache
Artisan 命令清除这些缓存锁。这通常仅在任务由于意外的服务器问题而卡住时才需要。
在单台服务器上运行任务
要使用此功能,您的应用程序必须使用 database
、memcached
、dynamodb
或 redis
缓存驱动程序作为应用程序的默认缓存驱动程序。此外,所有服务器都必须与同一个中央缓存服务器通信。
如果您的应用程序调度器在多台服务器上运行,您可以将计划作业限制为仅在一台服务器上执行。例如,假设您有一个计划任务,每周五晚上生成一份新报告。如果任务调度器在三台工作服务器上运行,则计划任务将在所有三台服务器上运行,并生成报告三次。这可不好!
要指示任务应仅在一台服务器上运行,请在定义计划任务时使用 onOneServer
方法。第一台获得任务的服务器将获得作业的原子锁,以防止其他服务器同时运行同一任务
1use Illuminate\Support\Facades\Schedule;2 3Schedule::command('report:generate')4 ->fridays()5 ->at('17:00')6 ->onOneServer();
命名单服务器作业
有时您可能需要使用不同的参数调度同一作业,同时仍然指示 Laravel 在单台服务器上运行每个作业的排列组合。要完成此操作,您可以通过 name
方法为每个计划定义分配一个唯一的名称
1Schedule::job(new CheckUptime('https://laravel.net.cn'))2 ->name('check_uptime:laravel.com')3 ->everyFiveMinutes()4 ->onOneServer();5 6Schedule::job(new CheckUptime('https://vapor.laravel.net.cn'))7 ->name('check_uptime:vapor.laravel.com')8 ->everyFiveMinutes()9 ->onOneServer();
同样,如果计划的闭包要在单台服务器上运行,则必须为其分配名称
1Schedule::call(fn () => User::resetApiRequestCount())2 ->name('reset-api-request-count')3 ->daily()4 ->onOneServer();
后台任务
默认情况下,在同一时间计划的多个任务将按照它们在 schedule
方法中定义的顺序依次执行。如果您有长时间运行的任务,这可能会导致后续任务的启动时间比预期晚得多。如果您想在后台运行任务,以便它们可以同时运行,则可以使用 runInBackground
方法
1use Illuminate\Support\Facades\Schedule;2 3Schedule::command('analytics:report')4 ->daily()5 ->runInBackground();
runInBackground
方法只能在通过 command
和 exec
方法调度任务时使用。
维护模式
当应用程序处于维护模式时,您的应用程序计划任务将不会运行,因为我们不希望您的任务干扰您可能在服务器上执行的任何未完成的维护。但是,如果您想强制任务即使在维护模式下也运行,您可以在定义任务时调用 evenInMaintenanceMode
方法
1Schedule::command('emails:send')->evenInMaintenanceMode();
调度组
当使用类似的配置定义多个计划任务时,您可以使用 Laravel 的任务分组功能来避免为每个任务重复相同的设置。分组任务简化了您的代码,并确保了相关任务之间的一致性。
要创建计划任务组,请调用所需的任务配置方法,然后调用 group
方法。group
方法接受一个闭包,该闭包负责定义共享指定配置的任务
1use Illuminate\Support\Facades\Schedule;2 3Schedule::daily()4 ->onOneServer()5 ->timezone('America/New_York')6 ->group(function () {7 Schedule::command('emails:send --force');8 Schedule::command('emails:prune');9 });
运行调度器
现在我们已经学习了如何定义计划任务,接下来让我们讨论如何在服务器上实际运行它们。schedule:run
Artisan 命令将评估您的所有计划任务,并根据服务器的当前时间确定它们是否需要运行。
因此,当使用 Laravel 的调度器时,我们只需要在服务器上添加一个 cron 配置条目,该条目每分钟运行一次 schedule:run
命令。如果您不知道如何向服务器添加 cron 条目,请考虑使用托管平台,例如 Laravel Cloud,它可以为您管理计划任务的执行
1* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
亚分钟级调度任务
在大多数操作系统上,cron 作业最多只能每分钟运行一次。但是,Laravel 的调度器允许您以更频繁的间隔计划任务,甚至可以达到每秒一次
1use Illuminate\Support\Facades\Schedule;2 3Schedule::call(function () {4 DB::table('recent_users')->delete();5})->everySecond();
当在您的应用程序中定义了亚分钟级任务时,schedule:run
命令将继续运行到当前分钟结束,而不是立即退出。这允许命令在一分钟内调用所有必需的亚分钟级任务。
由于运行时间超出预期的亚分钟级任务可能会延迟后续亚分钟级任务的执行,因此建议所有亚分钟级任务都分派队列作业或后台命令来处理实际的任务处理
1use App\Jobs\DeleteRecentUsers;2 3Schedule::job(new DeleteRecentUsers)->everyTenSeconds();4 5Schedule::command('users:delete')->everyTenSeconds()->runInBackground();
中断亚分钟级任务
由于当定义了亚分钟级任务时,schedule:run
命令会在整个调用分钟内运行,因此您有时可能需要在部署应用程序时中断该命令。否则,已经运行的 schedule:run
命令实例将继续使用您应用程序先前部署的代码,直到当前分钟结束。
要中断正在进行的 schedule:run
调用,您可以将 schedule:interrupt
命令添加到应用程序的部署脚本中。此命令应在您的应用程序完成部署后调用
1php artisan schedule:interrupt
在本地运行调度器
通常,您不会在本地开发机器上添加调度器 cron 条目。相反,您可以使用 schedule:work
Artisan 命令。此命令将在前台运行,并每分钟调用一次调度器,直到您终止该命令。当定义了亚分钟级任务时,调度器将在一分钟内继续运行以处理这些任务
1php artisan schedule:work
任务输出
Laravel 调度器提供了几种便捷的方法来处理计划任务生成的输出。首先,使用 sendOutputTo
方法,您可以将输出发送到文件以供以后检查
1use Illuminate\Support\Facades\Schedule;2 3Schedule::command('emails:send')4 ->daily()5 ->sendOutputTo($filePath);
如果您想将输出附加到给定的文件,可以使用 appendOutputTo
方法
1Schedule::command('emails:send')2 ->daily()3 ->appendOutputTo($filePath);
使用 emailOutputTo
方法,您可以将输出通过电子邮件发送到您选择的电子邮件地址。在通过电子邮件发送任务的输出之前,您应该配置 Laravel 的电子邮件服务
1Schedule::command('report:generate')2 ->daily()3 ->sendOutputTo($filePath)
如果您只想在计划的 Artisan 或系统命令以非零退出代码终止时通过电子邮件发送输出,请使用 emailOutputOnFailure
方法
1Schedule::command('report:generate')2 ->daily()
emailOutputTo
、emailOutputOnFailure
、sendOutputTo
和 appendOutputTo
方法是 command
和 exec
方法独有的。
任务钩子
使用 before
和 after
方法,您可以指定在计划任务执行之前和之后执行的代码
1use Illuminate\Support\Facades\Schedule; 2 3Schedule::command('emails:send') 4 ->daily() 5 ->before(function () { 6 // The task is about to execute... 7 }) 8 ->after(function () { 9 // The task has executed...10 });
onSuccess
和 onFailure
方法允许您指定在计划任务成功或失败时执行的代码。失败表示计划的 Artisan 或系统命令以非零退出代码终止
1Schedule::command('emails:send')2 ->daily()3 ->onSuccess(function () {4 // The task succeeded...5 })6 ->onFailure(function () {7 // The task failed...8 });
如果您的命令有输出可用,您可以通过类型提示 Illuminate\Support\Stringable
实例作为钩子闭包定义的 $output
参数,在 after
、onSuccess
或 onFailure
钩子中访问它
1use Illuminate\Support\Stringable; 2 3Schedule::command('emails:send') 4 ->daily() 5 ->onSuccess(function (Stringable $output) { 6 // The task succeeded... 7 }) 8 ->onFailure(function (Stringable $output) { 9 // The task failed...10 });
Ping URL
使用 pingBefore
和 thenPing
方法,调度器可以在任务执行之前或之后自动 ping 给定的 URL。此方法对于通知外部服务(例如 Envoyer)您的计划任务正在开始或已完成执行非常有用
1Schedule::command('emails:send')2 ->daily()3 ->pingBefore($url)4 ->thenPing($url);
pingOnSuccess
和 pingOnFailure
方法可用于仅在任务成功或失败时 ping 给定的 URL。失败表示计划的 Artisan 或系统命令以非零退出代码终止
1Schedule::command('emails:send')2 ->daily()3 ->pingOnSuccess($successUrl)4 ->pingOnFailure($failureUrl);
pingBeforeIf
、thenPingIf
、pingOnSuccessIf
和 pingOnFailureIf
方法可用于仅在给定条件为 true
时 ping 给定的 URL
1Schedule::command('emails:send')2 ->daily()3 ->pingBeforeIf($condition, $url)4 ->thenPingIf($condition, $url);5 6Schedule::command('emails:send')7 ->daily()8 ->pingOnSuccessIf($condition, $successUrl)9 ->pingOnFailureIf($condition, $failureUrl);
事件
Laravel 在调度过程中分派各种事件。您可以为以下任何事件定义监听器
事件名称 |
---|
Illuminate\Console\Events\ScheduledTaskStarting |
Illuminate\Console\Events\ScheduledTaskFinished |
Illuminate\Console\Events\ScheduledBackgroundTaskFinished |
Illuminate\Console\Events\ScheduledTaskSkipped |
Illuminate\Console\Events\ScheduledTaskFailed |