rate.Limiter基于令牌桶算法实现轻量可靠限流，支持全局复用、中间件集成、key级分桶及标准响应头，但单机限流无法解决分布式一致性问题。
用 golang.org/x/time/rate 实现每秒请求数限制
Go 官方扩展包 rate 是最轻量、最可靠的选择，它基于令牌桶算法，能平滑控制突发流量。不要自己手写计数器或时间窗口逻辑——容易漏掉并发竞争、时钟漂移、goroutine 泄漏等问题。
关键点：
-
rate.Limiter是线程安全的，可全局复用，无需为每个请求新建 - 初始化时指定
limit（每秒令牌数）和burst（桶容量），例如rate.NewLimiter(5, 10)表示“平均 5 QPS，最多允许 10 次瞬时并发” - 使用
Limiter.Wait(ctx)阻塞等待可用令牌，或Limiter.Allow()非阻塞判断——后者需手动返回 429
在 HTTP handler 中嵌入限流逻辑
限流应放在中间件层，而不是每个业务 handler 内硬编码。避免重复逻辑，也方便统一开关和指标上报。
常见错误：在 handler 开头直接调用 limiter.Wait(r.Context()) 却没处理 context 取消，导致超时请求仍占用令牌。正确做法是确保 Wait 能响应 cancel 或 timeout：
立即学习“go语言免费学习笔记（深入）”；
func rateLimitMiddleware(next http.Handler) http.Handler {
limiter := rate.NewLimiter(rate.Limit(10), 5)
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !limiter.Allow() {
http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
return
}
next.ServeHTTP(w, r)
})
}
注意：Allow() 不阻塞，适合无延迟敏感场景；若需精确配额（如按用户 ID 分桶），需配合 sync.Map 或外部存储做 key 级限流。
按用户 IP 或 API Key 区分限流策略
单一全局限流无法满足多租户或差异化配额需求。必须将限流器与标识符绑定，但不能为每个 key 新建 rate.Limiter——内存和 GC 压力会随 key 数线性增长。
推荐做法是复用限流器实例，用 LRU 缓存 + TTL 控制生命周期：
- 用
sync.Map存储map[string]*rate.Limiter，key 是ip或api_key - 每次请求先查 map，命中则复用；未命中则新建并写入，同时设置过期清理（例如用定时 goroutine 清除 1 小时未使用的 entry）
- 避免直接用
net/http.Request.RemoteAddr做 IP，需解析X-Forwarded-For并校验可信代理链
限流失败时返回标准 HTTP 响应头
仅返回 429 状态码不够。客户端需要知道“什么时候能重试”，否则只能盲等或退避策略失效。
务必设置以下 header：
-
X-RateLimit-Limit：当前窗口最大请求数（如60） -
X-RateLimit-Remaining：剩余可用请求数（需动态计算） -
X-RateLimit-Reset：时间戳（Unix 秒），表示窗口重置时刻
注意：rate.Limiter 本身不暴露剩余令牌数，需自行维护计数或改用更高级库（如 uber-go/ratelimit）——但多数场景下，用固定窗口 + Redis 计数反而更易对齐前端预期。
真正难的是跨进程一致性。单机 rate 包解决不了分布式部署下的总量控制，这时候必须切到 Redis + Lua 原子脚本，且要小心网络延迟导致的“临界窗口错位”。
