必须在项目启动前注册全局响应结构体并设置ghttp.ResponseHandlerDefault;错误码需为全局唯一整型,推荐用iota定义;Controller层须用gerror包装错误并经响应中间件处理;Service层事务内错误需透传至Controller,由中间件统一转换为Response结构。

统一响应结构体定义与注册
要让所有接口返回格式一致,必须在项目启动前完成响应结构体的全局注册,否则中间件无法识别业务返回值类型。
在 internal/controller/base.go 中定义基础响应结构:
type Response struct { Code int `json:"code"` Message string `json:"message"` Data interface{} `json:"data,omitempty"` Timestamp int64 `json:"timestamp"` }
接着在 internal/cmd/server.go 的服务器初始化处调用 【ghttp.ResponseHandlerDefault = response.Handler】,这是框架唯一认可的默认响应处理器入口点。
不设置该变量会导致后续所有自定义中间件的 WriteJsonExit 调用仍走原始裸响应,彻底绕过你写的封装逻辑。
业务错误码分层管理
GoFrame 要求错误码必须为整型且全局唯一,避免用字符串做 code 字段——框架内部会直接 panic。
方法一:在 internal/consts/error_code.go 中集中声明
const ( ErrCodeUserNotFound = 1001 ErrCodeInvalidParam = 1002 ErrCodeDBTransactionFailed = 1003 )
方法二:用 iota 自动递增(推荐)
const ( ErrCodeSuccess = 0 iota ErrCodeUserNotFound ErrCodeInvalidParam ErrCodeDBTransactionFailed )
注意:iota 必须从空行后开始,否则第一个常量值不是 0。如果已有 ErrCodeSuccess = 0 手动赋值,后面接 iota 会导致 ErrCodeUserNotFound 也等于 0。
Controller 层错误拦截与转换
这一步决定前端能否拿到结构化错误信息。不能在 Controller 里直接 return errors.New("xxx"),必须包装成 gf 框架可识别的 error 类型。
第一步:引入框架错误组件
import "github.com/gogf/gf/v2/errors/gerror"
第二步:在 handler 函数中用 gerror.Newf 包装原始错误
if user == nil { return gerror.Newf("用户不存在,ID:%d", id) }
第三步:确保该 handler 已被响应中间件包裹——检查路由注册时是否调用了 group.Middleware(ghttp.MiddlewareHandlerResponse)
第四步:在中间件中捕获 error 并映射为 Response 结构
func ResponseMiddleware(r *ghttp.Request) { r.Middleware.Next() if r.GetError() != nil { code := GetErrorCode(r.GetError()) // 自定义映射函数 r.Response.WriteJsonExit(Response{ Code: code, Message: r.GetError().Error(), Data: nil, Timestamp: time.Now().Unix(), }) } }
Service 层事务内错误透传
事务必须在 Service 层开启,Controller 层只负责接收和响应。若把 db.Transaction 写在 Controller 里,一旦 panic 就无法被捕获到统一错误处理器中。
① 在 Service 方法开头显式开启事务:
ctx := r.Context() tx, err := dao.DB.Tx(ctx) if err != nil { return nil, gerror.Wrap(err, "开启事务失败") }
② 所有 DAO 操作必须使用 tx 对象,不能用 dao.DB
③ 成功时提交,失败时回滚并返回带堆栈的 error:
if err != nil { tx.Rollback(ctx) return nil, gerror.Wrapf(err, "创建用户失败,参数:%+v", input) }
④ 最终由 Controller 调用该 Service 方法,并原样 return 其 error ——框架会自动将其交给上层中间件处理
这一步不做透传,错误就会卡死在 Service 内部,ResponseMiddleware 根本收不到任何 error,前端只看到 200 状态码和空 data。

















