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"	简单间隔。必须能被 24h 整除——"7h" 无效。
Schedule	"0 9 * * 1"	标准 cron 表达式（5 个字段，UTC）。

常见 cron 表达式

Cron	含义
"0 * * * *"	每小时整点
"0 2 * * *"	每天 UTC 时间 02:00
"0 0 * * 0"	每周日 UTC 时间午夜
"0 4 15 * *"	每月 15 日 UTC 时间 04:00

重要行为

• 使用 encore run 在本地运行时，定时任务不会执行。 只有已部署的环境才会触发定时任务。
• 定时任务端点应设为 private，以避免被外部触发——只能由定时任务调度器调用。
• Schedule 中的所有时间均为 UTC。设计计划时，请将本地时间转换为 UTC。
• 端点必须在模块加载时定义——请在引用它的 cron.NewJob 之前声明端点。

指南

• 对于“按固定间隔运行”，请使用 Every（间隔必须能被 24h 整除）。
• 对于特定时间或星期几，请使用 Schedule。
• 确保端点逻辑具有幂等性：定时任务可能延迟触发，也可能在重新部署期间重试。
• 对于事件驱动的后台工作（而非时间驱动），请改用 encore-go-pubsub 技能。