定时任务集成

XYGo Admin 2026-04-22 1 次阅读

Cron任务注册、执行周期配置

扩展可以注册定时任务，调度周期在后台管理界面配置。

扩展与主包的关系：与消息队列一样，使用同一套 xygo/internal/library/cron 基础设施：

对比项	主包	扩展
任务位置	`server/internal/crons/*.go`	`server/addons/{name}/crons/*.go`
包名	`package crons`	`package crons`
触发方式	`main.go` 空导入	`module.go` 空导入 `_ "xygo/addons/{name}/crons"`
任务命名	`queue_alert`、`log_clean`	加扩展前缀：`shop.order_timeout`

注册任务

在 crons/ 子目录下创建任务文件：

go 复制代码

// server/addons/shop/crons/order_timeout.go
package crons

import (
    "context"
    "fmt"

    cronlib "xygo/internal/library/cron"
)

func init() {
    cronlib.Register(&OrderTimeoutTask{})
}

type OrderTimeoutTask struct{}

func (t *OrderTimeoutTask) GetName() string {
    return "shop.order_timeout"
}

func (t *OrderTimeoutTask) Execute(ctx context.Context, params []string) (string, error) {
    cancelCount := 5
    return fmt.Sprintf("取消了 %d 个超时订单", cancelCount), nil
}

注意：因为子目录包名是 crons，与系统库 cron 同名，需要用别名 cronlib 导入。

Task 接口

go 复制代码

type Task interface {
    GetName() string
    Execute(ctx context.Context, params []string) (string, error)
}

工作流程

代码注册：扩展在 init() 中调用 cron.Register() 将任务放入内存注册表
后台配置：管理员在系统管理 → 定时任务中添加任务，配置 cron 表达式和参数
启动调度：系统启动时从数据库读取已启用的任务，匹配注册表后启动调度

注意：只在代码中 Register 不会自动运行任务，还需要在后台管理界面中添加并启用。

Cron 表达式

采用标准 6 位 cron 格式（秒分时日月周）：

复制代码

*/30 * * * * *     每30秒
0 */5 * * * *      每5分钟
0 0 2 * * *        每天凌晨2点
0 0 0 1 * *        每月1号0点

任务名规范

复制代码

shop.order_timeout     ✓ 正确（扩展名.任务描述）
shop.daily_report      ✓ 正确
order_timeout          ✗ 避免（缺少扩展名前缀）