Beego v2.x 必须用 beego.InsertFilter 结合 rate.Limiter 手动实现限流,因内置 LimitFilter 已移除、配置项无效;需在 beego.Run() 前注册,用 sync.Map 复用限流器,区分 BeforeRouter(动态接口)和 BeforeStatic(静态资源)阶段,集群下须引入 Redis 等外部协调组件。

beego.InsertFilter + rate.Limiter 是唯一可行方案
Beego v2.x 没有内置限流能力,beego.LimitFilter 在 v2.0+ 已被彻底移除,任何尝试调用它都会报 undefined: beego.LimitFilter。配置文件里写 LimitQPS = 10 完全无效——框架压根不读这个字段。必须手动用 golang.org/x/time/rate 结合 beego.InsertFilter 实现。
关键点:
- 注册必须在
beego.Run()之前,通常放在main()开头或init()里 - 推荐用
beego.BeforeRouter阶段,覆盖所有动态请求(但注意:不拦截/static/类路径) - 路径匹配要带前缀斜杠和星号,比如
"/api/*",漏掉*会导致子路径不触发 - 别用
c.Ctx.Request.RemoteAddr提取 IP——它含端口且易被代理污染;改用c.Ctx.Input.IP()
per-IP 令牌桶限流的并发安全写法
直接在过滤器里每次新建 rate.NewLimiter 会引发内存泄漏和 GC 压力。必须复用 *rate.Limiter 实例,并用 sync.Map 或带锁 map[string]*rate.Limiter 存储,否则高并发下 map panic 或计数错乱。
示例核心逻辑(非完整函数):
var (
ipLimiters = sync.Map{} // key: ip string, value: *rate.Limiter
limiterRPS = 10
limiterBurst = 20
)
func RateLimitFilter(c *context.Context) {
ip := c.Ctx.Input.IP()
limiter, ok := ipLimiters.Load(ip)
if !ok {
newLimiter := rate.NewLimiter(rate.Limit(limiterRPS), limiterBurst)
limiter, _ = ipLimiters.LoadOrStore(ip, newLimiter)
}
if !limiter.(*rate.Limiter).Allow() {
c.Ctx.ResponseWriter.WriteHeader(429)
c.Ctx.ResponseWriter.Header().Set("X-RateLimit-Remaining", "0")
c.StopRun() // 立即终止,不进 controller
return
}
}
注意:
-
sync.Map比加锁map更轻量,适合读多写少场景(IP 复用率高) -
limiterBurst不宜设为 1——令牌桶需要缓冲应对短时脉冲,否则正常重试都失败 - 不要在
Allow()后再做耗时操作(如查 DB),否则限流窗口实际被拉长
静态资源路径 /static/ 怎么限流?
/static/ 请求绕过 Beego 的整个路由系统,BeforeRouter 和 BeforeExec 过滤器完全不生效。想限制私有静态资源(如 /static/users/123/report.pdf),必须用 beego.BeforeStatic 阶段注册过滤器。
正确注册方式:
beego.InsertFilter("/static/users/", beego.BeforeStatic, authAndRateLimitForStatic)
限制要点:
-
BeforeStatic中c.Data为空,不能调c.TplName或c.Render() - 无法用
c.Input.Param()——参数未解析,得自己从c.Ctx.Request.URL.Path里截取 - 限流逻辑同上,但 IP 提取仍用
c.Ctx.Input.IP() - 若同时需限制
/api/和/static/private/,得写两套逻辑、分别注册
为什么集群部署下简单限流会失效?
单机 rate.Limiter 只统计本实例流量。4 台机器各限 100 QPS,实际集群吞吐可达 400 QPS 而不触发拒绝——这不是 bug,是设计使然。大促削峰必须引入外部协调组件。
可选升级路径:
- Redis + Lua 原生命令实现滑动窗口(
INCR + EXPIRE组合不安全,必须用EVAL原子执行) - 用
redis-go调用CL.THROTTLE(Redis 6.2+) - 接入 etcd 或 Consul 做分布式计数器(延迟略高,适合低频敏感接口)
- 消息队列削峰:把请求转成 MQ 消息,用 prefetch + manual ACK 控制消费速率
真正难的不是写限流代码,而是决定“对谁限、限多少、超限后怎么兜底”。IP 级限流挡不住代理池,用户 token 级又依赖鉴权前置完成——这些边界条件,比 Allow() 调用本身更消耗判断力。


















