go第三方库文档 定时任务cron

//go第三方库文档 定时任务cron
// https://pkg.go.dev/github.com/robfig/cron/v3

// 安装
// 要下载特定的标记版本，请运行：
go get github.com/robfig/cron/v3@v3.0.0
// 将其作为以下内容导入程序：
import "github.com/robfig/cron/v3"
// 由于使用Go模块，它需要Go 1.11或更高版本。

// 用法
// 调用方可以注册要在给定计划中调用的FUNC。Cron将在他们自己的goroutine中运行它们。
c := cron.New()
c.AddFunc("30 * * * *", func() { fmt.Println("Every hour on the half hour") })
c.AddFunc("30 3-6,20-23 * * *", func() { fmt.Println(".. in the range 3-6am, 8-11pm") })
c.AddFunc("CRON_TZ=Asia/Tokyo 30 04 * * *", func() { fmt.Println("Runs at 04:30 Tokyo time every day") })
c.AddFunc("@hourly",      func() { fmt.Println("Every hour, starting an hour from now") })
c.AddFunc("@every 1h30m", func() { fmt.Println("Every hour thirty, starting an hour thirty from now") })
c.Start()
..
//func在其自己的goroutine中异步调用。
...
//Funcs也可以添加到正在运行的Cron中
c.AddFunc("@daily", func() { fmt.Println("Every day") })
..
//检查cron作业条目的下一个和上一个运行时。
inspect(c.Entries())
 ..
c.Stop() //停止计划程序（不停止任何已运行的作业）。

// CRON表达式格式
// cron表达式表示一组时间，使用5个空格分隔的字段。
Field name   | Mandatory? | Allowed values  | Allowed special characters
----------   | ---------- | --------------  | --------------------------
Minutes      | Yes        | 0-59            | * / , -
Hours        | Yes        | 0-23            | * / , -
Day of month | Yes        | 1-31            | * / , - ?
Month        | Yes        | 1-12 or JAN-DEC | * / , -
Day of week  | Yes        | 0-6 or SUN-SAT  | * / , - ?
// 月和星期日字段值不区分大小写。“太阳”、“太阳”和“太阳”同样被接受。
// 该格式的具体解释基于Cron Wikipedia页面：https://en.wikipedia.org/wiki/Cron

// 其他格式
// 可选的Cron表达式格式支持其他字段，如秒。您可以通过如下创建自定义解析器来实现这一点。
cron.New(
	cron.WithParser(
		cron.NewParser(
			cron.SecondOptional | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor)))
// 由于添加秒数是对标准cron规范最常见的修改，因此cron提供了一个内置函数来实现这一点，这与您前面看到的自定义解析器相当，只是它的秒数字段是必需的：
cron.New(cron.WithSeconds())
// 它模拟最流行的替代Cron调度格式Quartz：http://www.quartz-scheduler.org/documentation/quartz-2.x/tutorials/crontrigger.html

// 特殊人物
// 星号（*）
// 星号表示cron表达式将匹配字段的所有值；e、 例如，在第5个字段（月）中使用星号表示每个月。
// 斜杠（/）
// 斜线用于描述范围的增量。例如，第1个字段（分钟）中的3-59/15表示一小时中的第3分钟，此后每隔15分钟。格式“*\/…”相当于格式“first-last/…”，即字段最大可能范围内的增量。形式“N/…”表示“N-MAX/…”，即从N开始，使用增量直到该特定范围结束。它不会缠绕。
// 逗号（，）
// 逗号用于分隔列表中的项目。例如，在第5个字段（星期几）中使用“MON，WED，FRI”表示周一、周三和周五。
// 连字符（-）
// 连字符用于定义范围。例如，9-17表示上午9点到下午5点（含）之间的每小时。
// 问号（）
// 可以使用问号代替“*”，将月日或周日留空。

// 预定时间表
// 您可以使用几个预定义计划中的一个来代替cron表达式。
Entry                  | Description                                | Equivalent To
-----                  | -----------                                | -------------
@yearly (or @annually) | Run once a year, midnight, Jan. 1st        | 0 0 1 1 *
@monthly               | Run once a month, midnight, first of month | 0 0 1 * *
@weekly                | Run once a week, midnight between Sat/Sun  | 0 0 * * 0
@daily (or @midnight)  | Run once a day, midnight                   | 0 0 * * *
@hourly                | Run once an hour, beginning of hour        | 0 * * * *

