Golang高效Cron表达式解析与任务调度插件gronx的使用

gronx 是一个Golang的cron表达式解析器，具有任务运行器和守护进程功能，支持类似crontab的任务列表文件。它可以从任何时间点找到表达式下一次(NextTick())或上一次(PrevTick())的运行时间。

主要特性

• 零依赖
• 非常快速，因为它在段不匹配时会提前退出
• 内置类似crontab的守护进程
• 支持秒级时间粒度

安装

go get -u github.com/adhocore/gronx

基本用法

import (
	"time"

	"github.com/adhocore/gronx"
)

gron := gronx.New()
expr := "* * * * *"

// 检查表达式是否有效，返回bool
gron.IsValid(expr) // true

// 检查表达式是否在当前时间到期，返回bool和error
gron.IsDue(expr) // true|false, nil

// 检查表达式在给定时间是否到期
gron.IsDue(expr, time.Date(2021, time.April, 1, 1, 1, 0, 0, time.UTC)) // true|false, nil

也可以不实例化直接检查有效性：

import "github.com/adhocore/gronx"

gronx.IsValid("* * * * *") // true

批量到期检查

如果有多个cron表达式需要在同一参考时间检查是否到期，可以使用BatchDue()：

gron := gronx.New()
exprs := []string{"* * * * *", "0 */5 * * * *"}

// 返回[]gronx.Expr{}数组，每个项目都有Due标志和遇到的Err
dues := gron.BatchDue(exprs)

for _, expr := range dues {
    if expr.Err != nil {
        // 处理错误
    } else if expr.Due {
        // 处理到期任务
    }
}

// 或者使用给定时间
ref := time.Now()
gron.BatchDue(exprs, ref)

下一次运行时间

找出cron表达式下一次运行时间(在不久的将来)：

allowCurrent = true // 包括当前时间
nextTime, err := gronx.NextTick(expr, allowCurrent) // 返回time.Time, error

// 或者在某个参考时间后的下一次运行
refTime = time.Date(2022, time.November, 1, 1, 1, 0, 0, time.UTC)
allowCurrent = false // 排除参考时间
nextTime, err := gronx.NextTickAfter(expr, refTime, allowCurrent) // 返回time.Time, error

上一次运行时间

找出cron表达式上一次运行时间(在不久的过去)：

allowCurrent = true // 包括当前时间
prevTime, err := gronx.PrevTick(expr, allowCurrent) // 返回time.Time, error

// 或者在某个参考时间前的上一次运行
refTime = time.Date(2022, time.November, 1, 1, 1, 0, 0, time.UTC)
allowCurrent = false // 排除参考时间
nextTime, err := gronx.PrevTickBefore(expr, refTime, allowCurrent) // 返回time.Time, error

Go Tasker

Tasker是一个可以在Golang应用程序中以编程方式使用的任务管理器。它作为守护进程运行，并调用使用cron表达式调度的任务：

package main

import (
	"context"
	"time"

	"github.com/adhocore/gronx/pkg/tasker"
)

func main() {
	taskr := tasker.New(tasker.Option{
		Verbose: true,
		// 可选：默认为本地时区
		Tz:      "Asia/Bangkok",
		// 可选：默认为stderr日志流
		Out:     "/full/path/to/output-file",
	})

	// 添加每分钟运行的任务
	taskr.Task("* * * * *", func(ctx context.Context) (int, error) {
		// 做一些事情...

		// 然后返回退出码和错误，例如：如果一切正常
		return 0, nil
	}).Task("*/5 * * * *", func(ctx context.Context) (int, error) { // 每5分钟
		// 你也可以将输出记录到上面Option中配置的Out文件：
		taskr.Log.Printf("done something in %d s", 2)

		return 0, nil
	})

	// 运行任务不重叠，将concurrent标志设置为false：
	concurrent := false
	taskr.Task("* * * * * *", tasker.Taskify("sleep 2", tasker.Option{}), concurrent)

	// 每10分钟执行任意命令
	taskr.Task("@10minutes", taskr.Taskify("command --option val -- args", tasker.Option{Shell: "/bin/sh -c"}))

	// ... 添加更多任务

	// 可选地，如果你想让tasker在2小时后停止，使用Until()传递持续时间：
	taskr.Until(2 * time.Hour)

	// 最后运行tasker，它每分钟精确地触发并运行该时间到期的所有任务！
	// 当收到ctrl+c时，它会优雅地退出，确保待处理的任务完成。
	taskr.Run()
}

