应选用 golang.org/x/time/rate 的 rate.Limiter——基于令牌桶、线程安全、经高并发验证；避免手写实现，注意 burst 与 r 的语义、按用户隔离实例、用 Wait 而非 Allow、配合 Header 返回限速状态、不跨节点共享、SetLimitAndBurst 支持运行时调整。
限速器选 golang.org/x/time/rate 而不是自己手写
Go 官方扩展包里的 rate.Limiter 是当前最稳妥的选择——它基于令牌桶算法，线程安全，且已通过高并发压测验证。自己用 time.Ticker 或 sync.Mutex + time.Now() 实现，容易在边界条件下漏放行或误拦截，尤其在突发流量下表现不稳定。
常见错误现象：rate.NewLimiter(10, 5) 被误认为“每秒最多 10 次”，实际是“初始桶容量 5，每秒补充 10 个令牌”。若请求密集到达，前 5 次会立刻通过，第 6 次开始等待。这点必须和业务预期对齐。
- 令牌桶容量（
burst）应 ≥ 单次 API 调用可能消耗的令牌数（比如上传大文件接口可设为 100） - 填充速率（
r）单位是「令牌/秒」，不要传time.Second * 2这类值——rate.Every才负责转换，直接传数值更清晰 - 如果 API 需按用户 ID 区分限速，别复用同一个
rate.Limiter实例；用map[string]*rate.Limiter+ 读写锁，或更推荐sync.Map存储
HTTP 中间件里调用 limiter.Wait 而非 Allow
用 limiter.Allow() 只能返回布尔值，无法知道“这次请求要等多久”，而 API 自动限速的关键在于：不丢请求、不堆积、可控延迟。用 limiter.Wait(ctx) 可以让请求自然排队，同时支持超时控制。
典型场景：前端轮询状态接口，期望稳定 2qps，但客户端偶尔发快了。若用 Allow() 直接 429，用户体验断层；用 Wait() 则平滑延后执行，服务端压力更均衡。
-
ctx必须带超时，例如ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)，否则慢请求可能无限阻塞 - 不要在
Wait前做耗时操作（如 DB 查询），否则限速失去意义——令牌已扣，但请求还没真正开始处理 - 如果想记录等待时间，可在
Wait前后打日志：start := time.Now(); limiter.Wait(ctx); log.Printf("waited %v", time.Since(start))
配合 HTTP Header 返回限速状态（X-RateLimit-Limit 等）
纯限速不够，调用方需要感知配额余量才能做退避或提示。Go 的 rate.Limiter 不直接暴露剩余令牌数，得靠估算：用 limiter.ReserveN 获取预留对象，再调用其 Delay() 和 OK()，最后手动计算。
注意：这个估算不是原子的，两次调用间可能有其他 goroutine 消耗令牌，所以只适合“近似展示”，不能用于决策。
- 示例逻辑：先
r := limiter.ReserveN(time.Now(), 1)，若r.OK()为 true，则剩余 ≈r.Limit() - r.Tokens()（需注意r.Limit()是每秒速率，不是当前桶值） - 标准 Header 推荐返回三个：
X-RateLimit-Limit: 100（每秒配额）、X-RateLimit-Remaining: 92（估算）、X-RateLimit-Reset: 1717023480（Unix 时间戳，表示下次重置时间，可用time.Now().Add(time.Second)算） - 别把
Remaining写死成burst - used——令牌桶是动态填充的，静态减法误差极大
避免在微服务中跨节点共享限速状态
多个 Go 实例部署时，rate.Limiter 是进程内状态，天然不共享。强行用 Redis + Lua 做分布式限速（如 INCR + EXPIRE）会引入网络延迟和单点故障，反而破坏 API 的低延迟目标。
真实系统中更可行的做法是：在入口网关（如 Envoy、API Gateway）统一限速，Go 服务只做二级保护；或者接受“每实例独立限速”，用扩缩容+负载均衡来摊薄偏差。
- 如果真需要全局精确计数（如付费用户的总调用次数），改用持久化存储，但限速逻辑要降级为异步检查+异步更新，避免阻塞主流程
-
rate.Limiter的SetLimitAndBurst支持运行时调整，适合灰度变更配额，但注意它不保证所有 goroutine 立即看到新值——新请求会生效，正在 Wait 的请求仍按旧规则走完 - 测试时别忘覆盖“极限 burst”场景：用
limiter.ReserveN(now, burst+1)触发等待，验证是否真卡住而不是跳过
限速逻辑越靠近网络边缘越可靠，Go 服务内的限速本质是兜底。别指望靠它解决架构层问题，也别为了“精确”把简单事情搞复杂。
