任務調度 · Laravel5.8筆記

# 任務調度 - [簡介](#introduction) - [定義調度](#defining-schedules) - [Artisan 命令調度](#scheduling-artisan-commands) - [隊列任務調度](#scheduling-queued-jobs) - [Shell 命令調度](#scheduling-shell-commands) - [調度頻率設置](#schedule-frequency-options) - [時區](#timezones) - [避免任務重復](#preventing-task-overlaps) - [任務只運行在一臺服務器上](#running-tasks-on-one-server) - [后臺任務](#background-tasks) - [維護模式](#maintenance-mode) - [任務輸出](#task-output) - [任務鉤子](#task-hooks) <a name="introduction"></a> ## 簡介過去，你可能需要在服務器上為每一個調度任務去創建 Cron 入口。但是這種方式很快就會變得不友好，因為這些任務調度不在源代碼中，并且你每次都需要通過 SSH 鏈接登錄到服務器中才能增加 Cron 入口。 Laravel 命令行調度器允許你在 Laravel 中對命令調度進行清晰流暢的定義。且使用這個任務調度器時，你只需要在你的服務器上創建單個 Cron 入口接口。你的任務調度在 `app/Console/Kernel.php` 的 `schedule` 方法中進行定義。為了幫助你更好的入門，這個方法中有個簡單的例子。 ### 啟動調度器當使用這個調度器時，你只需要把下面的 Cron 入口添加到你的服務器中即可。如果你不知道怎么在服務器中添加 Cron 入口，可以考慮使用一些服務來管理 Cron 入口，比如 [Laravel Forge](https://forge.laravel.com)： * * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1 這個 Cron 為每分鐘執行一次 Laravel 的命令行調度器。當 `schedule:run` 命令被執行的時候，Laravel 會根據你的調度執行預定的程序。 <a name="defining-schedules"></a> ## 定義調度你可以在 `App\Console\Kernel` 類的 `schedule` 方法中定義所有的調度任務。在開始之前，讓我們來看一個例子。在這個例子中，我們計劃每天午夜調用一個閉包。在閉包中，我們執行一個數據庫查詢來清空一張表： <?php namespace App\Console; use Illuminate\Support\Facades\DB; use Illuminate\Console\Scheduling\Schedule; use Illuminate\Foundation\Console\Kernel as ConsoleKernel; class Kernel extends ConsoleKernel { /** * 應用里的自定義 Artisan 命令 * * @var array */ protected $commands = [ // ]; /** * 定義計劃任務 * * @param \Illuminate\Console\Scheduling\Schedule $schedule * @return void */ protected function schedule(Schedule $schedule) { $schedule->call(function () { DB::table('recent_users')->delete(); })->daily(); } } 除了使用閉包來定義任務調度外，你也可以用 [invokable objects](http://php.net/manual/zh/language.oop5.magic.php#object.invoke)。 $schedule->call(new DeleteRecentUsers)->daily(); <a name="scheduling-artisan-commands"></a> ### Artisan 命令調度除了使用調用閉包這種方式來調度外，你還可以調用 [Artisan 命令](/docs/{{version}}/artisan) 和操作系統命令。比如，你可以給 `command` 方法傳遞命令名稱或者類來調度一個 Artisan 命令。 $schedule->command('emails:send --force')->daily(); $schedule->command(EmailsCommand::class, ['--force'])->daily(); <a name="scheduling-queued-jobs"></a> ### 隊列任務調度 `job` 方法可以用來調度 [隊列任務](/docs/{{version}}/queues)。此方法提供了一種快捷的方式來調度任務，而無需使用 `call` 方法創建閉包來調度任務。 $schedule->job(new Heartbeat)->everyFiveMinutes(); // 分發任務到「heartbeats」隊列... $schedule->job(new Heartbeat, 'heartbeats')->everyFiveMinutes(); <a name="scheduling-shell-commands"></a> ### Shell 命令調度 `exec` 方法可用于向操作系統發送命令： $schedule->exec('node /home/forge/script.js')->daily(); <a name="schedule-frequency-options"></a> ### 調度頻率設置當然了，你可以給你的任務分配多種調度計劃：方法 | 描述 ------------- | ------------- `->cron('* * * * *');` | 自定義 Cron 時間表執行任務 `->everyMinute();` | 每分鐘執行一次任務 `->everyFiveMinutes();` | 每五分鐘執行一次任務 `->everyTenMinutes();` | 每十分鐘執行一次任務 `->everyFifteenMinutes();` | 每十五分鐘執行一次任務 `->everyThirtyMinutes();` | 每三十分鐘執行一次任務 `->hourly();` | 每小時執行一次任務 `->hourlyAt(17);` | 每小時第 17 分鐘執行一次任務 `->daily();` | 每天午夜執行一次任務（譯者注：每天零點） `->dailyAt('13:00');` | 每天 13 點執行一次任務 `->twiceDaily(1, 13);` | 每天 1 點和 13 點分別執行一次任務 `->weekly();` | 每周執行一次任務 `->weeklyOn(1, '8:00');` | 每周一的 8 點執行一次任務 `->monthly();` | 每月執行一次任務 `->monthlyOn(4, '15:00');` | 每月 4 號的 15 點執行一次任務 `->quarterly();` | 每季度執行一次任務 `->yearly();` | 每年執行一次任務 `->timezone('America/New_York');` | 設定時區結合其他一些特定條件，我們可以生成在一周中特定時間運行的任務。舉個例子，在每周一執行命令： // 每周一 13:00 執行... $schedule->call(function () { // })->weekly()->mondays()->at('13:00'); // 工作日（周一至周五） 8點至 17 點每小時執行一次... $schedule->command('foo') ->weekdays() ->hourly() ->timezone('America/Chicago') ->between('8:00', '17:00'); 額外的限制條件列表如下：方法 | 描述 ------------- | ------------- `->weekdays();` | 限制任務在工作日執行 `->weekends();` | 限制任務在周末執行 `->sundays();` | 限制任務在周日執行 `->mondays();` | 限制任務在周一執行 `->tuesdays();` | 限制任務在周二執行 `->wednesdays();` | 限制任務在周三執行 `->thursdays();` | 限制任務在周四執行 `->fridays();` | 限制任務在周五執行 `->saturdays();` | 限制任務在周六執行 `->between($start, $end);` | 限制任務在 `$start` 和 `$end` 之間執行 `->when(Closure);` | 當閉包返回為真時執行 `->environments($env);` | 限制任務在特定環境中執行 #### 時間范圍限制使用 `between` 來限制任務在一天中的某個時間段來執行： $schedule->command('reminders:send') ->hourly() ->between('7:00', '22:00'); 或者使用 `unlessBetween` 方法來為任務排除一個時間段： $schedule->command('reminders:send') ->hourly() ->unlessBetween('23:00', '4:00'); #### 閉包測試限制使用 `when` 方法來根據測試結果來執行任務。也就是說，如果給定的閉包返回結果為 `true`，只要沒有其他約束條件阻止任務運行，任務就會一直執行下去： $schedule->command('emails:send')->daily()->when(function () { return true; }); `skip` 方法可以看做是 `when` 方法的逆過程。如果 `skip` 方法返回 `true`，任務就不會執行： $schedule->command('emails:send')->daily()->skip(function () { return true; }); 使用鏈式調用 `when` 方法時，只有所有的 `when` 都返回 `true` 時，任務才會執行。 #### 環境約束 `environments` 方法可用于僅在給定環境中執行任務： $schedule->command('emails:send') ->daily() ->environments(['staging', 'production']); <a name="timezones"></a> ### 時區使用 `timezone` 方法，你可以指定任務在給定的時區內執行： $schedule->command('report:generate') ->timezone('America/New_York') ->at('02:00') 如果要為所有計劃任務分配相同的時區，則可能希望在 `app/Console/Kernel.php` 文件中定義 `scheduleTimezone` 方法。此方法應返回應分配給所有計劃任務的默認時區： /** * 獲取默認情況下應為預定事件使用的時區。 * * @return \DateTimeZone|string|null */ protected function scheduleTimezone() { return 'America/Chicago'; } > {note} 請記住，有些時區會使用夏令時。當夏時制時間發生更改時，你的任務可能會執行兩次，甚至根本不會執行。所以我們建議盡可能避免使用時區來安排計劃任務。 <a name="preventing-task-overlaps"></a> ### 避免任務重復默認情況下，即使之前的任務還在執行，調度內任務也會執行。你可以使用 `withoutOverlapping` 方法來避免這種情況： $schedule->command('emails:send')->withoutOverlapping(); 在這個例子中，如果 `emails:send` [Artisan 命令](/docs/{{version}}/artisan) 沒有正在運行，它將會每分鐘執行一次。如果你的任務執行時間不確定，且你又不能準確預估出任務的執行時間，那么 `withoutOverlapping` 方法會顯得特別有用。如果有需要，你可以指定「without overlapping」鎖指定的時間范圍。默認情況下，鎖將在 24 小時后過期。 $schedule->command('emails:send')->withoutOverlapping(10); <a name="running-tasks-on-one-server"></a> ### 任務只運行在一臺服務器上 > {note} 要使用這個特性，你的應用默認緩存驅動必須是 `memcached` 或者 `redis`。除此之外，所有的服務器必須使用同一個中央緩存服務器通信。如果你的應用在多個服務器上運行，你可能需要限制你的調度任務只在單個服務器上運行。假設你有一個調度任務：每周五晚生成一份新報告。如果這個任務調度器在三個服務器上運行，那么這個任務會在三臺服務器上運行且生成三份報告。這樣不好！為了說明任務應該在單個服務器上運行，在定義調度任務時使用 `onOneServer` 方法。第一個獲取到任務的服務器會生成一個原子鎖，用來防止其他服務器在同一時刻執行相同任務。 $schedule->command('report:generate') ->fridays() ->at('17:00') ->onOneServer(); <a name="background-tasks"></a> ### 后臺任務默認情況下，同時調度的多個命令將按順序執行。如果你有長時間運行的命令，這可能會導致后續命令的啟動時間比預期的要晚。因此，你想在后臺同時運行命令，可以使用 `runInBackground` 方法： $schedule->command('analytics:report') ->daily() ->runInBackground(); <a name="maintenance-mode"></a> ### 維護模式 Laravel 的隊列任務在 [維護模式](/docs/{{version}}/configuration#maintenance-mode) 下不會運行。因為我們不想你的調度任務干擾到你服務器上可能還未完成的項目。不過，如果你確實是想在維護模式下強制調度任務執行，你可以使用 `evenInMaintenanceMode` 方法： $schedule->command('emails:send')->evenInMaintenanceMode(); <a name="task-output"></a> ## 任務輸出 Laravel 調度器提供了一些方便的方法來處理調度任務輸出。首先，你可以使用 `sendOutputTo` 方法來輸出到文件以便于后續檢查： $schedule->command('emails:send') ->daily() ->sendOutputTo($filePath); 如果希望將輸出 `附加` 到給定文件，可以使用 `appendOutputTo` 方法 $schedule->command('emails:send') ->daily() ->appendOutputTo($filePath); 使用 `emailOutputTo` 方法，你可以將輸出發送到指定郵箱。在使用郵件發送之前，你需要配置 Laravel 的 [郵件服務](/docs/{{version}}/mail)： $schedule->command('foo') ->daily() ->sendOutputTo($filePath) ->emailOutputTo('foo@example.com'); > {note} `emailOutputTo`，`sendOutputTo` 和 `appendOutputTo` 方法是 `command` 和 `exec` 獨有的。 <a name="task-hooks"></a> ## 任務鉤子使用 `before` 和 `after` 方法，你可以在調度任務執行前或者執行后來執行特定代碼： $schedule->command('emails:send') ->daily() ->before(function () { // Task is about to start... }) ->after(function () { // Task is complete... }); #### Ping 網址使用 `pingBefore` 和 `thenPing` 方法，你可以在任務執行前或者執行后來 ping 指定的 URL。這個方法在通知外部服務（比如 [Laravel Envoyer](https://envoyer.io)）時將會特別有用： $schedule->command('emails:send') ->daily() ->pingBefore($url) ->thenPing($url); 只有在給定條件為 `true` 時，才能使用 `pingBeforeIf` 和 `thenPingIf` 方法 ping 指定的 URL： $schedule->command('emails:send') ->daily() ->pingBeforeIf($condition, $url) ->thenPingIf($condition, $url); 所有 ping 方法都需要 Guzzle HTTP 庫。你可以使用 Composer 來添加 Guzzle 到你的項目中： composer require guzzlehttp/guzzle