beego.InsertFilter() 是唯一注册入口,必须在 beego.Run() 前调用;路径匹配需精确(如 "/api/" 末尾斜杠不可省),全局用 "/*",静态资源需单独用 BeforeStatic;中间件函数须为 func(*context.Context),必须显式调用 ctx.Next() 且仅一次,校验失败用 ctx.Abort(statusCode, message) 并手动设置 Content-Type。

beego.InsertFilter() 是唯一注册入口,必须在 beego.Run() 前调用
Beego 没有 Use() 或 UseMiddleware(),所有校验逻辑都得走 beego.InsertFilter()。它不是“挂载”,而是“插入过滤链”——注册晚了(比如写在某个 Controller 里),等于没写。
常见错误现象:中间件函数写了,日志也打了,但请求完全不触发。大概率是注册位置错了,检查是否放在 main() 开头或 init() 里,且在 beego.Run() 之前。
-
beego.InsertFilter("/api/", beego.BeforeRouter, ValidateFilter)—— 只对/api/开头路径生效,结尾斜杠不能省,否则可能误匹配/apixxx - 若要全局校验,用
beego.InsertFilter("/*", beego.BeforeRouter, ValidateFilter),但注意:它不拦截/static/路径 - 静态资源校验必须单独注册:
beego.InsertFilter("/static/private/", beego.BeforeStatic, StaticValidateFilter)
校验中间件函数签名固定为 func(*context.Context),且必须显式调用 ctx.Next()
Beego 的过滤器不是回调,是同步控制流节点。不调 ctx.Next(),后续所有过滤器和 Controller 都不会执行;用 return 代替 ctx.Next() 是常见坑点。
典型结构如下:
func ValidateFilter(ctx *context.Context) {
path := ctx.Request.URL.Path
method := ctx.Request.Method
// 拒绝非法方法
if method == "POST" || method == "PUT" || method == "DELETE" {
if err := ctx.Input.ParseForm(); err != nil {
ctx.Abort(400, "bad form")
return
}
}
// 校验必要字段(例如 token)
authHeader := ctx.Request.Header.Get("Authorization")
if !strings.HasPrefix(authHeader, "Bearer ") {
ctx.Abort(401, "missing token")
return
}
ctx.Next() // 必须放最后,且只调一次
}
- 不要
defer ctx.Next()—— 它不是 deferable 函数,会破坏执行顺序 -
ctx.Abort()是终止标准方式,不是http.Error()或手动写 status - 在
BeforeStatic阶段,ctx.Input.Param()不可用,参数得用正则从path里手动提取
路径与方法组合校验要前置判断,避免干扰 Controller 状态
想只校验 POST /api/login?别在中间件里写 if path == "/api/login" && method == "POST" 后再放行——这样虽能跑通,但 ctx.Next() 已部分执行,可能提前触发 session 初始化或 body 读取,导致 Controller 再次读 body 时返回空。
正确做法是:用 InsertFilter() 的路径前缀 + 在中间件开头快速短路:
- 注册:
beego.InsertFilter("/api/login", beego.BeforeRouter, LoginValidate) - 函数内第一句:
if ctx.Request.Method != "POST" { ctx.Abort(405, "method not allowed"); return } - 后续再做 token 解析、密码校验等,确保只在目标方法下执行
- 若需校验 query 参数(如
?v=2),用ctx.Input.Query("v"),它比手动解析URL.RawQuery更安全
校验失败后不要留空响应,Abort 要带明确 statusCode 和 message
ctx.Abort() 的第二个参数会作为响应体内容(默认是纯文本),前端或网关依赖这个 message 做错误分类。只传 401 不传 message,调试时很难定位是 token 过期还是格式错误。
常见 statusCode 映射:
-
400:参数缺失、JSON 解析失败、ParseForm()错误 -
401:token 不存在、签名无效、过期(JWT 场景下建议区分 401 vs 403) -
403:token 有效但权限不足(如访问 /admin 但角色是 user) -
429:IP 或用户级限流触发(需配合自定义计数器,Beego 不内置)
容易被忽略的一点:Beego 默认不设置 Content-Type: application/json,如果前端 expect JSON,得自己加:ctx.ResponseWriter.Header().Set("Content-Type", "application/json"),再调 ctx.Abort()。否则可能被当成 HTML 或 text/plain 处理。











