首页 > Golang > Go教程

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

时间：2026-05-22 10:39:41 140浏览收藏

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

Golang 实现基于 Redis 的分布式限流器

为什么直接用 `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 

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