redis-cell 是 Go 分布式限流最省心的选择，因其 CL.THROTTLE 命令将令牌桶逻辑封装在 Redis 服务端，Go 客户端只需调用一条命令并解析五元组响应，无需处理时间窗口、并发竞争或本地状态。
为什么 redis-cell 是 Go 分布式限流最省心的选择
因为它的 CL.THROTTLE 命令把令牌桶逻辑全封装在 Redis 服务端，Go 客户端只需发一条命令、收一个五元组响应，不用自己算时间窗口、不操心并发竞争、也不用维护本地状态。比起手撸 Lua 脚本或用 INCR+EXPIRE 组合，出错率低得多，且天然支持突发流量平滑放行。
常见错误现象：用 SETNX + 过期时间模拟计数器，结果在秒级窗口内被多个协程同时写入，导致超限请求漏放；或用本地内存限流（如 golang.org/x/time/rate），一上多实例就完全失效。
-
redis-cell模块必须提前加载到 Redis 实例中（redis-server --loadmodule /path/to/redis-cell.so），否则调用CL.THROTTLE会报ERR unknown command - Go 客户端推荐用
github.com/go-redis/redis/v8，它原生支持自定义命令，无需 hack 连接对象 - 不要试图用
Eval发送等效 Lua 脚本替代——redis-cell的 C 实现做了原子性与性能优化，Lua 版本无法复现其精度和吞吐
Go 调用 CL.THROTTLE 的最小可行代码
核心是构造五个参数：key、最大突发容量（burst）、单位时间内允许请求数（rate）、单位时间秒数（period）、当前请求量（通常为 1）。返回值是长度为 5 的整数数组，顺序为：[allowed_tokens, total_allowed, remaining_tokens, reset_time_in_seconds, retry_after]。
使用场景：HTTP 中间件里对用户 ID 或 API 路径做限流，比如每秒最多 10 次，允许最多 3 次突发。
立即学习“go语言免费学习笔记（深入）”；
ctx := context.Background()
cmd := rdb.Do(ctx, "CL.THROTTLE", "rate:uid:123", 10, 10, 1, 1)
vals, err := cmd.IntSlice()
if err != nil {
// 注意：redis-cell 返回的不是标准 RESP 错误，而是带前缀的字符串错误，比如 "ERR invalid argument"
if strings.HasPrefix(err.Error(), "ERR") {
http.Error(w, "rate limit config error", http.StatusInternalServerError)
return
}
http.Error(w, "redis unavailable", http.StatusServiceUnavailable)
return
}
if len(vals) != 5 {
http.Error(w, "unexpected redis-cell response", http.StatusInternalServerError)
return
}
if vals[0] == 0 { // allowed_tokens == 0 表示被拒绝
w.Header().Set("Retry-After", strconv.FormatInt(int64(vals[4]), 10))
http.Error(w, "too many requests", http.StatusTooManyRequests)
return
}
参数差异：period 单位是秒，但 redis-cell 内部用毫秒计算，所以设成 1 就是 1 秒窗口；burst 必须 ≥ rate，否则初始化失败报 ERR invalid burst value。
CL.THROTTLE 返回值各字段的实际含义和坑点
很多人只看第一个值判断是否放行，忽略其余字段导致重试逻辑出错或监控失真。
-
allowed_tokens：本次请求是否被允许（1=是，0=否）——这是唯一可用于 if 判断的字段 -
total_allowed：该 key 当前窗口内**总共被允许的请求数**（含本次），等于burst，一般不用 -
remaining_tokens：剩余可用令牌数，可用于暴露给前端或打日志，但注意它可能为负（表示已超限，负值绝对值 = 超限次数） -
reset_time_in_seconds：窗口重置时间戳（Unix 秒），不是相对时间，需和服务端时间对齐，否则Retry-After计算偏移 -
retry_after：若被拒绝，此字段是**距离下次允许请求还需等待的秒数**（浮点，单位秒），直接塞给Retry-After头即可，别四舍五入
容易踩的坑：把 reset_time_in_seconds 当作 TTL 用，或者用 remaining_tokens 做告警阈值却没处理负数，结果告警一直狂轰。
生产环境必须检查的三件事
限流一旦失效，故障就是雪崩级的，不能只测通路。
- 确认 Redis 版本 ≥ 4.0 且
redis-cell.so加载成功：连上 Redis 执行MODULE LIST，输出里要有name:redis-cell - 压测时观察
redis-cell的 CPU 占用——它在服务端做浮点运算，高 QPS 下可能比普通命令吃资源，必要时升级 Redis 实例规格 - Key 设计要带业务维度隔离，比如
rate:api:/user/profile:uid_123，避免不同接口或用户互相挤占令牌；别用纯时间戳或随机字符串当 key，会导致冷 key 扫描无效
最易被忽略的是时钟漂移：如果 Redis 服务器和 Go 应用服务器时间差超过 1 秒，reset_time_in_seconds 和 retry_after 就会不准。建议所有节点统一 NTP 校时，别依赖系统默认配置。