// 间隔
// 您还可以安排作业以固定的时间间隔执行，从添加作业或运行cron时开始。通过如下格式化cron规范来支持这一点：
@every <duration>
// 其中“duration”是time.ParseDuration接受的字符串(http://golang.org/pkg/time/#ParseDuration).
// 例如，“@每1h30m10s”表示在1小时、30分钟、10秒后激活的计划，然后在此后的每个间隔激活。
// 注意：间隔不考虑作业运行时。例如，如果作业运行需要3分钟，并且计划每5分钟运行一次，则每次运行之间只有2分钟的空闲时间。

// 时区
// 默认情况下，所有解释和调度都在机器的本地时区（time.local）中完成。可以在构造时指定不同的时区：
cron.New(
    cron.WithLocation(time.UTC))
// 通过在cron规范的开头提供一个额外的空格分隔字段（格式为“cron_TZ=Asia/Tokyo”），单个cron时间表也可以覆盖要在其中解释的时区。

// 例如：
// #早上6点准时运行。本地
cron.New().AddFunc("0 6 * * ?", ...)
// #在美国/纽约早上6点跑步
nyc, _ := time.LoadLocation("America/New_York")
c := cron.New(cron.WithLocation(nyc))
c.AddFunc("0 6 * * ?", ...)
// #在亚洲/东京早上6点运行
cron.New().AddFunc("CRON_TZ=Asia/Tokyo 0 6 * * ?", ...)
// #在亚洲/东京早上6点运行
c := cron.New(cron.WithLocation(nyc))
c.SetLocation("America/New_York")
c.AddFunc("CRON_TZ=Asia/Tokyo 0 6 * * ?", ...)

// 还支持前缀“TZ=（时区）”以实现旧式兼容性。
// 请注意，在夏时制超前跃迁过渡期间安排的作业将不会运行！

// 工作包装
// Cron运行程序可以配置一系列作业包装器，以向所有提交的作业添加横切功能。例如，它们可用于实现以下效果：
// -从作业中恢复任何恐慌（默认激活）
// -如果上一次运行尚未完成，则延迟作业的执行
// -如果上一次运行尚未完成，则跳过作业的执行
// -记录每个作业的调用

// 使用“cron.WithChain”选项为添加到cron的所有作业安装包装器：
cron.New(cron.WithChain(
	cron.SkipIfStillRunning(logger),
))

// 通过显式包装为单个作业安装包装：
job = cron.NewChain(
	cron.SkipIfStillRunning(logger),
).Then(job)

// 线程安全
// 由于Cron服务与调用代码同时运行，因此必须注意确保正确的同步。
// 所有cron方法都设计为正确同步，只要调用方确保调用在它们之间排序之前有一个明确的顺序。

// 登录中
// Cron定义了一个记录器接口，该接口是github.com/go-logr/logr中定义的接口的子集。它有两个日志级别（Info和Error），参数是键/值对。这使得cron日志可以插入结构化日志系统。提供了一个适配器，[Verbose]PrintfLogger来包装标准库*log.Logger。
// 为了进一步了解Cron操作，可以激活详细日志记录，它将记录作业运行、调度决策以及添加或删除的作业。使用一次性记录器激活它，如下所示：

cron.New(
	cron.WithLogger(
		cron.VerbosePrintfLogger(log.New(os.Stdout, "cron: ", log.LstdFlags))))

// 实施
// Cron条目存储在一个数组中，按其下一次激活时间排序。Cron将一直休眠，直到下一个作业即将运行。
// 醒来时：
// -它运行在该秒上处于活动状态的每个条目
// -它计算已运行作业的下一次运行时间
// -它会在下次激活时对条目数组进行重新排序。
// -它会一直睡到最快的工作。

