老实说，

背景

项目使用 go‑zero 框架，Redis 部署为 Sentinel。通过 go‑redis 的 UniversalClient 接入。

给文章服务 API 加限流时我先试了 go‑zero 内置的 PeriodLimit发现限流失效。随后翻文档找到了 TokenLimiter——这是一种令牌桶算法。看起来靠谱，但结果一样不兼容。按理说，

两个官方限流器都走不通。最终基于令牌桶算法自行实现了一个兼容 Sentinel UniversalClient 的限流中间件。

这篇文章记录完整的踩坑过程、根因分析和最终方案。说起来，

一、第一次尝试：PeriodLimit

go‑zero 的 PeriodLimit 位于 core/limit/periodlimit.go主要原因：

func Take {
val。err := p.redis.Incr
if val == {
p.redis.Expire
}
return val <= p.quota, nil
}

固定窗口计数器: 用 INCR + EXPIRE 组合，在一个时间窗口内统计请求次数。

Pain Point #1: 依赖单节点客户端导致 Sentinel 模式失效

• *redis.Redis*。这个类型包装的是 *redis.Client不支持 Sentinel 模式
• INCR 和 EXPIRE 是两条独立命令，在 UniversalClient 的连接池下无法保证它们在同一连接上顺序执行，加上从节点的复制延迟，计数根本不准。说起来，

不可用。原因有二——类型不兼容 + 多命令原子性无法保证。

二、第二次尝试：TokenLimiter

PeriodLimit 不行，go-zero 还提供了 TokenLimiter。它用的是 Lua 脚本，算法也是令牌桶。看起来正是我需要的：

-- go-zero tokenscript.lualocal rate = tonumber
local capacity = tonumber
local now = tonumber
local requested = tonumber
local fill_time = capacity / rate
local ttl = math.floor
local last_tokens = tonumber)
if last_tokens == nil n
last_tokens = capacity
end
...
return allowed

Amazing!按理说，But on Go side we have:

type TokenLimiter struct {
store *redis.Redis // go-zero's Redis wrapper。underlying is *redis.Client
...
}
func NewTokenLimiter *TokenLimiter

Pain Point #2: 一样被限制在单节点客户端，Sentinel 无法使用！

• *redis.Redis* again wraps a single-node client.
• The algorithm is fine but client type binds it to non‑Sentinel usage.
• No fallback;still unusable in our setup.

算法对了但客户端类型绑死了还是不可用。按理说，

三、根因分析：为什么 go‑zero 的限流器都不兼容 Sentinel?

• Pain Point #3: 所有官方限流器依赖于 go‑zero 自己的 Redis 封装，而该封装只支持单节点客户端。我们的业务需要多主复制与读写分离，这导致所有内置限流器根本无法工作。

Pain Point #4: 尝试改造 go‑zero 源码或写适配层成本高且易失效；后可能 失效，

• Migrating or wrapping core logic requires deep knowledge and maintenance overhead.
• A single change could break with a new release of go‑zero.
• No guarantee that Sentinel fault tolerance will work correctly under our production load.

四、自行实现：基于 UniversalClient 的分布式令牌桶

为什么选令牌桶？🔍🏃‍♂️🚫📈📉🔒⚡️💬👨‍💻🛠️⏱️🧪🤖🐞🏁📦🛡️📊🤔🙌🔐✅🔥🔧✉️🥇🌐📈🎯❗️👀💥⚙️💡🔎💥🗜️🚨🚫✨🛤️🏹🗝️🔥🍀🥂🎓😎😤⚖️🤝🥳🍻❌✋✅👍🏆☑︎⏳👓⚙️➕🐲🌟🧩🌈🎉🎭⚡➡️😴😩➡︎🚫↔︎⇌➡︎🚶‍♀‍➡︎📢🙅‍♀✈❗🤬⚠︎🔥📣💯👑💸💰🔜👏⏰👌🏆🙌☑✔〰︎⭕✅◾➢⬇✕✖㊙⬇➙↪↕→←⬅↖↘↘↘↘↘��➡?，." We’ll implement it directly using universal client and Lua script to keep atomicity and support Sentinel mode.

---

为什么选令牌桶？

策略	优点	缺点	Pain Point 对应
固定窗口	简单实现	窗口边界突发可放过多请求	❌ “短暂高峰”导致误判
滑动窗口	平滑限流	每个请求存储时间戳。占用内存大	❌ “高并发”导致 OOM
令牌桶	允许突发+平滑	实现稍复杂，但在生产中最常见且成熟	✅ “可靠稳定”需求

