Documentation
¶
Overview ¶
Package cron 提供 Cron 表达式解析和调度功能。
支持标准 5 字段 Cron 表达式：分 时 日 月 周
⚠️ 与标准 cron 的方言差异（[#186]）：dow 支持 7≡Sunday；不支持 MON/JAN 名字、不支持 L/W/# 扩展；不可满足表达式（2 月 31 日）Next 返回零值 time.Time 而非报错——从系统 crontab 迁移时注意。
夏令时 ¶
Next 的返回值**保证严格晚于入参**（零值除外）。调度器最常见的消费形态
for { next := sched.Next(prev); time.Sleep(time.Until(next)); prev = next }
一旦 Next 返回不晚于入参的时刻就变成原地热转、任务被疯狂重复执行且永不 前进——所以这不是「精度」问题而是**活性**问题（[#214]）。内部推进全部走 绝对时间加法、不按墙钟重建，因此：
- **回拨**（同一墙钟出现两次）：两次出现都会各自被推进到，不会倒退；
- **前跳**（某个墙钟不存在，如 America/Santiago 2026-09-06 的 00:00）： 目标日/月的起点取该日**最早存在的时刻**；若表达式要求的墙钟时刻当天 确实不存在（如「仅在 9/6 00:00」），则该次不触发——与「按墙钟语义 该时刻当天不存在」一致，不会无限搜索。
Index ¶
- func NextSchedule(s Schedule, from time.Time, n int) []time.Time
- func RoundDuration(d time.Duration, precision time.Duration) time.Duration
- func SortEntries(entries []Entry)
- type ConstantDelaySchedule
- type DelaySchedule
- type Entry
- type RandomDelaySchedule
- type Schedule
- type SpecSchedule
- type WrapSchedule
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NextSchedule ¶
NextSchedule 返回最近的 N 个调度时间。
n <= 0 返回空切片（不做任何调度计算）——负数此前会传给 make([]time.Time, 0, n) 直接 panic（makeslice: cap out of range）。
func RoundDuration ¶
RoundDuration 将时间向上取整到指定间隔。
Types ¶
type ConstantDelaySchedule ¶
ConstantDelaySchedule 以固定时间间隔调度。
func Every ¶
func Every(duration time.Duration) ConstantDelaySchedule
Every 返回一个以固定间隔调度的 Schedule。
⚠️ 语义三件套（[#184](https://github.com/oekit/pkg/issues/184)，此前零声明）：
- duration < 1s **静默钳到 1s**（本调度器秒级粒度，ConstantDelaySchedule 沿用 robfig 形态）——配 Every(500ms) 期望半秒节奏会得到 1s，调度密度 减半无任何信号；
- 亚秒部分**截断**（1500ms ⇒ 1s）；
- Next 按传入时间的秒对齐，实际触发间隔 = delay 但不保证与「上次执行 完成」挂钩（固定时刻表，非完成后间隔；后者用 oekit/concurrency/loop 的 IntervalAfterCompletion）。
需要亚秒级高频节奏不该用 cron——直接 go-timer/loop。
type DelaySchedule ¶
DelaySchedule 在固定延迟后触发。
func NewDelaySchedule ¶
func NewDelaySchedule(delay time.Duration) DelaySchedule
NewDelaySchedule 创建一个延迟调度器。
type RandomDelaySchedule ¶
RandomDelaySchedule 在随机延迟后触发。
func NewRandomDelaySchedule ¶
func NewRandomDelaySchedule(min, max time.Duration) RandomDelaySchedule
NewRandomDelaySchedule 创建一个随机延迟调度器。
type SpecSchedule ¶
SpecSchedule 根据 cron 表达式调度任务。
func (*SpecSchedule) Next ¶
func (s *SpecSchedule) Next(t time.Time) time.Time
Next 返回下一个调度时间。
⚠️ 返回值**保证严格晚于入参**（除非返回零值 time.Time 表示放弃）。调度器的 标准消费形态是 `for { next := sched.Next(prev); time.Sleep(next.Sub(now)); prev = next }`， 一旦 Next 返回不晚于入参的时刻，该循环就变成**原地热转**且永不前进——任务在 一个窗口里被疯狂重复执行，进程忙等（[#214] 的失效形态）。内部各循环已全部 改成绝对时间推进（见各循环注释），这里再留一道兜底：真出现不前进时从入参 往后挪一秒重算，最多 3 次。
Source Files