79 lines
1.8 KiB
Markdown
79 lines
1.8 KiB
Markdown
# @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)
|