ratelimitx —— 进程内限流原语(令牌桶 / 漏桶 / per-key 桶)
限流有两种做法:跨副本一致的(Redis 滑动窗口),和单进程内的(纯内存桶)。 ratelimitx 是后者 —— 极快、零依赖,但只在一个进程内有效。
⚠️ Windows 上没有官方 Redis —— 要跨副本一致的限流(走 kvstore)就得先有 Redis: 用 Memurai(Redis 协议兼容,装成 Windows 服务, 默认
127.0.0.1:6379、无密码)。Developer 版仅供开发/测试,不许上生产。 详见 快速开始。
功能
ratelimitx 提供三种限流算法,覆盖三类场景:
| 类型 | 构造 | 语义 | 适合 |
|---|---|---|---|
令牌桶 TokenBucket |
NewTokenBucket(capacity, ratePerSec) |
桶里攒着令牌就能一次放行一批,之后匀速补 | 突发可放过 + 平均速率控制 |
漏桶 LeakyBucket |
NewLeakyBucket(capacity, ratePerSec) |
队列水位满就拒,没有"攒令牌" | 削峰填谷 / 并发上限 |
per-key 桶池 KeyedBucket |
NewKeyedBucket(cap, rate, maxKeys, ttl) |
每个 key 一个桶,LRU 上限 + 空闲 TTL | per-user / per-IP / per-API-key |
三者都是纯内存、无外部依赖、线程安全:
- 单桶用
atomic.Int64+lastRefill做无锁算法(CAS 重试) KeyedBucket持 LRU +sync.Mutex
它不解决什么
- 不跨副本。多副本部署时每个副本各限各的(见「注意事项」第 1 条)
- 不排队、不阻塞 —— 拒绝时返
false,由调用方决定返 429 还是排队 - 不做滑动窗口(那是 kvstore 的
Window) - 不做分布式锁
配置
yaml 侧
该包无 yaml 配置。
⚠️ yaml 里那个 ratelimit: 块不是给这个包的:
ratelimit:
global_qps: 1000
per_ip_qps: 50
login_fail_per_hour: 10
这三个键在 config.RateLimitConfig 里定义了,但全仓零消费方 ——
grep "GlobalQPS\|PerIPQPS\|LoginFailPerHour" 只命中定义行。真正的限流参数是
internal/api/router/router.go 里硬编码的:
middleware.RateLimit("login", 10, time.Minute, "ip")
而 middleware.RateLimit 走的是 kvstore 的跨副本滑动窗口,不是 ratelimitx。
⇒ 改 yaml 那三个键不会有任何效果。
代码侧
所有参数都在构造函数上,没有配置项:
| 参数 | 含义 | 非法值的兜底 |
|---|---|---|
capacity / cap |
桶容量(最大突发) | < 1 → 1 |
ratePerSec / rate |
每秒补充 / 漏出速率 | < 1 → 1 |
maxKeys |
LRU 上限 | < 1 → 1000 |
ttl |
单桶空闲 TTL | ≤ 0 → 10 分钟 |
使用方法
令牌桶:允许突发
tb := ratelimitx.NewTokenBucket(5, 2) // 容量 5,每秒补 2
if !tb.Allow() {
return errTooManyRequests
}
fmt.Println(tb.Available(), tb.Stats())
AllowN(n) 一次要多个 token(批量导入按条数扣);桶里不够就整笔拒绝。
漏桶:严格平滑
lb := ratelimitx.NewLeakyBucket(5, 2) // 队列上限 5,每秒漏 2
if !lb.Allow() {
return errOverflow
}
fmt.Println(lb.Level(), lb.Stats())
per-key 桶池
kb := ratelimitx.NewKeyedBucket(2, 1, 1000, 10*time.Minute)
defer kb.Stop() // 必须 Stop,见「注意事项」
if !kb.Allow("IP-A") { /* 限流 */ }
if !kb.Allow("IP-B") { /* 另一个 key,互不影响 */ }
fmt.Println(kb.Len()) // 当前 key 数
fmt.Println(kb.Get("IP-A").Stats()) // 拿桶看状态
完整可运行示例见 examples/ratelimitx/main.go。
注意事项
- ⚠️ 根本局限:进程内。多副本部署时每个副本各限各的,实际阈值 = 配额 × 副本数。
配 50 QPS、部署 4 个副本,集群实际能过 200 QPS。
⇒ 真正跨副本的限流走 kvstore(Redis ZSET 滑动窗口)——
middleware.RateLimit(scene, max, window, dim), 那是另一个包的事,见 kvstore。 - ⚠️ 包注释里的
ratelimitx.InitMetrics(metricsx.Registry())不存在。 全仓只有cachex.InitMetrics和cronx.InitMetrics。照抄那行编译不过。 指标要自己从Stats()/BucketStats/LeakyStats里取。 - ⚠️
KeyedBucket的热路径也有锁。结构体注释写着"已有桶访问无锁",但Get一进来就k.mu.Lock(),而Allow正是走Get⇒ 每次 Allow 一次全局 互斥。注释与实现不符,别照着注释估并发能力。 - ⚠️ 漏桶不排队、不阻塞。
LeakyBucket.Allow()只判断"队列是否满", 没有取队列的 API —— 所谓"严格平滑"得由调用方自己按rate的节奏取走东西 才成立。实际用起来它就是"并发数上限"。 - ⚠️
NewKeyedBucket会起一个后台 goroutine(每分钟扫一次清过期桶)。 不调Stop()就泄漏 —— 反复构造KeyedBucket的代码会一路漏 goroutine。 - ⚠️ 参数 < 1 会被兜底成 1,不是"关闭"。
NewTokenBucket(0, 0)得到的是 "容量 1、每秒 1 个",不是不限流。 - ⚠️ 令牌桶初始是满桶。刚构造出来能一次性放行
capacity个请求 (tokens初始化成capacity * 1e6)。 - ⚠️
AllowN不做部分放行。桶里只剩 2 个、要 3 个 ⇒ 整个拒,不是放 2 个。 - ⚠️
Available()/Level()会改状态。它们先refill/drain再读, 不是纯查询 —— 拿它当探针会消耗桶的额度。 - ⚠️
Stats().Allowed对AllowN记的是 token 数不是请求数(allowed.Add(int64(n)))。 - ⚠️ 零生产调用方。
internal/guard的可达性扫描把它列为"库类原语 + 单测齐全, 但零生产调用方;它们是故意留着的(接线点在业务线)"。 ⇒ 用它之前先确认自己要接的是"进程内限流"而不是"跨副本限流"。