go‑zero 的 TokenLimiter 已经采用此算法，只是绑定到单节点客户端。

---

Lua 脚本

lua -- keys : tokens_key -- keys : timestamp_key local tokens_key = KEYS local timestamp_key = KEYS local rate = tonumber -- 每秒补充速率 local capacity = tonumber -- 桶容量 local now = tonumber -- 当前时间 local requested = tonumber -- 本次请求消耗的令牌数 -- TTL 为 “满桶所需时间” 加一点缓冲，以防脚本被清除后重新加载。local fill_time = capacity / rate -- 秒 local ttl = math.floor + 5000 -- 惰性读取 & 补充 local last_tokens = redis.call if not last_tokens n last_tokens = capacity end local last_ts = redis.call if not last_ts n last_ts = now end -- 按时间差补充新的 token local delta_ms = math.max local delta_sec = delta_ms / 1000 local new_tokens = math.min(capacity,tonumber + delta_sec * rate) -- 判断是否满足请求并扣减 token 数量 if new_tokens>= requested n local left = new_tokens - requested redis.call redis.call return {true,left} -- {允许，可返回剩余 token 数量} else -- 不满足请求时返回建议等待秒数 local wait_sec = math.ceil / rate) return {false,wait_sec} -- {拒绝，建议等待秒数} end 与官方 `tokenscript.lua` 对比：

区别点	官方版	自研版
时间精度	now.Unix	now.UnixMilli
返回值结构	bool	{allowed bool。waitSec int} 可直接给前端 Retry-After
客户端类型	*redis.Redis 单节点包装	*redis.UniversalClient* 支持 Sentinel

---

Go 实现主要代码

go package ratelimit import ( "context" "fmt" "strings"

"github.com/go-redis/redis/v8"

) const luaScript string = ` ... // 上面完整脚本粘贴即可省略以节省篇幅示例... ` // RateLimitMiddleware 中间件结构体 type RateLimitMiddleware struct { Redis redis.UniversalClient // 支持 sentinel/failover 等模式 ★关键差异★ Rate float64 // 每秒补充速率，如每秒10个token => Rate=10.0 Burst int // 桶容量，例如短时可突发20个请求 => Burst=20 scriptSHA string // SCRIPT LOAD 后得到的 SHA 值，用于 EVALSHA 调整 } // NewRateLimitMiddleware 初始化并预加载脚本到 Redis。func NewRateLimitMiddleware(ctx context.Context,rate float64,burst int。rc redis.UniversalClient) {

shaResult := rc.ScriptLoad.Result
if shaResult!= nil && strings.HasPrefix,"ERR") {
return nil,fmt.Errorf)
}
return &RateLimitMiddleware{
说到Redis。rc,Rate: rate,Burst: burst,scriptSHA: shaResult.Result,},nil

} // evalScript 执行脚本；优先 EVALSHA，遇到 NOSCRIPT 时回退 EVAL。怎么说呢，func evalScript( ctx context.Context,keys string,args ...interface{}。) {

resSlice := interface{}{}

if rm.scriptSHA!老实说，= "" { result,err := rm.Redis.EvalSha(ctx,rm.scriptSHA,keys。 args...).Result if err == nil { resSlice // no compile error?just ignore，return result.,nil // simplified pseudo-code for brevity in article. } if!strings.HasPrefix,"NOSCRIPT") { return nil。err // 非 NOSCRIPT 错误直接返回。} rm.scriptSHA="" // 清空 SHA，让下一次强制重新加载。老实说，} // NOSCRIPT 或首次调用回退 Eval result := rm.Redis.Eval.Result return result.,nil // same pseudo-code. } **解释**的观点是。
• EvalSha 调整将 Lua 脚本一次性上传到 Redis 并缓存 SHA，后续只发送哈希即可避免网络负载。若服务器内存压力过大导致脚本被驱逐。则会收到 NOSCRIPT，需要再一次加载。
• UNIVERSAL 客户端所有写操作都自动路由到 Master 节点，无需担心从节点复制延迟问题。整个 Lua 脚本在 Master 上原子执行，不存在跨实例竞态。

---

中间件集成方式

go func NewArticleHandler http.HandlerFunc { return func{ 至于ctx，=r.Context

 userID := extractUserIDFromJWT)
if userID==""{
w.WriteHeader;return，}
keyTokens := fmt.Sprintf
keyTS := fmt.Sprintf
从res,_来看，=rm.evalScript(ctx。.string{keyTokens,keyTS},rm.Rate,float64,time.Now.UnixMilli,int64)
allowed,_:=res.;if，allowed{
waitSec,_:=res.;w.Header.Set)
w.WriteHeader;w.Write(byte(`{"msg":"rate limit exceeded","retry_after":`+
fmt.Sprintf))
return;}
/* 真正业务逻辑 */
...
w.WriteHeader;w.Write)，return;}

}

