5.19 定时任务调度机制

:::tip 概述调度基于 robfig/cron：调度器基础设施在 service 的 job 模块，任务实现集中放在 internal/task 包，经 init 自注册、按任务记录的 url 字段数据驱动查找。配套执行锁、任务日志与管理界面。 :::

架构分工

internal/service/job*.go     调度器基础设施（cron 挂载/摘除/执行分派/执行锁）
internal/task/*.go           任务处理方法（一任务一文件，init 自注册）
service.DaemonInit           启动接线（cmd/api 在启动序列调用）
cmd/api                      空白导入 task 包 → 触发 init 注册

依赖方向单向：task → service（注册 + 共享能力），service 不反向依赖 task。

任务实现契约

// internal/task/xxx.go
func init() {
    service.RegisterJobHandler("任务名", handler)   // 注册名 = 任务记录 url 字段值
}

// 处理方法签名
func(ctx context.Context, params string) (string, error)
// params：任务参数（JSON 字符串，可为空）
// 返回：写入任务日志摘要的文本

新增任务三步：写 task 文件 → init 注册 → 管理界面建任务记录（url 填注册名 + cron 表达式）。不改调度器一行代码。

内置任务

任务	职责
LogClean	按 `job.logRetentionDays`（默认 90 天）物理清理超期的操作/登录/任务日志（经 WithPhysicalDelete 放行）
SendSms	短信发送示例任务
HelloWorld	演示任务

执行可靠性

机制	说明
执行锁	键 TTL `job.lockTTLSeconds`（默认 300 秒），执行期自动续期；长任务超时也不会被并发抢占
任务日志	每次执行写 gin_job_log（开始/结束/耗时/结果/摘要）
失败处理	错误写入任务日志，不影响下次调度
启动恢复	DaemonInit 按数据库任务记录重建 cron 挂载

管理界面

任务管理页（monitor/job）：任务 CRUD、cron 表达式配置、启停、手动执行、执行日志查看。见 6.16 定时任务管理。

配置

job:
  logRetentionDays: 90     # 日志保留天数（LogClean 消费）
  lockTTLSeconds: 300      # 执行锁 TTL（任务参数可覆盖）

优雅关闭

关闭链中"停定时任务"排在"关 DB"之前——任务可能还在写库，先停任务再关连接，避免执行期报错。

下一步

→ 第 6 章业务模块

2.5 KiB Raw Blame History Unescape Escape