// 指数
type Chain
func NewChain(c ...JobWrapper) Chain
func (c Chain) Then(j Job) Job
type ConstantDelaySchedule
func Every(duration time.Duration) ConstantDelaySchedule
func (schedule ConstantDelaySchedule) Next(t time.Time) time.Time
type Cron
func New(opts ...Option) *Cron
func (c *Cron) AddFunc(spec string, cmd func()) (EntryID, error)
func (c *Cron) AddJob(spec string, cmd Job) (EntryID, error)
func (c *Cron) Entries() []Entry
func (c *Cron) Entry(id EntryID) Entry
func (c *Cron) Location() *time.Location
func (c *Cron) Remove(id EntryID)
func (c *Cron) Run()
func (c *Cron) Schedule(schedule Schedule, cmd Job) EntryID
func (c *Cron) Start()
func (c *Cron) Stop() context.Context
type Entry
func (e Entry) Valid() bool
type EntryID
type FuncJob
func (f FuncJob) Run()
type Job
type JobWrapper
func DelayIfStillRunning(logger Logger) JobWrapper
func Recover(logger Logger) JobWrapper
func SkipIfStillRunning(logger Logger) JobWrapper
type Logger
func PrintfLogger(l interface{ ... }) Logger
func VerbosePrintfLogger(l interface{ ... }) Logger
type Option
func WithChain(wrappers ...JobWrapper) Option
func WithLocation(loc *time.Location) Option
func WithLogger(logger Logger) Option
func WithParser(p ScheduleParser) Option
func WithSeconds() Option
type ParseOption
type Parser
func NewParser(options ParseOption) Parser
func (p Parser) Parse(spec string) (Schedule, error)
type Schedule
func ParseStandard(standardSpec string) (Schedule, error)

type ScheduleParser
type SpecSchedule
func (s *SpecSchedule) Next(t time.Time) time.Time

// 类型
type Chain 
type Chain struct {
    //包含已过滤或未报告的字段
}
// Chain是一系列作业包装器，它用日志记录或同步等横切行为装饰提交的作业。

func NewChain 
func NewChain(c ...JobWrapper) Chain
// NewChain返回由给定的JobWrapper组成的链。

func (Chain) Then 
func (c Chain) Then(j Job) Job
// 然后使用链中的所有作业包装器装饰给定作业。

// 这：
NewChain(m1, m2, m3).Then(job)

// 相当于：
m1(m2(m3(job)))

type ConstantDelaySchedule 
type ConstantDelaySchedule struct {
    Delay time.Duration
}
// ConstantDelaySchedule表示一个简单的循环占空比，例如“每5分钟”。它支持的工作频率不超过每秒一次。

func Every 
func Every(duration time.Duration) ConstantDelaySchedule
// 每个返回一个crontab计划，该计划在每个持续时间内激活一次。不支持小于1秒的延迟（将四舍五入到1秒）。任何小于1秒的字段都将被截断。

func (ConstantDelaySchedule) Next 
func (schedule ConstantDelaySchedule) Next(t time.Time) time.Time
// Next返回下一次应运行此操作的时间。这将循环，以便下一次激活时间将在第二次。

type Cron 
type Cron struct {
    //包含已过滤或未报告的字段
}
// Cron跟踪任意数量的条目，根据调度指定调用关联的func。它可以启动、停止，并且可以在运行时检查条目。

func New 
func New(opts ...Option) *Cron
// New返回一个新的Cron作业运行器，由给定的选项修改。

// 可用设置
Time Zone
  Description: The time zone in which schedules are interpreted
  Default:     time.Local
Parser
  Description: Parser converts cron spec strings into cron.Schedules.
  Default:     Accepts this spec: https://en.wikipedia.org/wiki/Cron
Chain
  Description: Wrap submitted jobs to customize behavior.
  Default:     A chain that recovers panics and logs them to stderr.

func (*Cron) AddFunc 
func (c *Cron) AddFunc(spec string, cmd func()) (EntryID, error)
// AddFunc将func添加到Cron中，以便按照给定的计划运行。使用此Cron实例的时区作为默认值来解析规范。返回一个不透明的ID，可用于以后删除它。

func (*Cron) AddJob 
func (c *Cron) AddJob(spec string, cmd Job) (EntryID, error)
// AddJob将作业添加到Cron中，以便按照给定的计划运行。使用此Cron实例的时区作为默认值来解析规范。返回一个不透明的ID，可用于以后删除它。

