Gin 框架中的规范响应格式设计与实现

为什么需要统一的响应格式首先让我们思考一个问题为什么要统一API响应格式前后端协作效率一致的响应格式让前端开发者能以统一的方式处理服务端响应错误处理简化标准化的错误码和消息便于统一处理各种异常情况接口文档维护规范化响应减少文档编写工作量客户端适配移动端或其他客户端可以复用相同的响应解析逻辑设计统一的响应结构让我们从最基础的响应结构开始。在本文的示例项目中我采用了如下的响应结构type baseResponse struct { Code int json:code Msg string json:msg Data any json:data }这个结构包含了三个基本元素Code: HTTP状态码或业务状态码表示请求的执行结果Msg: 人类可读的消息描述请求的执行状态。(吐槽一下见过各种项目有的用message, 有的用messages, 调用方稍不留神就写错了所以干脆用缩写)Data: 实际的业务数据根据不同接口返回不同内容有的业务还需要返回timestamp或者trace_id之类的内容可以根据实际需求来修改。实现响应处理工具类有了基础结构后我们可以构建一个响应处理工具类。在我的项目中pkg/response/response.go文件实现了多种常用的响应方法// Success 返回200状态码, 默认返回成功 func Success(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: success, } } c.JSON(http.StatusOK, baseResponse{ Code: http.StatusOK, Msg: opts.Msg, Data: data, }) }通过这种方式我们可以针对不同的HTTP状态码提供专门的响应方法Success: 正常业务响应BadRequest: 参数校验失败Unauthorized: 权限校验失败NotFound: 资源不存在InternalServerError: 服务器内部错误处理异常情况仅仅处理正常的业务响应是不够的我们还需要统一拦截异常进行处理否则异常和未注册路由都不会返回我们需要的格式。这里我用一个自定义的异常恢复中间件做异常捕获func CustomRecovery() gin.HandlerFunc { return func(c *gin.Context) { defer func() { if err : recover(); err ! nil { var brokenPipe bool // 检测是否是连接中断 if ne, ok : err.(*net.OpError); ok { if se, ok : ne.Err.(*os.SyscallError); ok { if strings.Contains(strings.ToLower(se.Error()), broken pipe) || strings.Contains(strings.ToLower(se.Error()), connection reset by peer) { brokenPipe true } } } // 获取堆栈信息 stack : string(debug.Stack()) if brokenPipe { c.Abort() response.InternalServerError(c, nil, response.ResponseOption{Msg: network abort}) return } slog.Error(exception catched, error, err, stack, stack) c.Abort() response.InternalServerError(c, nil, response.ResponseOption{Msg: server internal error}) } }() c.Next() } }这个中间件有几个亮点连接中断处理特别处理了 broken pipe 和 connection reset by peer 错误避免客户端提前断开连接时产生冗余错误日志错误信息记录记录错误详情和堆栈信息便于问题排查统一错误响应所有异常都以统一格式返回给客户端路由未找到处理除了异常处理我们还需要处理请求路由不存在的情况r.NoRoute(func(c *gin.Context) { response.NotFound(c, nil, response.ResponseOption{ Msg: 接口不存在, }) })这样当用户请求不存在的接口时也会收到格式统一的响应。使用示例在实际使用中我们的控制器代码变得简洁明了r.GET(/a1, func(c *gin.Context) { response.Success(c, nil, nil) }) r.GET(/a2, func(c *gin.Context) { var respData struct { Name string }{ Name: hello, } response.Success(c, respData, response.ResponseOption{ Msg: how a successful response, }) })无论是在成功响应还是错误响应中客户端收到的都是相同格式的JSON数据极大地提升了开发体验。补充-完整代码示例项目结构├── go.mod ├── go.sum ├── main.go └── pkg └── response └── response.go响应类pkg/response/response.gopackage response import ( net/http github.com/gin-gonic/gin ) type baseResponse struct { Code int json:code Msg string json:msg Data any json:data } type ResponseOption struct { Msg string json:msg } // Success 返回200状态码, 默认返回成功 func Success(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: success, } } c.JSON(http.StatusOK, baseResponse{ Code: http.StatusOK, Msg: opts.Msg, Data: data, }) } // SuccessCreated 返回201状态码, 表示创建成功。常用于新增数据 func SuccessCreated(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: success, } } c.JSON(http.StatusCreated, baseResponse{ Code: http.StatusCreated, Msg: opts.Msg, Data: data, }) } // BadRequest 返回400错误, 常用于参数校验失败 func BadRequest(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: bad request, } } c.JSON(http.StatusBadRequest, baseResponse{ Code: http.StatusBadRequest, Msg: opts.Msg, Data: data, }) } // Unauthorized 401错误, 常用于权限校验失败 func Unauthorized(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: unauthorized, } } c.JSON(http.StatusUnauthorized, baseResponse{ Code: http.StatusUnauthorized, Msg: opts.Msg, Data: data, }) } // Forbidden 403错误, 常用于权限不足 func Forbidden(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: forbidden, } } c.JSON(http.StatusForbidden, baseResponse{ Code: http.StatusForbidden, Msg: opts.Msg, Data: data, }) } // NotFound 404错误, 常用于资源不存在 func NotFound(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: not found, } } c.JSON(http.StatusNotFound, baseResponse{ Code: http.StatusNotFound, Msg: opts.Msg, Data: data, }) } func MethodNotAllowed(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: method not allowed, } } c.JSON(http.StatusMethodNotAllowed, baseResponse{ Code: http.StatusMethodNotAllowed, Msg: opts.Msg, Data: data, }) } // UnprocessableEntity 422错误, 常用于客户端参数导致业务逻辑处理异常 func UnprocessableEntity(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: unprocessable entity, } } c.JSON(http.StatusUnprocessableEntity, baseResponse{ Code: http.StatusUnprocessableEntity, Msg: opts.Msg, Data: data, }) } // InternalServerError 500错误, 常用于服务器内部错误 func InternalServerError(c *gin.Context, data any, opts *ResponseOption) { if opts nil { opts ResponseOption{ Msg: internal server error, } } c.JSON(http.StatusInternalServerError, baseResponse{ Code: http.StatusInternalServerError, Msg: opts.Msg, Data: data, }) }程序入口main.gopackage main import ( log/slog net net/http/httputil os runtime/debug strings tmpgo/pkg/response github.com/gin-gonic/gin ) func main() { gin.SetMode(gin.ReleaseMode) // 生产环境设为 ReleaseMode r : gin.New() // 不要用 gin.Default() // 添加 Logger 和 Recovery 中间件 r.Use(gin.Logger()) r.Use(CustomRecovery()) // 使用自定义异常恢复中间件 // 注册路由 r.GET(/a1, func(c *gin.Context) { response.Success(c, nil, nil) }) r.GET(/a2, func(c *gin.Context) { var respData struct { Name string }{ Name: hello, } response.Success(c, respData, response.ResponseOption{ Msg: how a successful response, }) }) r.GET(/b1, func(c *gin.Context) { response.UnprocessableEntity(c, nil, nil) }) r.GET(/b2, func(c *gin.Context) { panic(panic something) }) // 设置自定义 404 处理 r.NoRoute(func(c *gin.Context) { response.NotFound(c, nil, nil) }) // 设置自定义 405 处理方法不允许 r.NoMethod(func(c *gin.Context) { response.MethodNotAllowed(c, nil, nil) }) r.Run(127.0.0.1:10000) } // 在正式项目中可以统一放到中间件的模块中 // CustomRecovery 自定义异常恢复中间件 func CustomRecovery() gin.HandlerFunc { return func(c *gin.Context) { defer func() { if err : recover(); err ! nil { var brokenPipe bool // 检测是否是连接中断 if ne, ok : err.(*net.OpError); ok { if se, ok : ne.Err.(*os.SyscallError); ok { if strings.Contains(strings.ToLower(se.Error()), broken pipe) || strings.Contains(strings.ToLower(se.Error()), connection reset by peer) { brokenPipe true } } } // 获取堆栈信息 stack : string(debug.Stack()) // 获取原始请求内容可选方便排查是哪个参数导致的崩溃 httpRequest, _ : httputil.DumpRequest(c.Request, false) if brokenPipe { c.Abort() response.InternalServerError(c, nil, response.ResponseOption{Msg: network abort}) return } slog.Error(exception catched, error, err, stack, stack, request, string(httpRequest)) // c.AbortWithStatusJSON() c.Abort() response.InternalServerError(c, nil, response.ResponseOption{Msg: server internal error}) } }() c.Next() } }调用示例$ curl -X GET http://127.0.0.1:10000/a1 {code:200,msg:success,data:null} $ curl http://127.0.0.1:10000/a1 {code:200,msg:success,data:null} $ curl http://127.0.0.1:10000/a2 {code:200,msg:how a successful response,data:{Name:hello}} $ curl http://127.0.0.1:10000/a3 {code:404,msg:not found,data:null} $ curl http://127.0.0.1:10000/b1 {code:422,msg:unprocessable entity,data:null} $ curl http://127.0.0.1:10000/b2 {code:500,msg:server internal error,data:null}