令牌桶比计数器更适合Web接口限流，因其能平滑放行请求、避免窗口边界流量突增；需用Lua脚本保证“检查-补发-判断-更新”四步原子性，并妥善处理时间跳变、冷启动、多实例一致性等边界问题。
为什么令牌桶比计数器更适合 Web 接口限流
因为计数器（如 INCR + 过期）在窗口边界会突增流量，而令牌桶能平滑放行请求，更贴合真实业务节奏——比如你设了每秒 10 个令牌，那无论请求是均匀来还是短时爆发，只要桶里有令牌就能过，没令牌就直接拒绝，不排队不积压。
Redis 本身不支持原子性“取令牌+更新剩余量”，所以必须用 Lua 脚本保证操作不可拆分。漏桶虽也平滑，但实现复杂且不支持突发，对 API 场景不够友好。
用 Lua 脚本实现原子令牌桶的关键逻辑
核心是：检查当前令牌数、按时间补发、判断是否够用、更新剩余值——这四步必须在一个 EVAL 中完成，否则并发下会超发。
- 脚本接收 4 个参数：
key（桶名）、rate（每秒生成令牌数）、capacity（桶容量）、now（毫秒时间戳） - 用
redis.call("HMGET", KEYS[1], "last_fill", "tokens")一次性读状态，避免多次往返 - 补令牌公式是：
tokens = min(capacity, tokens + (now - last_fill) / 1000 * rate)，注意单位换算和向下取整 - 返回值设计为 2 元素数组：
{allowed: 0|1, remaining: int}，Python 侧靠这个做决策
local key = KEYS[1]
local rate = tonumber(ARGV[1])
local capacity = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
<p>local res = redis.call("HMGET", key, "last_fill", "tokens")
local last_fill = tonumber(res[1]) or now
local tokens = tonumber(res[2]) or capacity</p><p>local delta = math.max(0, now - last_fill) / 1000
tokens = math.min(capacity, tokens + delta * rate)
tokens = math.floor(tokens)</p><p>local allowed = 0
if tokens >= 1 then
tokens = tokens - 1
allowed = 1
end</p><p>redis.call("HMSET", key, "last_fill", now, "tokens", tokens)
redis.call("EXPIRE", key, 60)
return {allowed, tokens}Python 中调用时的 Redis 连接与异常处理要点
别用 redis-py 默认的 ConnectionPool 配置直连生产 Redis，高并发下连接打满或超时会导致限流失效——看起来“没限住”，其实是脚本根本没执行成功。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
- 设置
socket_timeout=0.1和socket_connect_timeout=0.1，超时就拒掉，别让请求卡住 - 捕获
redis.exceptions.TimeoutError和redis.exceptions.ConnectionError，统一按“限流通过”处理（宁可放过，不可误杀） -
rate和capacity建议从配置中心加载，不要硬编码；不同接口用不同key前缀，比如"rate_limit:api:v1:order:create" - 测试时用
redis.Redis(decode_responses=True)，避免字节串解析出错
上线前必须验证的三个边界场景
令牌桶最常翻车的地方不在主流程，而在时间跳变、冷启动、高并发竞争这几处。
- 系统时间回拨：如果 Redis 所在机器 NTP 同步出问题，
now小于last_fill，脚本里要math.max(0, now - last_fill)防负值 - 首次访问空桶：
HMGET返回nil，Lua 中tonumber(nil)是nil，必须显式 fallback（如上面脚本里的or now和or capacity） - 多实例部署时，确保所有服务连的是同一个 Redis（不是本地缓存或哨兵不同节点），否则桶状态不一致
真正难的不是写对脚本，而是让时间、连接、键命名、降级策略这四件事在不同环境里始终对齐。少一个，限流就变成“薛定谔的阀门”。
