Gin 本身不支持定时任务，因其仅为 HTTP 路由框架，无内置调度能力；定时任务需用 robfig/cron/v3 等独立库，在 main 函数中初始化依赖后启动，且不可依赖 gin.Context 或在 Handler 中动态创建。
为什么 Gin 本身不支持定时任务
Gin 是一个 HTTP 路由框架，Gin 的核心职责是处理请求、中间件、路由分发，它没有内置的定时器调度能力。试图在 gin.Engine 上直接注册 cron 任务或调用 time.Ticker 启动 goroutine 并不构成“Gin 的定时任务配置”——那只是你在 Gin 进程里手动启了一个 goroutine，和 Gin 本身无关。
常见错误现象：panic: runtime error: invalid memory address or nil pointer dereference，往往是因为在未初始化的全局变量（比如未初始化的数据库连接）上执行定时任务；或者任务函数里用了 gin.Context，但该 context 已随 HTTP 请求结束被回收，导致 panic。
- 定时任务必须独立于 HTTP 请求生命周期运行
- 不能依赖
c *gin.Context，因为定时任务没有上下文 - 所有依赖（如 DB、Redis 客户端）需提前初始化并传入任务函数
用 github.com/robfig/cron/v3 启动独立调度器
robfig/cron/v3 是 Go 生态最稳定的 cron 库，兼容 Go module，支持秒级精度（v3 版本起），且与 Gin 完全解耦。关键不是“集成到 Gin”，而是“和 Gin 同进程共存”。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在
main()函数中，先初始化所有依赖（DB、logger、cache 等），再创建cron.New()实例 - 用
c.AddFunc("0 0 * * *", func() { ... })添加任务，注意 cron 表达式格式：秒 分 时 日 月 周（v3 默认支持 6 位） - 调用
c.Start()启动调度器，**必须在router.Run()之前或之后单独 go 启动，不能阻塞 HTTP 服务** - 务必在程序退出前调用
c.Stop()，否则可能泄露 goroutine
示例片段：
func main() {
r := gin.Default()
// 初始化 DB、Redis 等...
db := initDB()
cache := initCache()
<pre class='brush:php;toolbar:false;'>c := cron.New(cron.WithSeconds()) // 启用秒级支持
c.AddFunc("*/10 * * * * *", func() { // 每 10 秒执行一次
cleanupExpiredSessions(db, cache)
})
c.Start()
defer c.Stop() // 注意 defer 位置
r.GET("/health", func(c *gin.Context) {
c.JSON(200, gin.H{"status": "ok"})
})
r.Run(":8080")}
避免在 Handler 里启动定时任务
有人尝试在某个 API 接口里调用 time.AfterFunc 或新建 cron.Cron 实例，这是危险操作。每次请求都新建调度器，会导致 goroutine 泄露、重复任务、内存暴涨。
典型错误场景：
-
POST /api/schedule接口里调用cron.New().AddFunc(...).Start() - 用闭包捕获
*gin.Context并传给定时函数 - 未做去重控制，同一任务被多次注册
正确做法：定时任务配置应是应用启动期的静态行为，不是运行时动态行为。若需动态调度（如用户自定义任务），应使用持久化存储（如 MySQL 表记录任务配置）+ 单一全局调度器 + 定期轮询加载变更。
日志与错误处理容易被忽略
定时任务失败默认静默，不会打印到 Gin 的日志中间件里。如果任务里发生 panic 或数据库超时，整个调度器可能停止（取决于 cron 配置）。
必须显式处理：
- 每个任务函数外层加
defer func() { if err := recover(); err != nil { log.Printf("cron panic: %v", err) } }() - 使用
cron.WithChain(cron.Recover(cron.DefaultLogger))启用 panic 捕获 - 任务内所有 I/O 操作（DB 查询、HTTP 调用）必须设 timeout，避免阻塞调度线程
- 不要在任务里调用
log.Fatal或os.Exit，这会杀死整个 Gin 进程
复杂点在于：任务失败后是否重试、是否告警、是否幂等，这些都不属于 Gin 或 cron 库的职责，得靠你自己设计补偿逻辑。