func (*Cron) Entries 
func (c *Cron) Entries() []Entry
// 条目返回cron条目的快照。

func (*Cron) Entry 
func (c *Cron) Entry(id EntryID) Entry
// 条目返回给定条目的快照，如果找不到，则返回nil。

func (*Cron) Location 
func (c *Cron) Location() *time.Location
// Location获取时区位置

func (*Cron) Remove 
func (c *Cron) Remove(id EntryID)
// 删除将来正在运行的条目。

func (*Cron) Run 
func (c *Cron) Run()
// 运行cron调度程序，如果已经运行，则不运行op。

func (*Cron) Schedule 
func (c *Cron) Schedule(schedule Schedule, cmd Job) EntryID
// Schedule向Cron添加一个作业，以便按照给定的计划运行。作业将使用配置的链进行包装。

func (*Cron) Start 
func (c *Cron) Start()
// 在其自己的goroutine中启动cron调度程序，如果已经启动，则不启动op。

func (*Cron) Stop 
func (c *Cron) Stop() context.Context
// 停止cron调度程序（如果正在运行）；否则它什么也不做。返回一个上下文，以便调用方可以等待正在运行的作业完成。

type Entry 
type Entry struct {
    //ID是此项的cron分配的ID，可用于查找
    //快照或删除它。
    ID EntryID
    //应在其上运行此作业的计划。
    Schedule Schedule
    //下一次作业将运行，或者如果未运行Cron，则为零时间
    //已启动或此条目的计划不可满足
    Next time.Time
    //Prev是上次运行此作业的时间，如果从未运行过，则为零时间。
    Prev time.Time
    //WrappedJob是在计划被激活时运行的东西。
    WrappedJob Job
    //作业是提交给cron的东西。
    //它被保留下来，以便以后需要在作业中获取的用户代码，
    //例如，via Entries（）可以这样做。
    Job Job
}
// 条目由一个计划和在该计划上执行的func组成。

func (Entry) Valid 
func (e Entry) Valid() bool
// 如果这不是零条目，Valid返回true。

type EntryID 
type EntryID int
// EntryID标识Cron实例中的条目

type FuncJob 
type FuncJob func()
// FuncJob是将func（）转换为cron.Job的包装器

func (FuncJob) Run 
func (f FuncJob) Run()
type Job 
type Job interface {
    Run()
}
// 作业是提交的cron作业的接口。

type JobWrapper 
type JobWrapper func(Job) Job
// JobWrapper用一些行为装饰给定的作业。

func DelayIfStillRunning 
func DelayIfStillRunning(logger Logger) JobWrapper
// DelayIfStillRunning序列化作业，将后续运行延迟到上一次运行完成。延迟超过一分钟后运行的作业将延迟记录在Info中。

func Recover 
func Recover(logger Logger) JobWrapper
// 恢复包装作业中的恐慌，并使用提供的记录器记录它们。

func SkipIfStillRunning 
func SkipIfStillRunning(logger Logger) JobWrapper
// 如果前一个调用仍在运行，SkipIfStillRunning将跳过对作业的调用。它在信息级别记录跳转到给定记录器。

type Logger 
type Logger interface {
    //Info记录有关cron操作的例行消息。
    Info(msg string, keysAndValues ...interface{})
    //错误记录错误条件。
    Error(err error, msg string, keysAndValues ...interface{})
}
// Logger是此包中用于日志记录的接口，因此可以插入任何后端。它是github.com/go-logr/logr接口的子集。

// var DefaultLogger Logger=PrintfLogger（log.New（os.Stdout，“cron:”，log.LstdFlags））
// 如果未指定，则Cron将使用DefaultLogger。

// var DiscardLogger Logger=PrintfLogger（log.New（ioutil.Discard，“，0））
// 调用方可以使用DiscardLogger放弃所有日志消息。

func PrintfLogger 
func PrintfLogger(l interface{ Printf(string, ...interface{}) }) Logger
// PrintfLogger将基于Printf的记录器（如标准库“log”）封装到记录器接口的实现中，该接口只记录错误。