---

Fail‑Closed 与 Fail‑Open 对比 🚫❓✅

Pain Point#5 & 风险评估	User-facing 行为	Implementation Detail
#sentinel failover loss & latency spikes	Fail-Close	Fail-Close.

#实际使用场景说明 👉 写文章接口必须保持数据一致性，否则可能造成“未提交成功却已计费”的情况！故选择 Fail-Close。✅ 如果你想要更宽松，可以改成 Fail-Open。并使用x/time/rate.LocalLimiter.但记住多实例环境下阈值会叠加！🚨🚨 🚀 💣 ⛔ 🎯 ⚠ ✋ 🔥 🏁 🧱 🛠 📝 📊 🔎 🔬 👷‍♂‍ 👷‍♀‍ 👩‍💻 👨‍💻 🎓 📚 📋 📦 ⚖ ⚒ 💼 💸 🔧 🤝 🧪 🌟 ✨ 🎉 😬 😵 🙃 😇 🍿 🍽 🍲 🌍 🌎 🌏 🌐 ➡ 🚀 ➡ ⭐ 🎯 ✔ ☑ ❗ 🔴 🔵 🟢 🟡 ⚙ ⏱ ⏲ ♿ 💬 📞 📺 📻 🎤 🎧 🎹 🎸 📸 🎬 ⛵ ⛱ ☀ ☁ ☂ ☃ ❄ ⛄ 💦 🌊 🌴 🍃 🌲 🌳 🍂 🍁 🍀 ⚡ ☢ ☣ 🔥 ❤️ 😭 😂 🤣 😭 😊 🙂 🙃 😇 🙏 👀 👋 👍 ✌ ✝ ✿ ✈ 🎵 💐 🙅 🙆 🙇 🙈 🙉 🙊 ';

​

---

Key Design & TTL 设置 ⚙️⌛🔒

sql /* 使用者级别限制 / req_limit::tokens:;/ 剩余 token 数 / req_limit::ts:;/ 上次刷新时间戳 */

/* TTL 示例 / TTL ≈ ceil1000 + buffer_seconds;

TTL 保证空闲使用者不会占用键空间。根据默认配置 ： TTL ≈ *1000 + 5s ≈ ~35s。老实说，

---

配置文件示例 YAML ✅⚙️📄

yaml # config.yaml 示例片段…RateLimits: ArticleCreate: Rate : 10 # 每秒最多允许10个创建请求 Burst :30 # 短时最多可突发30个请求

若超过阈值。将收到 响应，并带有 标头提示等待秒数。

---

六、 🚀🏁✔️✨🔥🐾🎉🌟🥇🙌🏼📝🤓💡🔮🍾♾🌐🎯📦🤝🙏❤️😊🥺😭🤣😤😴👍👌👩‍💻👨‍💻🚦🚥⭐⌛⌚⏰⏳⌨👾📱📞☎☎☎📞☎☎☎☎☎☕🍺🍻🍷🍸🍹🥂酒吧*

Pain Point / Root Cause ↓	User Impact ↑	Solution Details ↑
① 固定窗口 → INCR+EXPIRE 两条命令无原子性 → 随机错误率 ② TokenLimiter → 单节点包装 → 无法使用 Sentinel ③ 全局改造成本高且易失效	• 界面卡顿 • 请求被误判拒绝 • 高并发下出现“漏计”“错算”等错误	• 使用 UniversalClient • Lua 脚本实现惰性令牌桶 • EvalSha+NOSCRIPT 回退 • 毫秒级精度 & 建议等待返回 ...

主要收获

1. 算法没问题 – 两者都是成熟的固定窗口或惰性令牌桶。但被框架内部包装所限制，
2. 原因在于框架对 Redis 的封装 – 默认仅支持单节点 *redis.Client；不能直接注入 Sentinels.
3. 方法是绕开框架层 – 用标准 *go-redis.UniversalClient* 编写自己的中间件，并利用 Lua 原子脚本确保安全、兼容多主复制。
4. 额外细节调整 – EvalSha 缓存、NOSCRIPT 回退、毫秒级时间精度、Fail‐Closed 与 Retry‐After 响应等，使程序更健壮、更可观测。

这样，你就能在已有项目中快速替换掉失效的官方限流器。而不会牺牲性能或稳定性，同时保持对 Sentinel 集群的完全支持。祝你部署顺利 🚀✨