单机 golang.org/x/time/rate.Limiter 不能用于分布式场景，因其状态仅存于内存，多实例间不共享，导致实际QPS远超设定值；必须用Redis等外部存储配合Lua原子脚本实现分布式令牌桶。
为什么单机 golang.org/x/time/rate.Limiter 不能直接用于分布式场景
因为 Limiter 的状态（剩余令牌数、上次填充时间）完全保存在内存里，不同服务实例之间不共享。哪怕你用相同的配置初始化 10 个 Limiter，它们各自独立计数，实际总请求量可能轻松突破你设定的 QPS 上限。
常见错误现象：压测时单机没超限，但整体后端被打挂；灰度发布新节点后限流突然失效；K8s 水平扩缩容后限流阈值漂移。
关键判断：只要服务部署 ≥2 个实例，或未来可能扩容，就必须引入外部状态存储。Redis 是最常用、最可行的选择——它支持原子操作、低延迟、有 INCR/EXPIRE 组合能模拟桶行为，且 Go 生态有成熟客户端（如 github.com/redis/go-redis/v9）。
用 Redis 实现令牌桶的核心原子操作逻辑
不能靠读-改-写三步走（会竞态），必须用 Lua 脚本把「检查剩余令牌、扣减、按需重置时间戳、返回是否允许」全部打包成一个原子操作。
实操建议：
- 脚本 key 传桶名（如
"rate:api:/user/profile"），用ARGV[1]传当前时间戳（毫秒），ARGV[2]传令牌填充速率（如每秒 100 个 → 每毫秒 0.1 个），ARGV[3]传桶容量（如 200） - 先用
GET读当前状态（tokens和last_fill），若不存在则初始化为满桶 + 当前时间 - 计算应补充令牌：
min(capacity, tokens + (now - last_fill) * rate)，注意单位统一（全部转毫秒） - 判断
tokens >= 1：是则DECR并更新last_fill，返回 1；否则返回 0 - 务必对 key 设置
EXPIRE（比如 5 分钟），避免冷桶长期占内存
示例 Lua 片段（嵌入 Go 时用 rdb.Eval(ctx, script, keys, args...) 调用）：
local tokens_key = KEYS[1]
local now = tonumber(ARGV[1])
local rate = tonumber(ARGV[2])
local capacity = tonumber(ARGV[3])
<p>local bucket = redis.call("HMGET", tokens_key, "tokens", "last_fill")
local tokens = tonumber(bucket[1]) or capacity
local last_fill = tonumber(bucket[2]) or now</p><p>local delta = math.max(0, now - last_fill)
local new_tokens = math.min(capacity, tokens + delta * rate)</p><p>if new_tokens >= 1 then
redis.call("HMSET", tokens_key, "tokens", new_tokens - 1, "last_fill", now)
redis.call("EXPIRE", tokens_key, 300)
return 1
else
return 0
end</p>
Go 客户端封装要点与易踩的坑
别裸写 Lua 调用——封装成结构体，隐藏脚本和参数组装逻辑，暴露干净的 Allow() 方法。
容易忽略的关键点：
-
rate参数单位必须是「令牌/毫秒」，不是「令牌/秒」。传错会导致桶几乎不填充（比如传 100 当作每秒 100，实际变成每毫秒 100，一秒就补满 10 万令牌） - Redis 连接池要复用，
Allow()方法里不要每次新建redis.Client - 网络超时必须设（如
ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)），否则 Redis 卡住会拖垮整个 HTTP 请求 - 当
redis.Nil错误（key 不存在）或 Lua 返回 0 时，都算“被限流”，但前者极少发生（因脚本里做了初始化），后者才是常态 - 本地缓存？别加。分布式限流的语义要求强一致性，加缓存会让部分请求绕过限制
性能与边界情况怎么验证
真实压力下，瓶颈往往不在 Lua 脚本，而在 Redis 网络往返和连接竞争。
实操建议：
- 用
go-wrk或hey压测，QPS 设为限流值的 2–3 倍，观察 Redis 的latency和connected_clients是否飙升 - 故意 kill 一个 Redis 节点（如果是集群），看客户端是否快速 failover，还是卡死在重试上
- 测试时钟回拨：手动把某台机器时间往回调 1 秒，看脚本里
math.max(0, now - last_fill)是否兜住（必须兜住，否则delta为负会导致令牌数异常） - 桶容量设极小值（如 1）+ 高频请求，确认是否严格按间隔放行（可用
time.Now()打日志验证）
真正难调的是时钟精度和 Redis RT 波动的组合——当平均 RT 是 2ms，但 P99 到 15ms 时，两次请求的时间戳差可能比实际间隔小，导致多扣令牌。这种情况下，要么接受轻微过载，要么改用滑动窗口（但那就不是令牌桶了）。