并发性

默认情况下，任务可以并发运行，即如果上一次运行尚未完成但现在又到期了，它将再次运行。如果你想一次只运行一个任务实例，将concurrent标志设置为false：

taskr := tasker.New(tasker.Option{})

concurrent := false
expr, task := "* * * * * *", tasker.Taskify("php -r 'sleep(2);'")
taskr.Task(expr, task, concurrent)

任务守护进程

它也可以作为独立的任务守护进程使用，而不是在Golang应用程序中以编程方式使用。

首先，安装tasker命令：

go install github.com/adhocore/gronx/cmd/tasker@latest

然后准备一个crontab格式的taskfile，最后像这样运行任务守护进程：

tasker -file path/to/taskfile

Tasker命令选项：

-file string <required>
    The task file in crontab format
-out string
    The fullpath to file where output from tasks are sent to
-shell string
    The shell to use for running tasks (default "/usr/bin/bash")
-tz string
    The timezone to use for tasks (default "Local")
-until int
    The timeout for task daemon in minutes
-verbose
    The verbose mode outputs as much as possible

示例：

tasker -verbose -file path/to/taskfile -until 120 # 运行直到120分钟后(即2小时)，所有反馈回显
tasker -verbose -file path/to/taskfile -out path/to/output # 所有反馈回显到输出文件
tasker -tz America/New_York -file path/to/taskfile -shell zsh # 使用zsh shell基于纽约时区运行所有任务

Cron表达式

完整的cron表达式由7个部分组成：

<second> <minute> <hour> <day> <month> <weekday> <year>

然而，通常5部分就足够了，5部分表达式解释为：

<minute> <hour> <day> <month> <weekday>

在这种情况下，会在<second>位置前置一个默认值0。

在6部分表达式中，如果第6部分匹配<year>(即至少4位数字)，它将被解释为：

<minute> <hour> <day> <month> <weekday> <year>

并且会在<second>位置前置一个默认值0。

对于每个部分，你可以有多个选择，用逗号分隔：

例如：0 0,30 * * * *表示第0或第30分钟

要指定值范围，可以使用破折号：

例如：0 10-15 * * * *表示第10、11、12、13、14和15分钟

要指定步长范围，可以结合破折号和斜杠：

例如：0 10-15/2 * * * *表示10到15分钟之间每2分钟一次，即第10、12和14分钟

对于<day>和<weekday>部分，还有额外的修饰符(可选)。

如果你想，你可以在一个表达式中混合多个选择、范围和步长：

0 5,12-20/4,55 * * * *匹配分钟为5或12-20/4或55中的任意一个

真实缩写

你可以使用真实的缩写(3个字符)表示月份和星期几。例如：JAN、dec、fri、SUN

标签

以下标签可用，它们在解析前会转换为真实的cron表达式：

• @yearly 或 @annually - 每年
• @monthly - 每月
• @daily - 每天
• @weekly - 每周
• @hourly - 每小时
• @5minutes - 每5分钟
• @10minutes - 每10分钟
• @15minutes - 每15分钟
• @30minutes - 每30分钟
• @always - 每分钟
• @everysecond - 每秒

为了向后兼容，@always目前仍表示每分钟，在未来的版本中它可能表示每秒

// 像这样使用标签：
gron.IsDue("@hourly")
gron.IsDue("@5minutes")

修饰符

支持以下修饰符

• 月份中的某天 / 5部分中的第3部分 / 6+部分中的第4部分:

  • L 表示月份的最后一天(例如：L在闰年二月可能表示29日)
  • W 表示最近的工作日(例如：10W是最接近10日的工作日(MON-FRI))

• 星期几 / 5部分中的第5部分 / 6+部分中的第6部分:

  • L 表示月份的最后一周几(例如：2L是最后一个星期二)
  • # 表示月份中的第n个星期几(例如：1#2是第二个星期一)

许可证

© MIT | 2021-2099, Jitendra Adhikari