为什么不用 sync.Once 做限流器单例？
因为 sync.Once 只保证初始化一次，不解决并发访问时的计数竞争问题。限流器核心是「判断 + 更新」原子操作，比如令牌桶扣减或滑动窗口时间片统计——sync.Once 完全不参与这个过程，它只帮你 new 一次对象，后续所有 Allow()、Reserve() 还得自己加锁或用原子操作。
常见错误现象：rate.Limiter 实例被多次初始化，或多个协程同时调用 TryConsume() 导致漏判（本该拒绝的请求放行了）。
- 正确做法：单例封装的是带状态的限流器实例，不是创建逻辑本身
- 推荐用
sync.Once配合指针变量做懒初始化，但必须确保返回的实例本身线程安全 - 标准库
golang.org/x/time/rate的*rate.Limiter本身就是并发安全的，直接复用即可
如何安全导出全局 rate.Limiter 实例？
关键不是“怎么定义”，而是“怎么保证多包引用时仍为同一实例”。Go 的包级变量天然满足这点，但要注意初始化时机和循环依赖风险。
使用场景：http handler、消息队列消费者、定时任务等需要统一限流策略的模块。
立即学习“go语言免费学习笔记（深入）”；
- 在独立包（如
pkg/limiter）中定义var GlobalLimiter = rate.NewLimiter(rate.Limit(100), 200) - 不要在
init()里动态读配置初始化——配置加载失败会导致包初始化崩溃，且无法重试 - 如果需运行时热更新限流参数，改用函数封装：
func GetLimiter() *rate.Limiter，内部用sync.Once+ 原子指针替换 - 避免跨包直接修改
GlobalLimiter字段（如GlobalLimiter.limit），它没导出，也不该被绕过接口修改
多协程调用 Allow() 会丢精度吗？
不会丢，但会因「允许窗口」设计产生意料外的放行。比如 rate.NewLimiter(10, 5) 表示每秒 10 次，初始可突增 5 次；若前 100ms 内来了 6 个请求，第 6 个会被阻塞约 900ms，而不是立刻拒绝——这是令牌桶的正常行为，不是 bug。
容易踩的坑：
- 误以为
Allow()是硬拒绝：它其实是“尝试立即获取令牌”，返回 false 仅表示此刻无令牌，不代表永远不行 - 在 HTTP handler 中直接用
Allow()而不处理WaitN()或ReserveN()的等待逻辑，导致高并发下响应延迟毛刺 - 未设置上下文超时，
WaitN(ctx, n)可能无限期挂起，应始终传入带 deadline 的ctx - 注意单位：
rate.Limit是「每秒事件数」，不是「每毫秒」，别把 100 QPS 错写成rate.Every(time.Millisecond * 10)
替代方案：为什么有时该选 golang.org/x/exp/slog + 自定义限流器？
当标准 rate.Limiter 不够用时，比如要按用户 ID 分桶限流、或结合 redis 做分布式限流，就别硬套单例全局模式了。这时候单例反而成了瓶颈或误用源头。
性能与兼容性影响：
- 纯内存限流（
rate.Limiter）适合单机高吞吐，QPS 过万也没压力；但无法跨进程共享状态 - 想支持按 key 限流？别改造全局单例，改用
map[String]*rate.Limiter+sync.Map，并配 TTL 清理，否则内存泄漏 - 要用 Redis？直接上
github.com/bsm/redislock或github.com/go-redis/redis/v9实现滑动窗口，此时“全局单例”概念应退化为“全局 Redis 客户端实例”，限流逻辑下沉到方法里
真正难的从来不是怎么写一个 GetGlobalLimiter()，而是想清楚：这个“全局”，到底要全局到什么粒度——是整个进程，还是某个租户，还是某类 API 路径。没想清这点，代码越“规范”，越容易返工。