golang.org/x/time/rate.limiter就是go生态中高性能限流器，基于无锁令牌桶、纳秒级开销、不启goroutine；其limit需用rate.every(d)构造，burst是桶容量而非并发数，须按业务流量压测设定。
直接用 rate.Limiter，别自己封装“高性能模块”
Go 生态里不存在需要你从零写的“高性能限频令牌模块”——golang.org/x/time/rate.Limiter 就是它。它不启 goroutine、不依赖 ticker、无锁（全 atomic）、纳秒级开销（实测 10–50ns），比任何手写 sync.Mutex 计数器都快且准。自己实现只会引入时钟漂移、窗口边界漏放、goroutine 泄漏等隐性 bug。
rate.NewLimiter 两个参数的真实含义
很多人把 rate.NewLimiter(limit, burst) 理解成“QPS 和并发数”，这是错的。它实际定义的是令牌生成节奏和桶容量：
-
limit必须用rate.Every(d)构造，比如rate.Every(200 * time.Millisecond)表示每 200ms 补 1 个 token（≈5 QPS）；写rate.Limit(5)看似等价，但浮点运算会导致长期速率漂移 -
burst是桶容量，不是“最大并发”。设为 1 就退化成严格匀速，大量请求排队；设为 10 才能吸收脉冲；但别超 1000，否则首次突发后 token 长期不耗尽，限流形同虚设 - 桶初始满，但内部时间戳从第一次调用才开始记——服务刚启动遭遇突发，
burst全占完，后续请求立刻被拒，这是设计使然，不是 bug
按 IP 或用户限频时 sync.Map 的三个雷区
复用 *rate.Limiter 实例是前提，但不同维度必须各自独立桶。用 sync.Map 缓存时容易踩坑：
- key 必须标准化：
net.ParseIP(ipStr).To16()转固定长度字节数组再转 string；别拼r.RemoteAddr或未校验的X-Forwarded-For，格式不一或易伪造 - 代理可信性必须校验：先判断
net.ParseIP(r.RemoteAddr).IsPrivate()或比对trustedProxies白名单，可信才取X-Forwarded-For最左非私有地址 -
sync.Map不带 TTL，长期运行内存泄漏：必须后台 goroutine 定期扫描time.Since(lastUsed) > 1h的 entry 并Delete
HTTP 中间件里怎么避免常见误用
限流逻辑嵌入 handler 时，错误集中在实例生命周期和判断方式：
- 绝不能每次请求都新建
rate.Limiter：它不是一次性的，要全局复用或按 key 复用 - 别用
len(tokenCh) == 0判断（那是 channel 缓冲区长度，不等于可用令牌数），也别用Allow()做阻塞决策——它不返回等待时间，无法配合 context 超时 - 优先用
limiter.ReserveN(ctx, n)：返回*rate.Reservation，可调.Delay()算等待时间，或.Cancel()归还，真正支持上下文取消和细粒度控制
最常被忽略的点是：burst 设大了看起来“不限流”，设小了又导致平均延迟飙升——这不是参数调优问题，而是业务流量特征没摸清。上线前必须用真实压测数据验证，而不是凭经验拍。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