func VerbosePrintfLogger 
func VerbosePrintfLogger(l interface{ Printf(string, ...interface{}) }) Logger
// VerbosePrintfLogger将基于Printf的记录器（如标准库“log”）封装到记录器接口的实现中，该接口记录所有内容。

type Option 
type Option func(*Cron)
// 选项表示对Cron的默认行为的修改。

func WithChain 
func WithChain(wrappers ...JobWrapper) Option
// WithChain指定要应用于添加到此cron的所有作业的作业包装器。有关提供的包装器，请参阅此包中的Chain*函数。

func WithLocation 
func WithLocation(loc *time.Location) Option
// WithLocation覆盖cron实例的时区。

func WithLogger 
func WithLogger(logger Logger) Option
// WithLogger使用提供的记录器。

func WithParser 
func WithParser(p ScheduleParser) Option
// WithParser重写用于解释作业计划的解析器。

func WithSeconds 
func WithSeconds() Option
// WithSeconds重写用于解释作业计划的解析器，以包含秒字段作为第一个字段。

type ParseOption 
type ParseOption int
// 用于创建解析器的配置选项。大多数选项指定应包括哪些字段，而其他选项则启用功能。如果未包含字段，则解析器将采用默认值。这些选项不会更改字段解析的顺序。

const (
	Second         ParseOption = 1 << iota // //Seconds字段，默认值为0
	SecondOptional                         // 秒可选//可选秒字段，默认值为0
	Minute                                 // 分钟//分钟字段，默认值为0
	Hour                                   // 小时//小时字段，默认值为0
	Dom                                    // Day of month字段，默认值*
	Month                                  // 月字段，默认值*
	Dow                                    // 星期几字段，默认值*
	DowOptional                            // Optional day of week字段，默认值*
	Descriptor                             // 允许使用诸如@monthly、@weekly等描述符。
)

type Parser 
type Parser struct {
    //包含已过滤或未报告的字段
}
// 可以配置的自定义解析器。

func NewParser 
func NewParser(options ParseOption) Parser
// NewParser使用自定义选项创建解析器。

// 如果给出了多个可选项，它会感到恐慌，因为通常无法正确推断提供了或缺少哪个可选项。

// 例子
// //无描述符的标准解析器
specParser := NewParser(Minute | Hour | Dom | Month | Dow)
sched, err := specParser.Parse("0 0 15 */3 *")
// //同上，仅排除时间字段
subsParser := NewParser(Dom | Month | Dow)
sched, err := specParser.Parse("15 */3 *")
// //如上所述，只是使道指可选
subsParser := NewParser(Dom | Month | DowOptional)
sched, err := specParser.Parse("15 */3")

func (Parser) Parse 
func (p Parser) Parse(spec string) (Schedule, error)
// Parse返回表示给定规范的新crontab计划。如果规范无效，则返回描述性错误。它接受NewParser配置的crontab规范和特性。

type Schedule 
type Schedule interface {
    //Next返回下一个激活时间，晚于给定时间。
    //Next最初调用，然后每次运行作业时调用。
    Next(time.Time) time.Time
}
// 明细表描述作业的工作周期。

func ParseStandard 
func ParseStandard(standardSpec string) (Schedule, error)
// ParseStandard返回表示给定standardSpec的新crontab计划(https://en.wikipedia.org/wiki/Cron). 它需要5个条目，依次表示：分钟、小时、月日、月日和星期日。如果规范无效，则返回描述性错误。

// 它接受
- Standard crontab specs, e.g. "* * * * ?"
- Descriptors, e.g. "@midnight", "@every 1h30m"

type ScheduleParser 
type ScheduleParser interface {
    Parse(spec string) (Schedule, error)
}
// ScheduleParser是用于返回计划的计划规范解析器的接口

type SpecSchedule 
type SpecSchedule struct {
    Second, Minute, Hour, Dom, Month, Dow uint64
    //替代此明细表的位置。
    Location *time.Location
}
// SpecSchedule基于传统的crontab规范指定占空比（第二粒度）。它最初计算并存储为位集。

func (*SpecSchedule) Next 
func (s *SpecSchedule) Next(t time.Time) time.Time
// Next返回下一次激活此计划的时间，大于给定时间。如果找不到满足计划的时间，则返回零时间。