因为rate.Limiter无key分片能力，直接套用会导致全局共用或每请求新建，无法实现按endpoint、用户ID等维度的差异化限流；正确做法是封装sync.Map+rate.Limiter的分片池，并通过可配置keyFn提取限流键。
为什么不用 golang.org/x/time/rate 直接套用？
因为 rate.Limiter 本身不带上下文感知和并发安全的“请求计数器”语义，直接在 HTTP handler 里 new 一个 rate.NewLimiter 每次调用 Allow() 或 Wait() 看似可行，但容易漏掉两个关键点：一是没绑定到具体路由/方法维度，二是没处理 burst 超限后如何响应（比如返回 429）。微服务场景下，你通常需要按 endpoint、用户 ID、甚至租户 ID 做差异化限流，而原生 rate.Limiter 是单实例单策略的。
怎么把 golang.org/x/time/rate 包装成可复用组件？
核心是封装一层带 key 分片的限流器池，避免全局锁。推荐用 sync.Map + rate.Limiter 组合：
type RateLimiter struct {
limiters sync.Map // key: string → *rate.Limiter
r rate.Limit
b int
}
func (rl *RateLimiter) GetLimiter(key string) *rate.Limiter {
if lim, ok := rl.limiters.Load(key); ok {
return lim.(*rate.Limiter)
}
lim := rate.NewLimiter(rl.r, rl.b)
rl.limiters.Store(key, lim)
return lim
}
func (rl *RateLimiter) Allow(key string) bool {
return rl.GetLimiter(key).Allow()
}
注意：rate.NewLimiter 的第二个参数 b（burst）不能设为 0，否则 Allow() 永远返回 false；常见误配是 rate.Every(time.Second) 配 b=0，结果所有请求都被拒。
HTTP middleware 中怎么注入限流逻辑？
别在 handler 里硬编码 key 构造逻辑。把 key 提取抽成函数，方便测试和替换：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 按 path 限流：
r.URL.Path - 按 user header 限流：
r.Header.Get("X-User-ID") - 组合 key：
fmt.Sprintf("%s:%s", r.URL.Path, r.Header.Get("X-Tenant-ID"))
middleware 示例：
func RateLimitMiddleware(rl *RateLimiter, keyFn func(*http.Request) string) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
key := keyFn(r)
if !rl.Allow(key) {
http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
return
}
next.ServeHTTP(w, r)
})
}
}
调用时传入具体策略：keyFn := func(r *http.Request) string { return r.URL.Path }，而不是写死在 middleware 内部。
为什么不用第三方库如 uber-go/ratelimit 或 go-redsync/redsync？
uber-go/ratelimit 是 token bucket 实现，但它是无状态的单实例限流器，不维护 key 映射，仍需你自己做分片；redsync 依赖 Redis，属于分布式限流范畴——你在问“单机限流”，引入 Redis 就偏离了目标，还带来连接、序列化、超时等额外复杂度。真正需要单机高性能限流时，sync.Map + x/time/rate 组合足够，压测下 QPS 能稳定在 10w+，且无外部依赖。
真正容易被忽略的是：burst 值不是越大越好，它代表“突发容忍窗口”，设太大等于形同虚设；另外 key 的散列质量影响 sync.Map 的实际并发性能，避免用高基数、长字符串做 key（比如完整 JWT），优先截取或哈希后再用。
