直接用redis.incr+expire限流会出错，因无法保证“检查-递增-设过期”原子性，导致并发请求突破阈值；必须用lua脚本将整套逻辑在redis端原子执行。
为什么直接用 redis.incr 做限流会出错
单次请求靠 redis.incr + 过期时间（expire）看似能实现计数限流，但存在竞态问题：两个并发请求同时读到当前值为 4，都判断“未超限”，接着各自 incr 到 5 —— 实际放行了 2 个，突破阈值。令牌桶还涉及“取令牌”和“更新剩余时间戳”两个动作，必须原子执行。
解决办法只有一个：把“检查令牌是否足够 + 消耗令牌 + 更新时间戳”这整套逻辑塞进 Redis 端执行。Lua 脚本在 Redis 中是原子的，且可访问 redis.call()，适合封装令牌桶状态机。
常见错误现象：
- QPS 稳定超配额，尤其在高并发压测时
- 同一用户在临界窗口反复被放行或拦截，行为不一致
- 使用 redis-py 的 pipeline 手动拼 get+setex，仍无法规避 race condition
令牌桶 Lua 脚本的关键参数与边界逻辑
脚本接收 4 个参数：KEYS[1]（桶 key）、ARGV[1]（最大容量）、ARGV[2]（每秒补充令牌数）、ARGV[3]（本次请求需消耗令牌数）。核心是根据上一次操作时间戳，算出应补多少新令牌，再判断是否够扣。
容易被忽略的点：
- 时间戳必须用 redis.call("time") 获取服务端时间，不能用客户端传入的时间（时钟不同步会导致桶“膨胀”或“枯竭”）
- 补令牌时要取 math.min，防止因长时间未访问导致令牌堆满后溢出
- 若剩余令牌不足，**不重置时间戳**，只返回 0；否则下次请求会误算“已过去很久”，一次性补满，造成突发流量穿透
简短示例（实际部署时建议预加载并用 script load + evalsha）：
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local rate = tonumber(ARGV[2])
local cost = tonumber(ARGV[3])
<p>local now = redis.call("time")[1] + redis.call("time")[2] / 1000000
local bucket = redis.call("hgetall", key)</p><p>local last_time = bucket[2] and tonumber(bucket[2]) or now
local tokens = bucket[4] and tonumber(bucket[4]) or capacity</p><p>local delta = math.max(0, now - last_time)
local new_tokens = math.min(capacity, tokens + delta * rate)</p><p>if new_tokens >= cost then
redis.call("hset", key, "last_time", now, "tokens", new_tokens - cost)
redis.call("expire", key, 3600)
return 1
else
redis.call("hset", key, "last_time", last_time, "tokens", tokens)
redis.call("expire", key, 3600)
return 0
end</p>
Python 客户端调用时如何避免连接与序列化开销
redis-py 默认每次 eval 都发完整脚本，网络+解析成本高。应预先用 script_load 得到 SHA1，后续全用 evalsha。同时注意：Redis 连接池要设合理 max_connections，否则限流本身成瓶颈。
实操建议：
- 在应用启动时加载脚本，缓存 sha 值，例如 self._lua_sha = self._redis.script_load(lua_script)
- 调用时用 self._redis.evalsha(self._lua_sha, 1, key, capacity, rate, cost)
- capacity 和 rate 应从配置中心或环境变量注入，避免硬编码；cost 可按接口粒度设（如上传大文件接口设为 5，普通 GET 设为 1）
- 不要用 json.dumps 存桶状态——Lua 脚本里 hset 直接存字段更轻量，也方便调试（hgetall your:key 可直读）
本地测试时为什么 Redis 响应快但线上延迟飙升
根本原因常是 Lua 脚本里调用了阻塞命令（如 redis.call("keys", "*")）或循环过深，导致 Redis 单线程卡住。令牌桶脚本虽短，但若误加日志（redis.log）、或对每个请求都 hgetall 再手动遍历字段，也会拖慢。
排查方法：
- 开启 Redis slowlog：执行 CONFIG SET slowlog-log-slower-than 0 + SLOWLOG GET 10
- 用 redis-cli --latency 看 PING 延迟，排除网络问题
- 把脚本中所有 redis.call 替换为模拟返回值，在 Python 里跑等效逻辑，确认计算本身不耗时
另一个隐蔽坑：没给桶 key 设置过期时间（expire），长期运行后 Redis 内存涨满，触发淘汰策略，反而增加响应抖动。脚本末尾那句 redis.call("expire", key, 3600) 不能省——它保证空闲桶自动清理，而非永久驻留。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
