@go/timer

Maintainer Statement: 本项目完全由 AI 维护。任何改动均遵循代码质量与性能的最佳实践。

🎯 设计哲学

@go/timer 是一个高性能的时间流管控引擎，专为构建健壮的微服务基础设施而设计。它不仅仅是计时器，更是一套处理并发、超时和重试的工具集。

📦 安装

go get apigo.cc/go/timer

💡 核心功能

1. 耗时打点追踪 (Tracker)

用于精准测量复杂业务流程中各环节的耗时。

tk := timer.Start()
// ... 业务步骤 1
tk.Record("step1")
// ... 业务步骤 2
tk.Record("step2")

fmt.Println(tk.Describe()) // [step1] 10ms; [step2] 20ms; Total: 30ms

2. 指数退避重试 (Retry)

提供优雅的重试管控，防止由于短时波动导致的系统雪崩。

err := timer.Retry(func() error {
    return fetchRemoteData()
}, timer.WithMaxRetries(3), timer.WithBackoff(100*time.Millisecond, 2.0))

3. 高性能时间轮 (Time Wheel)

在大规模定时任务场景下，相比原生 time.Timer 具有极低的 CPU 和内存开销。

tw := timer.NewTimeWheel(10*time.Millisecond, 100)
tw.Start()

tw.AfterFunc(5*time.Second, func() {
    // 异步执行
})

4. 防抖与节流 (Debouncer & Throttler)

控制高频事件的触发频率。

// 防抖：静止 1s 后执行
d := timer.NewDebouncer(1*time.Second, flush)
d.Trigger()

// 节流：每 2s 最多执行一次
t := timer.NewThrottler(2*time.Second, alert)
t.Trigger()

5. 上下文超时监控 (Timeout Executor)

结合打点追踪的超时执行器。

res, err := timer.RunTimeout(3*time.Second, func(tk *timer.Tracker) (any, error) {
    tk.Record("init")
    // ...
    return data, nil
})

🧪 验证状态

测试全部通过，性能达标。

详见：TEST.md