golang.org/x/time/rate的Limiter足够用，因其基于令牌桶算法、线程安全、无后台goroutine、纳秒级性能，且经生产验证；自行实现易引发并发竞争、时钟漂移等问题。
为什么直接用 golang.org/x/time/rate 的 Limiter 就够用了
Go 标准库不带限流器，但官方维护的 x/time/rate 包已足够健壮、线程安全，且基于令牌桶（token bucket）模型，能应对突发流量 + 平滑限流。别自己手写计数器或时间窗口——容易漏掉并发竞争、时钟漂移、重置逻辑等问题。
常见错误是把 Limiter 当成“每秒只允许 N 次调用”的开关，其实它更像一个带容量的水桶：每次 Allow() 或 Reserve() 都尝试取一个令牌，桶会按固定速率（rate.Limit）自动填充，满了就丢弃新令牌。
-
rate.Every(100 * time.Millisecond)表示每 100ms 补 1 个令牌，等价于10QPS - 初始化时第二个参数是桶容量（burst），设为
1就完全削平；设为5则允许短时 5 次连发 - 不要在 HTTP handler 里反复
new(rate.Limiter)，应复用单例或按租户/路径分实例
Allow() 和 Reserve() 怎么选
Allow() 是最简接口：返回 bool，true 表示“此刻有令牌可取”，false 就该拒绝。适合无延迟容忍的场景（如 API 鉴权前置拦截）。
Reserve() 返回 *rate.Reservation，能告诉你“如果现在取，要等多久”，适合需要排队或预估延迟的逻辑（比如后台任务调度）。但注意：Reservation.OK() 才表示真正能执行，且必须调用 Cancel() 或 Delay() 后才释放资源。
- 高频低延迟接口（如健康检查）用
Allow()，省去对象分配开销 - 用户操作类接口（如下单）若想给前端返回“稍等 X 秒再试”，用
Reserve()+Delay() - 误用
Reserve()后忘记调用Cancel()会导致令牌未归还，桶逐渐变空
如何在 HTTP handler 中安全集成
直接在 handler 里调用 limiter.Allow() 即可，但要注意两点：一是避免全局单例被所有路由共用（比如登录和公开文档走同一个限流器），二是别让限流逻辑阻塞整个请求处理流程。
- 按路径前缀或用户 ID 做 key 分组：用
sync.Map缓存*rate.Limiter实例，key 是"user:" + userID - 对匿名请求，可用 IP 哈希（
hash/fnv）做 key，但注意 CDN 场景下全是同一个源 IP - 别在
http.HandlerFunc里写time.Sleep(limiter.Reserve().Delay())—— 这会让 goroutine 空等，压垮连接数 - 推荐模式：拒接（429）或透传（allow=true），真要排队请交给下游异步队列
测试时为什么 time.Now() 会干扰限流行为
rate.Limiter 内部依赖 time.Now() 计算令牌生成时间，单元测试中若用真实时间，会导致断言不可靠（比如“刚好卡在补令牌前一秒”）。官方没暴露时钟接口，但可通过包装解决。
- 定义接口
type Clock interface { Now() time.Time }，实现 mock 时钟 - 把
rate.Limiter封装进自定义结构体，接收Clock参数，在测试中注入固定时间 - 或者用
github.com/benbjohnson/clock这类成熟 mock 时钟库，调用clk.Add(1 * time.Second)快进时间验证补桶逻辑 - 漏掉这点，测试覆盖率可能虚高，但线上遇到时钟跳变（如 NTP 校正）就会出现突增或冻结现象
限流不是加个 if !limiter.Allow() { return } 就完事。关键在 burst 容量是否匹配业务毛刺、时钟精度是否影响稳定性、以及不同用户维度是否隔离到位——这些地方一动就出问题，但日志里往往只显示“429 太多”。
