95%场景应直接使用golang.org/x/time/rate.Limiter，它基于令牌桶、线程安全、精度可控、API简洁且经生产验证；自行实现易引发并发竞争、时钟漂移、burst边界错误等问题。
限流器该用 golang.org/x/time/rate 还是自己写？
直接结论：95% 的场景用 golang.org/x/time/rate.Limiter 就够了，不建议手撸。它基于 token bucket 实现，线程安全、精度可控、API 简洁，且经过长期生产验证。自己实现容易忽略并发竞争、时钟漂移、burst 边界行为等问题，比如漏桶变“漏勺”、突发流量被误拒、Reserve() 返回的 time.Time 被误当成绝对时间等。
常见错误现象：Allow() 在高并发下返回 false 频率异常高；单位时间内实际通过请求数远低于预期（如设了 100 QPS，实测仅 60）；服务重启后首次请求被卡住几秒——这通常是因为没调用 SetLimitAt() 或忽略了 Limiter 初始化时的起始时间偏移。
-
rate.NewLimiter(rate.Limit(100), 10)表示“每秒最多 100 个 token，初始桶容量为 10”，注意 burst 值不是并发数，而是允许的瞬时突增上限 - 若需严格控制每秒精确 100 次（不允许任何突增），burst 设为 1，但会牺牲响应柔性；设为 100 才能真正支撑峰值流量平滑通过
- 不要在每次 HTTP 请求中新建
Limiter，应复用单例或按租户/路径粒度缓存实例
HTTP 中间件里怎么嵌入 rate.Limiter？
核心是把限流逻辑放在 handler 执行前，并对拒绝请求返回明确状态码（通常是 429 Too Many Requests）和 Retry-After 头。别用 Allow() 简单判断——它不提供等待信息；优先用 ReserveN(time.Now(), n)，它返回的 Reservation 可查是否 OK、何时可执行、是否需要 sleep。
使用场景：API 网关、微服务入口、管理后台操作接口。注意别在 WebSocket upgrade handler 或文件上传流式处理中直接套用，这类长连接或大体积请求不适合以“请求数”为维度限流。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 若限流对象是用户 ID，从
ctx或header提取X-User-ID后做 map 查找对应*rate.Limiter，避免全局锁 - 务必调用
res.OK()判断是否获得许可，而不是只看err；res.Delay()非零时，可选择 sleep 或直接拒绝并设Retry-After: res.Delay().Seconds() - 避免在 defer 中调用
res.Cancel()——如果 handler panic，可能已执行部分业务逻辑，此时取消 reservation 会导致 token 白白浪费
rate.Limiter 的 WaitN 和手动 sleep 有什么区别？
WaitN 是封装好的阻塞式等待，内部会根据当前 token 余量和速率自动计算 sleep 时间，并在唤醒后尝试获取 token；而手动调用 time.Sleep(res.Delay()) 后仍需再调用 res.Ok() 或重新 ReserveN，否则可能因期间 token 被其他 goroutine 消耗而导致失败。
性能影响：两者底层都依赖系统时钟，但 WaitN 减少了用户层重复判断，也规避了因 sleep 不准（如被抢占、GC STW）导致的额外延迟。不过它会阻塞 goroutine，若你用的是短生命周期 goroutine（如 http.HandlerFunc），这点开销可忽略；若在长任务中调用，要考虑上下文超时是否覆盖了等待时间。
-
WaitN(ctx, n)支持传入context.Context，当等待中 ctx 被 cancel 或 timeout，它会立即返回 error，比手动 sleep + select 更健壮 - 不要在循环里反复调用
WaitN等待单个 token——应一次性申请所需数量（如批量操作需 5 个 quota，就WaitN(ctx, 5)），否则可能被拆成多次等待，放大延迟 - 如果业务允许“尽力而为”，用
ReserveN+ 非阻塞逻辑更合适；若必须等，WaitN是更简洁的选择
如何支持动态调整 QPS 而不重启服务？
rate.Limiter 本身不提供运行时修改 limit 的方法，但可以通过原子替换指针来实现热更新。关键不是改旧对象，而是用新配置创建新 *rate.Limiter，然后用 atomic.StorePointer 替换旧引用——所有 goroutine 下次访问时自然拿到新实例。
容易踩的坑：直接调用 limiter.SetLimit() 是无效的（该方法已被弃用且无作用）；用 sync.RWMutex 保护读写虽可行，但会引入锁开销，且读多写少场景下不如原子指针高效。
- 定义类型
type LimiterPtr struct{ ptr unsafe.Pointer }，用atomic.LoadPointer读，atomic.StorePointer写 - 更新时先 new 一个
rate.NewLimiter(newLimit, burst)，再 store，确保新旧 limiter 之间无状态继承（token 桶重置是合理行为） - 配合配置中心（如 etcd、Apollo）监听变更事件，在回调中触发 limiter 替换，注意处理监听失败、配置非法（如 limit ≤ 0）等边界
真正复杂的是多级限流叠加时的状态一致性——比如接口级 + 用户级 + IP 级三层限流，各自独立更新节奏不同，此时不能只靠原子替换，得引入版本号或事件广播机制来协调，否则会出现某一层已升配、另一层还在降配窗口期的误判。
