Documentation
¶
Overview ¶
Package cooldown 提供按 key 的冷却(CD)原语:某个动作触发后,要等到冷却结束 才能再次触发。纯内存、并发安全。
与相邻限流原语的区别:
- ratelimit 控"速率"(每秒 N 次,令牌桶);
- counter 控"窗口内累计次数"(每分钟 ≤ N);
- cooldown 控"两次动作的最小间隔 / 下次可用时刻",per-(key) 维度。 典型:技能 CD(放完技能 8s 后才能再放)、每日签到(领了要到次日)、 发言间隔(发一条后 3s 才能再发)、按钮防连点 / 二次确认窗口。
核心是"下次可用时刻"的时间戳:Trigger 记录 now+cd;Ready 判断 now 是否已过; Remaining 返回还剩多久。TryTrigger 是"检查 + 触发"的原子组合(未在 CD 中则 触发并返回 true,否则返回 false),避免检查与触发之间的竞态。
支持默认 CD(New 时设定)与 per-call CD(TriggerFor,不同动作不同冷却)。 分片锁降低争用;空闲 key 由后台 gc 回收。零值不可用,用 New 构造;Stop 后 gc 退出。
生产多实例:默认内存实现的冷却不跨实例(各台各算各的,换实例可绕过 CD)。用 WithStore 接入 kvstore.Store(如 Redis)后,冷却跨实例一致——"冷却中"用一个 TTL 键表示(键在=冷却中,TTL=剩余时间),TryTrigger 用 SetNX 原子抢占。
Index ¶
- type Cooldown
- func (c *Cooldown) Ready(key string) bool
- func (c *Cooldown) Remaining(key string) time.Duration
- func (c *Cooldown) Reset(key string)
- func (c *Cooldown) Stop()
- func (c *Cooldown) Trigger(key string)
- func (c *Cooldown) TriggerFor(key string, cd time.Duration)
- func (c *Cooldown) TryTrigger(key string) bool
- func (c *Cooldown) TryTriggerFor(key string, cd time.Duration) bool
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cooldown ¶
type Cooldown struct {
// contains filtered or unexported fields
}
Cooldown 按 key 的冷却管理器。零值不可用,用 New 构造。并发安全。
func (*Cooldown) TriggerFor ¶
TriggerFor 用指定 cd 触发冷却(不同动作不同冷却时用)。cd<=0 视为立即就绪。
func (*Cooldown) TryTrigger ¶
TryTrigger 原子地"检查 + 触发":若 key 已就绪,则触发默认 CD 并返回 true; 否则不改动、返回 false。用于"能放技能就放并进 CD"这类竞态敏感场景。
type Option ¶
type Option func(*config)
Option 配置 Cooldown。
func WithGCInterval ¶
WithGCInterval 设置空闲 key 清扫间隔(默认 1 分钟)。
func WithOnStoreError ¶
WithOnStoreError 设置 store 出错回调(网络故障等)。默认静默;出错时 Ready 返回 true、TryTrigger 放行(fail-open),由此回调上报供监控。
Source Files