encore-go-cron

Encore Go Cron ジョブ

手順

Encore Go における cron.NewJob 宣言は、スケジュールを既存の //encore:api エンドポイントに紐付けます。エンドポイントは選択した周期で実行されます。ジョブはパッケージレベルの変数として宣言してください。関数の内部では宣言しないでください。

package cleanup

import (
    "context"
    "encore.dev/cron"
)

// 1. The endpoint to call (typically private: //encore:api private)
//encore:api private
func CleanupExpiredSessions(ctx context.Context) error {
    // Cleanup logic
    return nil
}

// 2. Package-level cron declaration
var _ = cron.NewJob("cleanup-sessions", cron.JobConfig{
    Title:    "Clean up expired sessions",
    Schedule: "0 * * * *", // Every hour
    Endpoint: CleanupExpiredSessions,
})

スケジュール形式

フィールド	例	説明
Every	"1h"、"30m"、"6h"	単純な間隔。24 時間を割り切れる必要があります — "7h" は無効です。
Schedule	"0 9 * * 1"	標準的な cron 式（5 フィールド、UTC）。

よく使われる cron 式

Cron	意味
"0 * * * *"	毎時 0 分
"0 2 * * *"	毎日 02:00 UTC
"0 0 * * 0"	毎週日曜日の深夜 0 時 UTC
"0 4 15 * *"	毎月 15 日の 04:00 UTC

重要な動作

• encore run でローカル実行している場合、cron ジョブは実行されません。 cron が発火するのはデプロイされた環境のみです。
• cron エンドポイントは private にして、外部からトリガーできないようにする必要があります。呼び出すのは cron スケジューラーだけにしてください。
• Schedule の時刻はすべて UTC です。スケジュールを設計する際はローカル時刻から変換してください。
• エンドポイントはモジュールの読み込み時に定義する必要があります。cron.NewJob の参照より前に宣言してください。

ガイドライン

• 「一定間隔で実行する」場合は Every を使用します（24 時間を割り切れる必要があります）。
• 特定の時刻や曜日に実行する場合は Schedule を使用します。
• エンドポイントのロジックは冪等に保ってください。cron は遅れて発火したり、再デプロイの時間帯にリトライされたりする可能性があります。
• 時間駆動ではなくイベント駆動のバックグラウンド処理には、代わりに encore-go-pubsub スキルを使用してください。