在 goframe 框架中,统一错误处理的核心做法是结合 ghttp.request 的 seterrorfunc 方法注册全局异常处理器,并在业务逻辑中使用 gerror.new() 或 errors.is() 进行标准化包装。这样当程序发生 panic 或返回非 nil 错误时,框架会自动拦截并调用注册的函数,将结构化信息(如错误码、堆栈)序列化为 json 响应返回给客户端,避免直接暴露原始堆栈信息。

如何配置全局异常捕获中间件?
要实现全局捕获,需要在路由初始化阶段通过 Server.SetErrorFunc 设置回调函数。该函数接收请求对象和错误对象作为参数,开发者可以在其中判断错误类型,提取自定义的错误码,并构造统一的 JSON 结构返回。对于未捕获的 panic,GoFrame 默认会触发此流程,确保服务不崩溃且返回友好提示。

package main
import (
"context"
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
"github.com/gogf/gf/v2/errors/gcode"
"github.com/gogf/gf/v2/errors/gerror"
)
func main() {
s := g.Server()
// 注册全局错误处理函数
s.SetErrorFunc(func(ctx context.Context, r *ghttp.Request, err error) {
var resCode int32 = 500
var errMsg string
// 尝试从错误中提取自定义 Code
if gerror.Code(err).Code() != 0 {
resCode = gerror.Code(err).Code()
errMsg = gerror.Msg(err)
} else {
errMsg = "Internal Server Error"
}
// 输出日志以便排查
g.Log().Error(ctx, err)
// 返回统一格式的 JSON
r.Response.WriteJson(g.Map{
"code": resCode,
"message": errMsg,
"data": nil,
})
r.Exit()
})
s.Group("/api", func(group *ghttp.RouterGroup) {
group.Middleware(ghttp.MiddlewareHandlerResponse)
group.POST("/user", HandleUserCreate)
})
s.Run()
}
func HandleUserCreate(ctx context.Context, r *ghttp.Request) {
// 模拟业务逻辑抛出错误
err := errors.New("user not found")
if err != nil {
// 使用 gerror 包装错误,携带自定义 Code
customErr := gerror.NewCode(gcode.CodeInvalidParam, "invalid user id")
r.Response.Status = 400
// 由于设置了 SetErrorFunc,这里直接 panic 或 return err 均可被捕获
// 但通常建议直接返回 err,由框架流转至 ErrorHandler
panic(customErr)
}
}
上述代码展示了完整的配置流程。关键点在于 SetErrorFunc 必须在 Server.Run() 之前调用。在业务层,我们使用 gerror.NewCode 创建带有特定错误码的错误对象。当业务逻辑中触发 panic 或返回错误时,框架的全局机制会接管控制权,执行 SetErrorFunc 中的逻辑,最终通过 r.Response.WriteJson 发送响应。注意 ghttp.MiddlewareHandlerResponse 中间件通常用于自动处理成功响应,但在有全局错误处理时,它不会干扰错误流的捕获。
如何区分业务错误与系统异常?
在实际开发中,需要区分预期的业务错误(如参数校验失败、用户不存在)和非预期的系统异常(如数据库连接断开、空指针)。GoFrame 提供了 gerror.Code() 来检查错误是否包含自定义代码。如果错误是由 gerror.NewCode 创建的,则可以通过 gcode.CodeXXX 常量识别具体业务场景;如果是原生 Go 错误或第三方库错误,其 Code 通常为 0,此时应归类为系统异常。

package main
import (
"context"
"fmt"
"github.com/gogf/gf/v2/errors/gcode"
"github.com/gogf/gf/v2/errors/gerror"
"github.com/gogf/gf/v2/frame/g"
"net/http"
)
// 定义业务错误码
var (
ErrUserNotFound = gerror.NewCode(gcode.CodeNotFound, "user not found")
ErrDBDown = fmt.Errorf("database connection lost")
)
func CheckErrorType(ctx context.Context, err error) string {
// 检查是否为 gerror 包装的错误
code := gerror.Code(err)
// 判断是否有自定义业务码
if code.Code() != 0 {
switch code.Code() {
case gcode.CodeNotFound:
return "Business Error: User Not Found"
case gcode.CodeInvalidParam:
return "Business Error: Invalid Param"
default:
return fmt.Sprintf("Business Error: Code %d", code.Code())
}
}
// 检查是否为原生错误
if err == ErrDBDown {
return "System Error: Database Down"
}
return "Unknown System Error"
}
func main() {
// 模拟测试
result1 := CheckErrorType(context.Background(), ErrUserNotFound)
result2 := CheckErrorType(context.Background(), ErrDBDown)
fmt.Println(result1)
fmt.Println(result2)
}
这段代码演示了如何在错误处理逻辑内部进行类型判断。通过 gerror.Code(err) 获取错误码对象,若其 Code() 返回值不为 0,说明这是经过框架规范化的业务错误,可以进一步根据具体的 gcode 常量进行分类处理。若为 0,则可能是原生 Go 错误或其他第三方错误,这类错误通常代表系统层面的问题,应给予不同的 HTTP 状态码(如 500)和提示信息。这种区分机制使得前端可以根据错误码决定是展示友好的提示页还是重启页面。
基于 gerror.NewCode 的具体行为是什么?
当使用 gerror.NewCode(code, message) 创建错误时,生成的错误对象不仅包含消息文本,还嵌入了一个 gcode.Code 结构体。这个结构体允许开发者定义整型的错误码,便于跨语言或前后端对接。在序列化时,GoFrame 的默认 JSON 编码器会优先提取这个 Code 字段放入响应的 code 键中,而不是仅仅依赖错误消息字符串。这意味着即使消息改变,只要 Code 不变,前端就能稳定地识别错误类型。











