Golang Redis 分布式限流器实现方法

本文深入剖析了在 Go 语言中基于 Redis 实现分布式限流器的关键陷阱与最佳实践，直击“INCR + EXPIRE 非原子操作导致 key 永久残留、引发全局误限流”这一高并发下必然发生的严重问题，并给出以 Lua 脚本封装计数与过期逻辑的原子化解决方案；通过 redis.NewScript 注册可复用、易维护的限流脚本，结合 KEYS/ARGV 的正确使用规范、类型转换注意事项及返回值安全处理，手把手教你构建健壮、高效、生产可用的 Go 分布式限流器。

为什么直接用 INCR + EXPIRE 会出错

Redis 原生命令不是原子的，INCR 和 EXPIRE 分开调用时，若服务在 INCR 后、EXPIRE 前崩溃，key 就会永久存在，导致后续所有请求被误限流。这不是偶发问题，而是高并发下必然发生的 race condition。

正确做法是用 Lua 脚本把计数和过期逻辑打包成一个原子操作。Go 客户端（如 github.com/go-redis/redis/v9）支持 Eval，但要注意脚本里不能依赖外部状态，且 key 数量必须提前声明（KEYS[1]）。

常见错误写法：

redis.Incr(ctx, "rate:uid:123").Val() // 没设过期
redis.Expire(ctx, "rate:uid:123", time.Minute).Val() // 非原子

推荐脚本结构（带 TTL 自动重置）：

local current = redis.call("INCR", KEYS[1])
if current == 1 then
    redis.call("EXPIRE", KEYS[1], tonumber(ARGV[1]))
end
return current

如何用 redis.NewScript 封装限流逻辑

硬编码 Lua 脚本容易出错且难维护，应该用 redis.NewScript 提前注册，再统一调用。它能自动校验 key 数量、缓存 SHA1、复用连接上下文。

关键点：

• KEYS 只能传 key 名，不能传完整表达式（比如不能传 "rate:" + uid）——拼接必须在 Go 层做
• ARGV 用于传动态参数，比如窗口秒数、最大请求数，但注意 Redis 中 ARGV 全是字符串，数值需用 tonumber() 转换
• 脚本返回值是 int64 或 nil，别直接当布尔判断；要检查是否超限，得和阈值比对

示例封装：

var limitScript = redis.NewScript(`
local current = redis.call("INCR", KEYS[1])
if current == 1 then
    redis.call("EXPIRE", KEYS[1], tonumber(ARGV[1]))
end
return current
`)

func (r *RedisLimiter) Allow(ctx context.Context, key string, limit int64, windowSec int64) (bool, error) {
    n, err := limitScript.Run(ctx, r.client, []string{key}, windowSec).Int64()
    if err != nil {
        return false, err
    }
    return n 

EVALSHA 失败后为何要 fallback 到 EVAL
首次运行脚本时，Redis 还没缓存 SHA1，EVALSHA 会返回 "NOSCRIPT No matching script" 错误。Go-Redis 的 NewScript 默认已处理这个 fallback，但如果你手动调用 client.EvalSha，就必须自己捕获该错误并重试 Eval。
不处理 fallback 的后果：第一次限流永远失败，后续才正常——线上压测时极易被忽略，因为本地调试往往已预热过脚本。
需要关注的细节：

• 脚本内容变更后，SHA1 改变，旧缓存失效，同样触发 fallback
• 集群模式下，脚本必须在所有分片节点都存在，否则某些 key 路由到未加载脚本的节点也会报 NOSCRIPT
• 生产环境建议在服务启动时主动 SCRIPT LOAD 一次，避免首请求延迟

用户维度限流的 key 设计容易踩哪些坑

限流 key 看似简单，但设计不当会导致共享冲突或爆炸性增长。例如用 "rate:" + userID 看起来合理，但如果 userID 是数据库自增 ID，就可能被恶意枚举撞出大量 key，打爆 Redis 内存。

更安全的做法：

• 加固定前缀 + 哈希后缀："rate:u:" + md5(userID)[:8]，防遍历
• 按时间窗口切分 key："rate:u:123:2024052014"（小时级），避免单 key 过热，也方便 TTL 精确控制
• 不要把请求路径、IP、User-Agent 全塞进 key——字段越多，基数越大，内存和淘汰压力越不可控
• 如果需多层限流（如用户+接口），用分层 key："rate:u:123" 和 "rate:i:/api/pay" 分开计数，别揉成一个

另外，Redis 内存不是无限的，maxmemory-policy 推荐设为 allkeys-lru，避免限流 key 把业务数据挤出内存。

终于介绍完啦！小伙伴们，这篇关于《Golang Redis 分布式限流器实现方法》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布Golang相关知识，快来关注吧！