warning

定时任务采用了类 Linux Crontab 的表达格式，使得开发者能够快速理解掌握定时任务表达式技巧。但需要注意的是，由于定时任务模块是基于代码层面的控制，因此控制的粒度会更细，最小粒度到 秒，格式被划分为了 6 段。而 Linux Crontab 是基于程序层面的控制，最小粒度到 分，格式被划分为了 5 段。

基本介绍

cron表达式 表示一组时间，使用 6 个空格分隔的字段。

Seconds Minutes Hours Day Month Week

即 秒 分 时  日 月 周

每个字段的含义如下：

Field name    | Allowed values  | Allowed special characters
----------    | --------------  | --------------------------
Seconds       | 0-59            | * / , - #
Minutes       | 0-59            | * / , -
Hours         | 0-23            | * / , -
Day           | 1-31            | * / , - ?
Month         | 1-12 or JAN-DEC | * / , -
Week          | 0-6 or SUN-SAT  | * / , - ?

warning

月份和星期字段值英文不区分大小写。 例如传递 SUN、 Sun 和 sun 同样被接受。

特殊字符

星号（ *）

星号表示 cron 表达式将匹配所有的值。例如，在第五个字段( Month)中使用星号表示每个月。

斜线（ /）

斜杠用于描述范围的增量。例如：第二个字段使用 3-59/15 表示每小时的第 3 分钟开始到第 59 分钟，每隔 15 分钟执行。

逗号（ ,）

逗号用于分隔列表的项目。例如，第五个字段使用 MON,WED,FRI 将指每周一，周三和周五执行。

连字符（ -）

连字符用于定义范围。例如，第三个字段使用 9-17 表示每天上午 9 点至下午 5 点（含）。

忽略号（ \#）

忽略号表示 cron 表达式将忽略这个字段的使用，目前仅秒字段支持该符号，用于将 6 段 cron pattern 无缝转换为 5 段 linux crontab pattern。

问号（ ?）

可以使用 问号 而不是 * 来让 Day 或 Week 字段为空。

预定义格式

您可以使用几个预定义的时间来代替 cron 表达式。

Entry                  | Description                                | Equivalent To
-----                  | -----------                                | -------------
@yearly (or @annually) | Run once a year, midnight, Jan. 1st        | 0 0 0 1 1 *
@monthly               | Run once a month, midnight, first of month | 0 0 0 1 * *
@weekly                | Run once a week, midnight between Sat/Sun  | 0 0 0 * * 0
@daily (or @midnight)  | Run once a day, midnight                   | 0 0 0 * * *
@hourly                | Run once an hour, beginning of hour        | 0 0 * * * *

间隔

您还可以定义任务以固定的时间间隔执行，从添加时开始运行。这可以通过格式化 cron 规范来支持，如下所示：

@every <duration>

其中 duration 是 time.ParseDuration 接受的字符串 （ http://golang.org/pkg/time/#ParseDuration）。

例如， @every 1h30m10s 将表示添加任务之后每隔 1小时30分10秒 执行。

warning

间隔不会考虑任务的执行开销时间。例如，如果一项工作需要 3 分钟才能执行完成，并且计划每隔 5 分钟运行一次，那么每次任务之间只有 2 分钟的空闲时间。

表达式示例

表达式示例	表达式说明
* * * * * *	每秒执行
# * * * * *	每分钟执行，每一次执行至少间隔 60 秒
2 * * * * *	每分钟的第 2 秒执行
*/5 * * * * *	每 5 秒执行一次
# */30 * * * *	每 30 分钟执行一次
# 0 2 * * *	每天凌晨 2 点执行
# */30 9-18 * * *	每天 9 点到 18 点，每隔 30 分钟执行一次
# 0 9 * * MON,FRI	每 周一 和 周五 在 9 点执行一次

注意事项🔥

所有开发语言级别 6 段式的 cron pattern 设计从实践上来说，由于底层定时器的不准确性，因此都是有一定的设计缺陷。由于 cron pattern 精确到秒级，当延 迟达到了秒级，那么任务可能会存在丢失情况。而当 golang 引擎调度比较慢的时候，那么延迟很容易达到秒级引发程序逻辑问题。

考虑大部分的场景其实并不需要如此精准的定时任务粒度控制，因此从框架 v2.7 版本开始，我们对秒字段提供了忽略符号 #，用于将 6 段式的 cron pattern 转换为 5 段式的 linux crontab pattern，更加稳健。如果是秒级粒度的定时任务场景，请考虑使用 gtimer 定时器，但同时也需要注意，任何的定时器都是不准确的，不能完全依赖底层的系统时间。