go语言无开箱即用分布式令牌桶，rate.limiter仅支持单机内存限流；分布式需借助redis+lua实现原子判断与扣减，并处理时钟漂移、降级策略及key隔离。
Go 语言本身不提供开箱即用的分布式令牌桶实现，golang.org/x/time/rate 的 Limiter 是单机内存型，无法跨进程/节点共享桶状态。真要落地分布式限流，必须引入外部存储和协调机制。
为什么不能直接用 rate.Limiter 做分布式限流
rate.Limiter 所有状态（当前令牌数、上次填充时间）都存在内存里，多个服务实例各自维护一份，完全不感知彼此。哪怕所有实例用同一套配置，实际通过的请求数也会远超预期阈值。
- 现象：压测时 QPS 明显突破设定值，且实例越多超得越狠
- 根本原因：没有全局时钟对齐 + 没有原子性令牌扣减
- 误区：有人尝试用 Redis + Lua 封装
rate.Limiter接口，但只是“借壳”，核心逻辑仍被绕过
Redis + Lua 是最务实的分布式令牌桶落地方案
关键不是“用不用 Redis”，而是怎么用——必须把“判断+扣减”封装成一个原子操作，且能处理瞬时并发和时钟漂移。
- 推荐使用固定窗口 + 令牌预生成（如每秒预写入 N 个 token 到
redis:token_bucket:{key}），配合DECR原子扣减 - 更精确的做法是用 Lua 脚本实现滑动窗口式填充：每次请求先计算应有令牌数（基于
now - last_fill_time），再更新last_fill_time和剩余令牌 - 注意
redis-server版本需 ≥ 6.0，否则TIME在 Lua 中返回的是服务器本地时间，多节点间可能不一致 - 示例 Lua 片段核心逻辑：
local key = KEYS[1] local capacity = tonumber(ARGV[1]) local rate = tonumber(ARGV[2]) -- tokens per second local now = tonumber(ARGV[3]) local last_time = tonumber(redis.call('HGET', key, 'last_time') or '0') local tokens = tonumber(redis.call('HGET', key, 'tokens') or tostring(capacity)) <p>local delta = math.min((now - last_time) * rate, capacity) tokens = math.min(capacity, tokens + delta) local allowed = (tokens >= 1) and 1 or 0 if allowed == 1 then tokens = tokens - 1 end redis.call('HMSET', key, 'tokens', tokens, 'last_time', now) return {allowed, tokens}</p>
客户端 SDK 设计必须屏蔽 Redis 细节，但不能隐藏语义代价
封装成类似 limiter.AllowN(ctx, "api:/user", 1) 很诱人，但容易让人忽略背后网络延迟、Redis 故障降级、以及“允许”不等于“一定成功”的事实。
- 必须支持 fallback 策略：如 Redis 不可用时，自动退化为本地
rate.Limiter（需明确标注“降级模式”，避免误判容量） - 调用方需处理
context.DeadlineExceeded—— Redis RT 高时，限流判断本身可能超时，此时不应放行，而应拒绝 - 不要复用同一个
redis.Client实例做限流和业务缓存，网络抖动或慢查询会互相拖累 - Key 命名必须带租户/环境前缀，例如
limiter:prod:api:/order/create，否则测试环境刷掉生产配额就麻烦了
真正难的不是写通 Lua 脚本，而是定义清楚“谁负责重置桶”“时钟源以哪台机器为准”“突发流量下令牌欠款怎么算”。这些决策一旦定错，监控看不出来，压测也未必暴露，上线后才在凌晨三点开始丢请求。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
