GoFrame项目需实现统一响应结构与错误码管理:定义含Code、Message、Data、Timestamp字段的Response结构并添加构造方法;集中用const或map管理唯一整型错误码;通过中间件自动封装返回;使用CodeError或gerror.NewCode抛出自定义错误。

在GoFrame项目中实现统一返回结构与错误码管理,能让前端准确识别业务状态、快速定位异常原因,避免各接口各自为政返回格式混乱、错误信息裸露或缺失。
定义全局统一响应结构体
创建 response.go 文件,声明标准响应结构,确保所有 HTTP 接口都通过该结构返回数据。
第一步:在 internal/response/ 目录下新建 response.go,写入如下结构:
type Response struct { Code int `json:"code"` Message string `json:"message"` Data interface{} `json:"data,omitempty"` Timestamp int64 `json:"timestamp"` }
注意:Data 字段必须加 omitempty 标签,否则空对象(如 map[string]interface{})会序列化为 "data":{} 而非省略,干扰前端判空逻辑。
第二步:为该结构添加快捷构造方法,例如 Success(data interface{}) *Response 和 Error(code int, msg string) *Response,内部自动填充 Timestamp: time.Now().Unix()。
集中管理业务错误码
错误码不能散落在各 controller 或 service 中硬编码,必须收口到单一文件,支持 IDE 跳转、全局搜索和版本比对。
方法一:使用 const 常量组定义(适合中小项目)
在 internal/code/code.go 中按模块分组声明:
const ( OK = 0 // 成功 UserNotFound = 1001 // 用户不存在 InvalidParams = 1002 // 参数校验失败 TokenExpired = 2001 // token 过期 InternalError = 5000 // 系统内部错误 )
方法二:使用 map 初始化错误码元信息(适合需携带 HTTP 状态码、日志等级的中大型项目)
定义结构体 CodeInfo,包含 Code、Message、HTTPStatus、LogLevel;在 init() 函数中用 map 预加载全部错误码,并提供 GetMsg(code int) string 查询方法。
【Key】所有错误码值必须为整型且全局唯一,禁止不同语义复用同一数字,如 1001 不可既表示“用户不存在”又表示“订单未找到”。
中间件拦截并封装返回结果
让每个成功 handler 返回的数据自动套上 Response{Code: code.OK, Data: result},无需每个接口手动 new。
在 middleware/response.go 中编写 Gin 风格中间件(GoFrame v2 使用 ghttp.Handler):
注册 g.Server().BindHandler("/*", responseMiddleware),在中间件中捕获 ctx.GetHandlerResponse() 的原始返回值。
若返回值是 error 类型,则调用 code.ToResponse(err) 转为标准 Response 并设置 HTTP 状态码;若返回值是普通结构体或 nil,则包装为 Success()。
这一步必须放在路由注册之后、服务启动之前,否则中间件不生效。
自定义错误类型并关联错误码
业务逻辑中不直接 return errors.New("xxx"),而是抛出自定义 error 实例,便于中间件精准识别并映射到预设码。
方法一:实现 Code() int 和 Error() string 接口
定义 type CodeError struct { code int msg string },为其绑定两个方法。当 service 层调用 return &CodeError{code: code.UserNotFound, msg: "user not exist"},中间件即可提取 err.Code() 查表渲染。
方法二:使用 GoFrame 自带的 gerror.NewCode(code int, format string, args ...interface{})
直接在代码中写 return gerror.NewCode(code.UserNotFound, "user %d not found", uid),后续可通过 gerror.Code(err) 提取码值,无需额外定义结构体。
【注意】gerror.NewCode 创建的 error 默认不带堆栈,如需调试追踪,改用 gerror.NewCodef 并开启 GF_LOG_STACK=1。

















