95%场景应直接使用golang.org/x/time/rate.Limiter，它基于令牌桶、线程安全、精度可控、API简洁且经生产验证；自行实现易引发并发竞争、时钟漂移、burst边界错误等问题。
直接用 rate.Limiter 就够了，别堆第三方库
生产环境里真没必要一上来就引入 ulule/limiter 或 gin-contrib/limiter。官方 golang.org/x/time/rate 的 rate.Limiter 精度高、无锁、内存开销小，且经过大量服务验证。它不是玩具，是能扛住中等流量的轻量级核心组件。
关键点在于：它本身不带“按 IP”或“按用户 ID”的逻辑——那是你中间件该干的事；rate.Limiter 只管“桶怎么装、令牌怎么拿”。混用全局实例、忽略维度隔离、裸调 Wait(context.Background())，才是线上出问题的主因。
Allow() vs Wait()：选错就卡死或误拒
三个核心方法语义完全不同，不能凭直觉替换：
-
Allow()：非阻塞，返回bool。适合快速失败场景（如登录接口防爆破），没令牌立刻 429，不等。 -
Wait(ctx)：阻塞直到拿到令牌或ctx超时/取消。**绝不能传context.Background()**——否则请求可能永久挂起。必须带 timeout，例如context.WithTimeout(c.Request.Context(), 500*time.Millisecond)。 -
Reserve()：返回*rate.Reservation，可查OK()和Delay()。适合需要预判等待时间再决策的场景（如前端提示“请 300ms 后重试”）。
批量操作要用 AllowN()/WaitN()，但注意：WaitN(ctx, 5) 不代表允许 5 个并发，而是“这 5 个请求必须一起放行或一起拒绝”，适用于原子性要求高的操作（如扣库存）。
立即学习“go语言免费学习笔记（深入）”；
按 IP 或用户 ID 隔离限流器，靠 sync.Map 别用普通 map
单个 rate.Limiter 实例无法区分请求来源。如果所有请求共用一个实例，就会变成“全站共享一个桶”，完全失去限流意义。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
正确做法是为每个维度（如 c.ClientIP()、c.Param("user_id")）维护独立的 *rate.Limiter 实例，并缓存在 sync.Map 中：
- 用
sync.Map替代map + mutex：高并发下后者锁竞争严重，sync.Map读多写少场景性能更好。 - key 构造要小心：IPv6 地址含冒号，建议先标准化（如用
net.ParseIP().String()）；用户 ID 若来自 JWT，需确保可信，避免被伪造。 - 必须清理过期项：长期不访问的限流器会持续占内存。可用后台 goroutine 定期扫描
sync.Map，或结合time.AfterFunc在创建时埋过期回调。
示例 key 可设为 c.ClientIP() + ":" + c.Request.URL.Path，实现“每 IP 每路径独立限流”。
初始化参数别写错：rate.Every() 和 Burst 含义常被误解
rate.NewLimiter(rate.Limit(10), 5) 表示“每秒最多放行 10 个请求，桶初始容量为 5”——注意，“10”是速率（QPS），不是间隔；“5”是突发容量，不是初始剩余数。
更易读的写法是 rate.NewLimiter(rate.Every(time.Second/10), 5)，即“每 100ms 放一个令牌”，等价于 10 QPS。
常见错误：
- 误把
Burst()当作当前剩余令牌数：它只返回桶容量，实际剩余需靠ReserveN(now, 1)预留后查OK()判断。 - 桶容量（
b）设太小：比如b=1时，哪怕速率是 10 QPS，也无法应对任何突发，瞬间就打满。 - 速率单位混淆：传
rate.Limit(0.1)是 0.1 QPS（10 秒 1 次），不是“每 10 秒 1 次”——数值就是每秒令牌数。
真正难的从来不是写几行限流代码，而是想清楚：这个接口到底要防什么？是防爬虫、防误操作，还是保下游稳定性？参数背后是业务判断，不是数学题。
