Golang的 cron 库

news/2025/10/22 11:33:41/文章来源:https://www.cnblogs.com/yubo-guan/p/19157551

🔍 Cron 表达式
💡 核心特性与用法
- 预定义模式与间隔
- 基本使用步骤
- 时区设置
- 高级选项
简单示例
⚠️ 版本注意与总结

Golang 的 cron 库用于处理定时任务，其中 github.com/robfig/cron/v3 是一个广泛使用的、功能丰富的库，它支持标准的 cron 表达式，并且易于使用。

🔍 Cron 表达式

robfig/cron/v3 库支持标准的 cron 表达式来定义任务计划。表达式由 5 个或 6 个时间字段组成（取决于是否启用秒级精度），各字段含义如下：

字段	是否强制	允许值	允许的特殊字符
Seconds	可选	0-59	`* / , -`
Minutes	是	0-59	`* / , -`
Hours	是	0-23	`* / , -`
Day of month	是	1-31	`* / , - ? L W`
Month	是	1-12 或 JAN-DEC	`* / , -`
Day of week	是	0-6 或 SUN-SAT	`* / , - ? L #`

特殊字符的含义：

*：匹配该字段的所有值。
/：用于指定步长，例如 */5 * * * * * 表示每 5 秒执行一次。
,：用于列出多个值，例如 * * 5,10,15 3,4 * * 表示三月或四月的 5、10、15 日执行。
-：用于指定一个范围，例如 */5 * 10-12 * * * 表示每天 10 点到 12 点每 5 秒执行一次。
?：用于替代 *，通常在“日期”和“星期”字段中用于避免冲突。

💡 核心特性与用法

robfig/cron/v3 库提供了以下核心功能：

灵活的时间表达式：除了标准的 cron 表达式，还支持预定义模式和间隔描述符。
任务管理：可以动态添加、移除任务，并控制调度器的启动与停止。
可扩展性：支持通过装饰器模式添加日志、恢复等功能。

预定义模式与间隔

为了简化配置，库提供了一些预定义的模式：

@yearly 或 @annually：每年执行一次，等同于 0 0 1 1 *。
@monthly：每月执行一次，等同于 0 0 1 * *。
@weekly：每周执行一次，等同于 0 0 * * 0。
@daily 或 @midnight：每天执行一次，等同于 0 0 * * *。
@hourly：每小时执行一次，等同于 0 * * * *。
@every <duration>：每隔指定的 duration 执行一次，例如 @every 10s 表示每隔 10 秒执行。<duration> 会被 time.ParseDuration 解析，支持如 1h30m10s 这样的格式。

基本使用步骤

创建 Cron 实例：
```
c := cron.New()
```
如果需要秒级精度，可以使用 cron.WithSeconds() 选项：
```
c := cron.New(cron.WithSeconds())
```
此时 cron 表达式为 6 位（秒分时日月周）。
添加任务：
使用 AddFunc 方法添加任务，指定时间表达式和要执行的函数。
```
c.AddFunc("0 30 * * * *", func() { fmt.Println("每小时的第30分钟执行") 
})
```
也可以使用 AddJob 方法添加实现了 Job 接口（需实现 Run() 方法）的对象。
启动与停止：
```
c.Start() // 启动调度器
// ...
c.Stop()  // 停止调度器，注意已开始的任务会继续执行完毕
```
由于 c.Start() 会启动新的 goroutine 执行调度，主程序需要设法保持运行（例如使用 select {} 或 time.Sleep）。

时区设置

默认情况下，所有时间基于当前时区。你可以通过以下方式指定时区：

nyc, _ := time.LoadLocation("America/New_York")
c := cron.New(cron.WithLocation(nyc))

或者在时间字符串前添加 CRON_TZ 前缀。

高级选项

日志记录：可以集成自定义 Logger。

c := cron.New(cron.WithLogger(cron.PrintfLogger(log.New(os.Stdout, "CRON: ", log.LstdFlags)),),
)

任务恢复：使用 cron.WithChain 和 cron.Recover 可以在任务发生 panic 时恢复。

简单示例

下面是一个简单的示例，演示了如何使用 robfig/cron/v3 创建定时任务：

package mainimport ("fmt""log""os""time""github.com/robfig/cron/v3"
)func main() {c := cron.New(cron.WithLogger(cron.VerbosePrintfLogger(log.New(os.Stdout, "cron: ", log.LstdFlags)),),)// 添加一个每秒执行的任务c.AddFunc("@every 1s", func() {fmt.Println("每秒执行的任务", time.Now())})// 添加一个每分钟第30秒执行的任务c.AddFunc("30 * * * * *", func() {fmt.Println("每分钟第30秒执行的任务", time.Now())})c.Start()defer c.Stop()// 保持程序运行select {}
}