直接复用单个 rate.Limiter 实例会导致并发不安全,因 Allow/Wait 非线程安全;正确做法是按 key(如 IP)分桶,用 sync.Map 或 LRU 缓存管理带 TTL 的 Limiter 实例,并注意 key 提取性能与上下文超时控制。

为什么直接用 golang.org/x/time/rate 的 Limiter 在 HTTP 中间件里容易出错
因为 Limiter 的 Allow 和 Wait 方法不是并发安全的——它们内部修改共享状态但不加锁,而 HTTP 服务器(如 net/http)对每个请求都起 goroutine,并发调用时会破坏令牌桶的计数逻辑,导致漏放或误拒。你看到的“偶尔放过超额请求”或“连续拒绝正常请求”,大概率是这个原因。
正确做法是:每个请求独占一个 rate.Limiter 实例,或用线程安全封装。但更常见、也更合理的方案是按 key(如用户 ID、IP)做分桶管理,这时必须自己维护 map + sync.Pool 或 sync.Map,不能全局共用一个限流器。
- 不要在中间件闭包里初始化单个
rate.NewLimiter然后复用 - 避免用
map[string]*rate.Limiter直接读写——高并发下 panic 或数据竞争 - 如果用
sync.Map,注意它的LoadOrStore返回值是any,要显式类型断言为*rate.Limiter
如何为不同用户/IP 动态创建并复用 rate.Limiter
核心是控制实例数量和生命周期。无节制地为每个新 IP 创建新 Limiter 会导致内存持续增长;全量缓存又可能击穿内存。推荐用带驱逐策略的本地缓存,比如 golang.org/x/exp/maps 不适用,改用 sync.Map + TTL 控制。
实际中更轻量的做法是:用固定大小的 LRU cache(例如用 github.com/hashicorp/golang-lru/v2),或者干脆用带过期的 sync.Map 自实现简易 TTL——每次访问时检查最后更新时间,超时则丢弃并重建。
- key 建议用
req.RemoteAddr(含端口)或提取后的 IP 字符串,注意 IPv6 格式统一 - 速率参数(如
rate.Every(100 * time.Millisecond))建议从配置中心加载,不要硬编码 - 初始 burst 值设为 1~3 即可,太大削弱限流效果,太小导致首请求必等
// 示例:按 IP 分桶,带简单 TTL 清理
var limiters = sync.Map{} // map[string]*rate.Limiter
<p>func getLimiter(ip string) <em>rate.Limiter {
if lim, ok := limiters.Load(ip); ok {
return lim.(</em>rate.Limiter)
}
lim := rate.NewLimiter(rate.Every(200*time.Millisecond), 2)
limiters.Store(ip, lim)
return lim
}
</p>
rate.Limiter.Wait 在中间件里阻塞请求时要注意什么
HTTP handler 是阻塞式执行的,Wait 会挂起当前 goroutine 直到拿到令牌,这本身没问题;但若限流阈值设得太严(比如每秒 1 次),用户连续刷新就会排队,后端连接数陡增。更危险的是:如果客户端提前断开(如关闭浏览器),Wait 仍会等到令牌再返回,造成资源滞留。
- 务必配合
ctx.Done()使用WaitN,而不是裸调Wait - 不要在
http.HandlerFunc里直接调limiter.Wait(ctx),要传入 request.Context() - 如果用
gin.Context或echo.Context,记得用其自带的Request.Context(),别用 background context - 超时错误要明确返回
http.StatusTooManyRequests,并带上Retry-Afterheader(值可取limiter.Reserve().Delay())
性能瓶颈往往不在限流逻辑本身,而在 key 提取和 map 查找
实测表明,在 QPS > 5k 的服务中,req.RemoteAddr 解析、字符串拼接、sync.Map.Load 占用 CPU 超过 40%。IPv6 地址格式不一(带端口/不带端口/压缩写法)会让哈希分布变差;频繁 GC 也会拖慢 sync.Map 的 Store 路径。
- 优先用
req.Header.Get("X-Real-IP")或X-Forwarded-For的第一个非私有 IP,避免用RemoteAddr - key 构造尽量用
unsafe.String+ 预分配字节数组,减少字符串分配(Go 1.20+ 可行) - 如果业务允许,把限流粒度从 “每 IP” 改成 “每 API 路径 + IP”,用
req.URL.Path拼接,能显著降低冲突率 - 压测时重点看
runtime.mallocgc和sync.map.load的 p99 耗时,超过 50μs 就得优化 key 生成逻辑
真正难的不是写对一个限流器,而是让成千上万个限流器在内存可控、GC 干净、key 分布均匀的前提下跑满 CPU。多数人卡在第三步——没意识到 map 查找和字符串操作才是瓶颈。











