v0.21

スケジューリングとコマンド

はじめに

dframeworkは定期的なバックグラウンドタスクをアプリケーションコード内で直接定義できる組み込みタスクスケジューラーを備えています。サーバー上でシステムレベルのcronジョブを設定する代わりに単一のファイルでスケジュールを定義するだけでフレームワークが残りの処理を管理します。タスクにはコマンドクラスへの参照またはインライン関数を指定できます。

スケジューラーはアプリケーションの起動時に自動的に開始されプロセスの生存期間中動作し続けます。各タスクは分離されたコンテキストでメインスレッド内で同期的に実行され完了後に自動的に再スケジュールされます。

スケジュールの定義

スケジュールファイル

スケジュールはプロジェクトルートのconsole/Schedule.jsで定義します。このファイルはSchedulerインスタンスを受け取るデフォルト関数をエクスポートします。タスクを登録するにはスケジューラーのcommand()メソッドを使用し実行頻度メソッドをチェーンします。

1export default function (scheduler) {
2 scheduler.command('CleanupExpiredSessions').daily();
3 scheduler.command('SyncExternalData').everyFifteenMinutes();
4 scheduler.command('GenerateSitemaps').weekly();
5}

フレームワークは起動時にこのファイルを自動的に検出し定義されたスケジュールの実行を開始します。

コマンドのスケジューリング

scheduler.command()に文字列を渡すとスケジューラーはconsole/commandsディレクトリ内のコマンドファイルとして解決し${name}.jsと${name}Command.jsの両方を検索します。このファイルはhandle()メソッドを持つクラスをデフォルトエクスポートする必要があります。

1scheduler.command('PruneOldLogs').daily();
2scheduler.command('Report').args(['--format=pdf', 'sales']).daily();

これによりconsole/commands/PruneOldLogs.jsまたはconsole/commands/PruneOldLogsCommand.jsが解決されクラスがインスタンス化され指定された間隔でhandle()メソッドが呼び出されます。.args(argsArray)をチェーンすることで引数とオプションをコマンドインスタンスに転送できます。

クロージャのスケジューリング

個別のコマンドファイルを必要としない単純なタスクの場合はインライン関数を直接渡すことができます。

1export default function (scheduler) {
2 scheduler.command(async () => {
3 const count = await Session.where('expires_at', '<', new Date()).delete();
4 Log.info(`pruned ${count} expired sessions`);
5 }).everyThirtyMinutes();
6}

実行頻度オプション

プリセット間隔

スケジューラーはcommand()の後にチェーンできる直感的なプリセット間隔メソッドのセットを提供します。

メソッド 間隔
everyMinute() 60秒
everyFiveMinutes() 5分
everyTenMinutes() 10分
everyFifteenMinutes() 15分
everyThirtyMinutes() 30分
hourly() 1時間
daily() 24時間
weekly() 7日
1scheduler.command('HeartbeatCheck').everyMinute();
2scheduler.command('CacheWarmer').hourly();
3scheduler.command('WeeklyDigest').weekly();

カスタム間隔

プリセットでカバーされていない間隔についてはミリ秒単位の期間を指定してevery()メソッドを使用します。

1scheduler.command('PollExternalApi').every(45000);
2scheduler.command('RotateApiKeys').every(12 * 60 * 60 * 1000);

nodeの32ビット整数タイムアウト制限のため間隔は2147483647ミリ秒(約24.8日)を超えることはできません。この期間を超える間隔(月次や四半期ごとのジョブなど)についてはdstrn run <command>を使用して必要に応じてコマンドを実行するシステムcronジョブを設定してください。

コマンドの作成

コマンドクラス

コマンドはconsole/commandsディレクトリに保存されるクラスです。async handle(args, options)メソッドを持つクラスをデフォルトエクスポートする必要があります。handleメソッドにはコマンド実行時に実行されるロジックが含まれます。

1export default class PruneOldLogsCommand {
2 async handle(args, options) {
3 const cutoff = new Date();
4 cutoff.setDate(cutoff.getDate() - 30);
5 await DB.table('logs').where('created_at', '<', cutoff).delete();
6 Log.info('old logs pruned');
7 }
8}

スケジュールされたコマンドインスタンスは引数ヘルパー(this.option()、this.hasOption()、this.argument()、this.options、this.arguments、this.rawArgs)を提供します。自動スケジューラーによってトリガーされたコマンドは空の引数(handle([], {}))で実行されdstrn runによる手動実行では引数とオプションが転送されます(handle(rawArgs, options))。

コマンドの生成

cliを使用して新しいコマンドファイルをスキャフォールディングできます。

1dstrn make:command PruneOldLogs

これにより適切な定型構造を持つconsole/commands/PruneOldLogsCommand.jsが作成されます(ジェネレーターは末尾にCommandサフィックスがない場合自動的に追加します)。

コマンドの実行

run cliコマンドを使用してスケジュールされた任意のコマンドをオンデマンドで実行できます。

1dstrn run PruneOldLogs

dstrn run経由で手動実行する場合コマンド名の後に渡された追加の引数とオプションはhandle(args, options)に転送されthis.option()およびthis.argument()からアクセスできます。自動スケジューラーによってトリガーされた場合はhandle([], {})が空の引数で実行されます。dframeworkは完了時に経過した実行時間を報告します。

スケジューラーの仕組み

自動起動

アプリケーションの起動時フレームワークはconsole/Schedule.jsファイルの存在を確認します。存在する場合フレームワークはそれをインポートし新しいSchedulerインスタンスを渡しすべてのタスクが登録された後にscheduler.start()を呼び出します。登録された各タスクは設定された間隔の経過後に実行されるようスケジュールされその後継続的に再スケジュールされます。

実行と再スケジュール

タスクの間隔が経過するとスケジューラーはタスクのハンドラー(コマンドクラスまたはインライン関数)を呼び出します。タスク完了後スケジューラーは設定された間隔から経過した実行時間を差し引くことで次回の実行時間を計算します。これによりタスクの完了に大幅な時間がかかった場合でも実行間隔の一貫性が保たれます。次回の実行はsetTimeoutを使用してスケジュールされます。

各タスクはlastRunタイムスタンプを追跡します。スケジューラーはこれを使用して次回実行までの適切な遅延を算出します。

手動実行

scheduler.run()を使用して登録された任意のスケジュールタスクを名前でプログラムからトリガーできます。

1await app.scheduler.run('CleanupExpiredSessions');

これによりスケジュールされた定期タイマーを変更することなくオンデマンドでタスクを即座に1回実行します。

エラーハンドリング

NOTE

スケジュールされたタスクによってスローされたエラーはログに記録され分離されます。失敗したタスクは他のタスクに影響を与えたりサーバーを中断させたりすることなく自動的に再スケジュールされます。

1[Scheduler] PruneOldLogs caused error: ER_NO_SUCH_TABLE: Table 'logs' doesn't exist

スケジュールフェーズ中にタスク自体が予期しないエラーを引き起こした場合個別のcatchがそれをログに記録しエラーがメインプロセスに伝播するのを防ぎます。