直接用 golang.org/x/time/rate 就能跑通生产环境的令牌桶限流，它是 Go 官方维护、线程安全、轻量高性能的单机限流方案，核心参数为 rate.Limit（每秒令牌数）和 burst（桶容量），默认不跨秒累积令牌，HTTP 接口应优先使用 Allow() 实现快速失败。
直接用 golang.org/x/time/rate 就能跑通生产环境的令牌桶限流，不需要自己手写桶逻辑或强耦合 Redis —— 它是 Go 官方维护、线程安全、支持高并发的轻量实现，且默认行为已足够应对大多数 API 限流场景。
为什么选 golang.org/x/time/rate 而不是手写或第三方库
手写令牌桶容易漏掉时间精度问题（比如用 time.Now().Unix() 算 refill 会丢毫秒级变化），而 uber-go/ratelimit 或 juju/ratelimit 这类第三方库虽然功能多，但多数只提供漏桶语义或不支持 burst 控制；golang.org/x/time/rate 是标准库延伸，API 稳定、无额外依赖、性能经过压测验证。
它核心就两个参数：limit（每秒令牌生成数）和 burst（桶容量），没有“过期时间”“key 命名规则”这类分布式才需要的概念——单机部署时，它就是最简、最稳的选择。
-
limit类型是rate.Limit（本质是float64），设为10表示每秒最多放行 10 个请求 -
burst是int，设为5表示桶最多存 5 个令牌，哪怕前一秒没用完，也不能累积到下一秒（注意：这是它的设计，默认不累积） - 如果想允许跨秒累积，得用
AllowN(time.Now(), n)+ 手动管理时间窗口，但通常没必要
Allow() 和 Wait() 的实际区别与选型
这两个方法决定你如何处理被限流的请求：Allow() 立即返回 true/false，适合“快速失败”；Wait() 会阻塞直到拿到令牌，适合后台任务或内部调用。
- 对外暴露的 HTTP 接口一律用
Allow()：避免客户端长时间等待，直接返回429 Too Many Requests - 如果你在 Gin 中用了
Wait()，必须传带 timeout 的context，否则极端情况下可能 hang 住整个 goroutine -
WaitN(ctx, 2)表示等够 2 个令牌才继续，但要注意：若burst=1，它永远等不到，会一直 block 到 context cancel
Gin 中间件里怎么安全初始化和复用限流器
限流器本身是无状态、可复用的，但千万别在中间件闭包里每次新建 —— 那会创建大量对象，GC 压力陡增，且失去限流意义。
- 全局声明一个
var limiter = rate.NewLimiter(5, 10)，在main()初始化一次即可 - 不要按 path 或 user id 动态 new，除非你明确需要多维度隔离（这时应改用 Redis + 令牌桶，而非单机限流器）
- 如果要对不同路由设不同限流策略，定义多个全局变量，比如
apiLimiter和healthLimiter，然后在对应r.GET("/api/xxx", ...)的Use()中挂载不同中间件 - 测试时可用
limiter.SetLimit()和limiter.SetBurst()临时调整，但生产环境禁止 runtime 修改
容易被忽略的时钟漂移与测试陷阱
本地开发用 time.Now() 没问题，但容器或 K8s 环境下，若节点时钟不同步，AllowN(now, n) 的 now 参数可能引发误判 —— 实际上 golang.org/x/time/rate 内部全用 time.Now()，不接受外部时间戳，所以你传进去的 now 只用于计算“是否该 refill”，并不影响核心逻辑。
- 真正要注意的是：单元测试里别 mock
time.Now后直接调Allow()多次 —— 因为它内部有隐藏状态（上次 refill 时间），连续调用可能因时间未推进导致令牌没刷新 - 测试时建议用
AllowN(time.Now().Add(2*time.Second), 1)强制跳过 refill 判断，或用Reset()（非公开方法，不推荐） - 线上观察指标时，关注
limiter.Limit()返回值是否稳定，以及Allow()的 false 比例突增是否对应某次发布 —— 这比看日志更早发现问题
