timertask

timertask

分片定时任务——秒级延时/跨实例 Redis 后端 + cron 周期调度

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/timertask@v0.2.4
# 需要 Redis 形态（嵌套模块，按需引入）：
go get github.com/oekit/timertask/redis@v0.2.0

这个仓库做什么

timertask 是分片定时任务：按任务 ID 哈希分片、支持秒级精度的延时任务、 心跳续约防重复执行。三块能力：

• 本地后端（根包 LocalBackend）：进程内延迟任务队列，零 Redis 依赖
• cron 周期调度（子包 timertask/local）：按 cron 表达式触发任务，表达式解析复用 pkg/timex/cron；假时钟驱动，触发点序列可确定性断言
• Redis 后端（嵌套模块 timertask/redis）：跨实例分片 + 可靠投递（租约 + Ack + 可见性超时）

v0.2.0 起 Redis 后端自根包迁至嵌套模块——根模块依赖面只剩 github.com/oekit/pkg， import timertask 与 import timertask/local 的模块依赖面均不含 redis（纯 stdlib 嵌入式场景可用）。

快速使用

import "github.com/oekit/timertask"

var handler timertask.Handler = func(ctx context.Context, t *timertask.Task) error {
    return dispatch(t.Action, t.Param) // Action/Param 由业务自定义
}

backend := timertask.NewLocalBackend(handler)
_ = backend.Start(ctx)
_ = backend.Send(ctx, &timertask.Task{
    ID: "t1", EndTime: time.Now().Add(time.Minute).Unix(),
    Action: "remind", Param: `{"uid":42}`,
})

cron 周期调度（timertask/local）：

import "github.com/oekit/timertask/local"

sched, _ := local.New(local.Config{Concurrency: 1}) // 缺省严格串行
_ = sched.Schedule("0 3 * * *", func(ctx context.Context, at time.Time) error {
    return runNightly(ctx, at) // 按龄回收 / 事实合并 / 周期摘要
})
_ = sched.Start(ctx)

从 v0.1.x 迁移到 v0.2.0（Redis 后端迁嵌套模块）

github.com/oekit/timertask/redis 是独立的 Go module（有自己的 go.mod 与 tag redis/v0.2.0），不是根包下的子目录——所以迁移要改两处：

go get github.com/oekit/timertask/redis@v0.2.0   # ① go.mod 新增 require（必需）

// ② import 路径
import "github.com/oekit/timertask/redis"

backend := redis.New(redis.RedisConfig{...})   // API 不变

只改 import 路径而漏掉 ①，会构建失败（no required module provides package github.com/oekit/timertask/redis）。

只用本地形态（LocalBackend）的消费方无需任何改动——根包保留 Task/Handler/全部 With* 选项与 LocalBackend，且根模块已剥离 go-redis/logx/concurrency（import timertask 的模块依赖面只有 github.com/oekit/pkg）。

边界

• 跨实例去重需要 Redis → 嵌套模块 github.com/oekit/timertask/redis（独立 module，需单独 require）； cron 表达式解析在 pkg/timex/cron（local 子包直接复用，不另写一份）

矩阵总览（24 活跃模块，自动生成）

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE