# @go/timer

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

## 🎯 设计哲学

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

## 📦 安装

```bash
go get apigo.cc/go/timer
```

## 💡 核心功能

### 1. 耗时打点追踪 (Tracker)
用于精准测量复杂业务流程中各环节的耗时。

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

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

### 2. 指数退避重试 (Retry)
提供优雅的重试管控，防止由于短时波动导致的系统雪崩。

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

### 3. 高性能时间轮 (Time Wheel)
在大规模定时任务场景下，相比原生 `time.Timer` 具有极低的 CPU 和内存开销。

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

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

### 4. 防抖与节流 (Debouncer & Throttler)
控制高频事件的触发频率。

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

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

### 5. 上下文超时监控 (Timeout Executor)
结合打点追踪的超时执行器。

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

## 🧪 验证状态
测试全部通过，性能达标。

详见：[TEST.md](./TEST.md)