在goframe框架中捕获全局异常的核心做法是注册自定义的中间件,并在其中使用 recover() 函数拦截 panic。当程序发生未处理的错误时,中间件会捕获该 panic,记录日志并返回统一的 json 格式响应,从而避免服务崩溃或暴露敏感堆栈信息。

如何定义并注册全局异常处理中间件
通过实现 ghttp.Middleware 类型的函数来定义中间件,利用闭包捕获上下文并调用 recover()。注册时将其挂载到全局路由组或特定路由上,确保所有请求都经过此逻辑。

package main
import (
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)
func main() {
s := g.Server()
// 注册全局中间件
s.Use(MiddlewareGlobalError)
s.Group("/api", func(group *ghttp.RouterGroup) {
group.Middleware(ghttp.MiddlewareHandlerResponse)
group.GET("/test", TestHandler)
})
s.SetPort(8199)
s.Run()
}
func MiddlewareGlobalError(r *ghttp.Request) {
defer func() {
if err := recover(); err != nil {
g.Log().Errorf(r.Context(), "Panic recovered: %v", err)
r.Response.WriteJson(g.Map{
"code": 500,
"message": "Internal Server Error",
"data": nil,
})
r.Exit()
}
}()
r.Middleware.Next()
}
func TestHandler(r *ghttp.Request) {
panic("人为触发的测试异常")
}
上述代码展示了完整的中间件定义与注册流程。运行后访问 /api/test,服务端将捕获 panic 并返回标准 JSON 响应,而非直接抛出堆栈跟踪。
如何处理非 Panic 类的业务异常
对于不触发 panic 的业务错误(如参数校验失败、数据库约束冲突),应结合 GoFrame 的 ghttp.MiddlewareHandlerResponse 中间件,手动构造错误响应对象。建议在控制器中统一返回 ghttp.H 结构体,由 HandlerResponse 中间件自动封装为 JSON。

package main
import (
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)
func main() {
s := g.Server()
s.Use(MiddlewareGlobalError)
s.Group("/api", func(group *ghttp.RouterGroup) {
group.Middleware(ghttp.MiddlewareHandlerResponse)
group.POST("/user", CreateUserHandler)
})
s.SetPort(8199)
s.Run()
}
func CreateUserHandler(r *ghttp.Request) {
name := r.Get("name").String()
if name == "" {
// 手动返回错误,由 HandlerResponse 包装
r.Response.WriteJsonExit(g.Map{
"code": 400,
"message": "Name is required",
"data": nil,
}, 200)
return
}
r.Response.WriteJson(g.Map{
"code": 200,
"message": "Success",
"data": g.Map{"id": 1},
})
}
该示例演示了如何在非 panic 场景下主动返回错误。当用户未提供 name 参数时,控制器直接写入 JSON 响应并退出,HandlerResponse 中间件不会覆盖已写出的内容,从而实现灵活的业务错误控制。
当 panic 消息包含敏感信息时如何脱敏
若 panic 消息中包含数据库连接串、密钥等敏感内容,需在中间件的 defer 块中对 err 进行类型断言和字符串替换,或使用白名单机制过滤特定关键字。建议将原始错误仅记录在服务器日志中,而向客户端返回通用提示。
package main
import (
"strings"
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)
func MiddlewareGlobalErrorSensitive(r *ghttp.Request) {
defer func() {
if err := recover(); err != nil {
errMsg := "Internal Server Error"
if msg, ok := err.(string); ok {
// 简单脱敏:替换敏感关键词
sensitiveWords := []string{"password", "secret", "token"}
for _, word := range sensitiveWords {
if strings.Contains(strings.ToLower(msg), word) {
errMsg = "Operation failed due to security policy"
break
}
}
// 记录完整错误到日志
g.Log().Errorf(r.Context(), "Raw panic: %v", msg)
}
r.Response.WriteJson(g.Map{
"code": 500,
"message": errMsg,
"data": nil,
})
r.Exit()
}
}()
r.Middleware.Next()
}
func TestSensitiveHandler(r *ghttp.Request) {
panic("Database connection failed: password=123456")
}
在此增强版中间件中,如果 panic 消息包含 "password" 等敏感词,客户端收到的将是通用错误提示,而完整堆栈仅保留在服务端日志中,有效防止信息泄露。


















