直接用golang.org/x/time/rate的Limiter会漏请求，因其Wait阻塞goroutine易致HTTP中间件堆积，应改用AllowN或ReserveN非阻塞检查，并按key（如用户ID/IP）配合sync.Map缓存独立limiter实例，避免全局复用或高频新建。
为什么直接用 golang.org/x/time/rate 的 Limiter 会漏请求？
因为 Limiter 默认是「阻塞式」的——调用 Wait 或 Allow 时，若桶中无令牌，Wait 会挂起 goroutine 等待，而 HTTP 中间件里你通常不希望等（尤其在高并发下可能堆积大量 pending 请求）。更常见的是「立即返回」：有令牌就过，没令牌就 429。所以得用 Reserve + Delay 判断，或直接用 AllowN(time.Now(), n) 做非阻塞检查。
-
Allow()等价于AllowN(time.Now(), 1)，适合单请求限流 - 若需支持突发流量（比如允许每秒 100 次，但最多连发 5 次），必须设
burst≥ 1，且用AllowN显式传入数量 - 注意：多次调用
AllowN传不同n值时，burst 是全局共享的，不是按 n 分配的独立桶
如何把 rate.Limiter 安全注入 Gin/HTTP 中间件？
不能每个请求都 new 一个 rate.Limiter，否则内存泄漏+限流失效；也不能全局单例，因为多服务共用会互相干扰。正确做法是按 key（如用户 ID、IP、API 路径）做映射缓存，配合 TTL 清理。
- 用
sync.Map存map[string]*rate.Limiter，key 可以是fmt.Sprintf("%s:%s", ip, path) - 每次请求先查 map，命中则复用；未命中则新建并写入，burst 和 rps 根据业务分级设置（如 /pay 接口 burst=3，rps=1）
- 不建议用 LRU cache（如
gocache），因为rate.Limiter本身带时间状态，TTL 过期后残留的 Limiter 仍会误判 - 若用 Gin，中间件里从
c.ClientIP()取 IP，注意 Nginx 转发时要配置proxy_set_header X-Real-IP $remote_addr;并启用c.Request.Header.Get("X-Real-IP")
遇到 429 Too Many Requests 但日志显示 Limiter 允许了，怎么排查？
大概率是时钟漂移或并发竞争导致的 AllowN 判断与实际执行之间状态不一致——比如两个 goroutine 同时调用 AllowN(now, 1)，都拿到 true，但桶里只剩 1 个令牌。
- 根本解法：用
ReserveN(now, n)返回的*rate.Reservation，再调用其OK()判断，并在确认通过后立刻CancelAt或忽略（不 Cancel 也行，但 Reservation 本身已预留令牌） - 更稳妥的是加一层 CAS 尝试：只在
res.OK() && res.Delay() == 0时放行，避免因系统负载高导致 now 时间戳滞后 - 务必在中间件开头就调
time.Now()并复用该时间戳，不要在AllowN里让 limiter 自己取 now——不同 goroutine 取的时间差哪怕几微秒，burst 计算就会偏移
限流 key 设计不当会导致什么问题？
用固定字符串当 key（比如硬编码 "global"）会让所有请求挤一个桶，看似“全局限流”，实则把登录、健康检查、静态资源全锁死；反过来，如果 key 粒度太细（如带毫秒级时间戳），又会导致缓存爆炸和限流失效。
- 推荐组合：服务名 + 路由路径前缀 + 用户标识（如 JWT subject 或 header 中的
X-User-ID），例如fmt.Sprintf("svc:order:/v1/pay:%s", userID) - 对匿名接口，可用
hash(ip + userAgent[:16])防止 IP 伪造，但别直接用原始 IP——运营商 NAT 下千人共用一个出口 IP - 注意：Gin 的
c.FullPath()比c.Request.URL.Path更可靠，它已解析路由参数，不会把/user/:id和/user/123当成两个 key
令牌桶的 burst 值不是越大越好，它本质是“信用透支额度”；真正压测时你会发现，burst=10 且 rps=1 的配置，在短时 10QPS 下几乎不拦截，但一旦持续超过 1s，后续请求立刻全被挡。这个临界点容易被忽略。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
