Gin 框架中的规范相应格式计划与实现

在当代Web应用开辟中，同一和规范化的API相应格式对于前后端协作至关告急。本日，我们来探究怎样在Gin框架中计划一套既实用又易于维护的相应格式规范。
为什么须要同一的相应格式？

起首，让我们思索一个题目：为什么要同一API相应格式？

• 前后端协作服从：同等的相应格式让前端开辟者能以同一的方式处置惩罚服务端相应
  
• 错误处置惩罚简化：尺度化的错误码和消息便于同一处置惩罚各种非常环境
  
• 接口文档维护：规范化相应淘汰文档编写工作量
  
• 客户端适配：移动端或其他客户端可以复用类似的相应剖析逻辑
  

计划同一的相应布局

让我们从最底子的相应布局开始。在本文的示例项目中，我接纳了如下的相应布局：

1. type baseResponse struct {
2.     Code int    `json:"code"`
3.     Msg  string `json:"msg"`
4.     Data any    `json:"data"`
5. }

复制代码

这个布局包罗了三个根本元素：

• Code: HTTP状态码或业务状态码，表现哀求的实行效果
  
• Msg: 人类可读的消息，形貌哀求的实行状态。(吐槽一下，见过各种项目，有的用"message", 有的用""messages", 调用方稍不注意就写错了，以是干脆用缩写)
  
• Data: 实际的业务数据，根据差别接口返回差别内容
  

有的业务还须要返回timestamp大概trace_id之类的内容，可以根据实际需求来修改。
实现相应处置惩罚工具类

有了底子布局后，我们可以构建一个相应处置惩罚工具类。在我的项目中，pkg/response/response.go 文件实现了多种常用的相应方法：

1. // Success 返回200状态码, 默认返回成功
2. func Success(c *gin.Context, data any, opts *ResponseOption) {
3.     if opts == nil {
4.         opts = &ResponseOption{
5.             Msg: "success",
6.         }
7.     }
8.     c.JSON(http.StatusOK, baseResponse{
9.         Code: http.StatusOK,
10.         Msg:  opts.Msg,
11.         Data: data,
12.     })
13. }

复制代码

通过这种方式，我们可以针对差别的HTTP状态码提供专门的相应方法：

• Success: 正常业务相应
  
• BadRequest: 参数校验失败
  
• Unauthorized: 权限校验失败
  
• NotFound: 资源不存在
  
• InternalServerError: 服务器内部错误
  

处置惩罚非常环境

仅仅处置惩罚正常的业务相应是不敷的，我们还须要同一拦截非常举行处置惩罚，否则非常和未注册路由都不会返回我们须要的格式。这里我用一个自界说的非通例复中心件做非常捕获：

1. func CustomRecovery() gin.HandlerFunc {
2.     return func(c *gin.Context) {
3.         defer func() {
4.             if err := recover(); err != nil {
5.                 var brokenPipe bool
6.                 // 检测是否是连接中断
7.                 if ne, ok := err.(*net.OpError); ok {
8.                     if se, ok := ne.Err.(*os.SyscallError); ok {
9.                         if strings.Contains(strings.ToLower(se.Error()), "broken pipe") ||
10.                             strings.Contains(strings.ToLower(se.Error()), "connection reset by peer") {
11.                             brokenPipe = true
12.                         }
13.                     }
14.                 }
16.                 // 获取堆栈信息
17.                 stack := string(debug.Stack())
19.                 if brokenPipe {
20.                     c.Abort()
21.                     response.InternalServerError(c, nil, &response.ResponseOption{Msg: "network abort"})
22.                     return
23.                 }
25.                 slog.Error("exception catched", "error", err, "stack", stack)
26.                 c.Abort()
27.                 response.InternalServerError(c, nil, &response.ResponseOption{Msg: "server internal error"})
28.             }
29.         }()
30.         c.Next()
31.     }
32. }

复制代码

这个中心件有几个亮点：

• 毗连停止处置惩罚：特别处置惩罚了 "broken pipe" 和 "connection reset by peer" 错误，克制客户端提前断开毗连时产生冗余错误日记
  
• 错误信息记载：记载错误详情和堆栈信息，便于题目排查
  
• 同一错误相应：全部非常都以同一格式返回给客户端
  

路由未找到处置惩罚

除了非常处置惩罚，我们还须要处置惩罚哀求路由不存在的环境：

1. r.NoRoute(func(c *gin.Context) {
2.     response.NotFound(c, nil, &response.ResponseOption{
3.         Msg: "接口不存在",
4.     })
5. })

复制代码

如许，当用户哀求不存在的接口时，也会收到格式同一的相应。
利用示例

在实际利用中，我们的控制器代码变得轻便明白：

1. r.GET("/a1", func(c *gin.Context) {
2.     response.Success(c, nil, nil)
3. })
5. r.GET("/a2", func(c *gin.Context) {
6.     var respData = struct {
7.         Name string
8.     }{
9.         Name: "hello",
10.     }
11.     response.Success(c, respData, &response.ResponseOption{
12.         Msg: "how a successful response",
13.     })
14. })

复制代码

无论是在乐成相应还是错误相应中，客户端收到的都是类似格式的JSON数据，极大地提升了开辟体验。
增补-完备代码示例

项目布局：

1. ├── go.mod
2. ├── go.sum
3. ├── main.go
4. └── pkg
5.     └── response
6.         └── response.go

复制代码

相应类

• pkg/response/response.go
  

1. package response
3. import (
4.         "net/http"
6.         "github.com/gin-gonic/gin"
7. )
9. type baseResponse struct {
10.         Code int    `json:"code"`
11.         Msg  string `json:"msg"`
12.         Data any    `json:"data"`
13. }
15. type ResponseOption struct {
16.         Msg string `json:"msg"`
17. }
19. // Success 返回200状态码, 默认返回成功
20. func Success(c *gin.Context, data any, opts *ResponseOption) {
21.         if opts == nil {
22.                 opts = &ResponseOption{
23.                         Msg: "success",
24.                 }
25.         }
26.         c.JSON(http.StatusOK, baseResponse{
27.                 Code: http.StatusOK,
28.                 Msg:  opts.Msg,
29.                 Data: data,
30.         })
31. }
33. // SuccessCreated 返回201状态码, 表示创建成功。常用于新增数据
34. func SuccessCreated(c *gin.Context, data any, opts *ResponseOption) {
35.         if opts == nil {
36.                 opts = &ResponseOption{
37.                         Msg: "success",
38.                 }
39.         }
40.         c.JSON(http.StatusCreated, baseResponse{
41.                 Code: http.StatusCreated,
42.                 Msg:  opts.Msg,
43.                 Data: data,
44.         })
45. }
47. // BadRequest 返回400错误, 常用于参数校验失败
48. func BadRequest(c *gin.Context, data any, opts *ResponseOption) {
49.         if opts == nil {
50.                 opts = &ResponseOption{
51.                         Msg: "bad request",
52.                 }
53.         }
54.         c.JSON(http.StatusBadRequest, baseResponse{
55.                 Code: http.StatusBadRequest,
56.                 Msg:  opts.Msg,
57.                 Data: data,
58.         })
59. }
61. // Unauthorized 401错误, 常用于权限校验失败
62. func Unauthorized(c *gin.Context, data any, opts *ResponseOption) {
63.         if opts == nil {
64.                 opts = &ResponseOption{
65.                         Msg: "unauthorized",
66.                 }
67.         }
68.         c.JSON(http.StatusUnauthorized, baseResponse{
69.                 Code: http.StatusUnauthorized,
70.                 Msg:  opts.Msg,
71.                 Data: data,
72.         })
73. }
75. // Forbidden 403错误, 常用于权限不足
76. func Forbidden(c *gin.Context, data any, opts *ResponseOption) {
77.         if opts == nil {
78.                 opts = &ResponseOption{
79.                         Msg: "forbidden",
80.                 }
81.         }
82.         c.JSON(http.StatusForbidden, baseResponse{
83.                 Code: http.StatusForbidden,
84.                 Msg:  opts.Msg,
85.                 Data: data,
86.         })
87. }
89. // NotFound 404错误, 常用于资源不存在
90. func NotFound(c *gin.Context, data any, opts *ResponseOption) {
91.         if opts == nil {
92.                 opts = &ResponseOption{
93.                         Msg: "not found",
94.                 }
95.         }
96.         c.JSON(http.StatusNotFound, baseResponse{
97.                 Code: http.StatusNotFound,
98.                 Msg:  opts.Msg,
99.                 Data: data,
100.         })
101. }
103. func MethodNotAllowed(c *gin.Context, data any, opts *ResponseOption) {
104.         if opts == nil {
105.                 opts = &ResponseOption{
106.                         Msg: "method not allowed",
107.                 }
108.         }
109.         c.JSON(http.StatusMethodNotAllowed, baseResponse{
110.                 Code: http.StatusMethodNotAllowed,
111.                 Msg:  opts.Msg,
112.                 Data: data,
113.         })
114. }
116. // UnprocessableEntity 422错误, 常用于客户端参数导致业务逻辑处理异常
117. func UnprocessableEntity(c *gin.Context, data any, opts *ResponseOption) {
118.         if opts == nil {
119.                 opts = &ResponseOption{
120.                         Msg: "unprocessable entity",
121.                 }
122.         }
123.         c.JSON(http.StatusUnprocessableEntity, baseResponse{
124.                 Code: http.StatusUnprocessableEntity,
125.                 Msg:  opts.Msg,
126.                 Data: data,
127.         })
128. }
130. // InternalServerError 500错误, 常用于服务器内部错误
131. func InternalServerError(c *gin.Context, data any, opts *ResponseOption) {
132.         if opts == nil {
133.                 opts = &ResponseOption{
134.                         Msg: "internal server error",
135.                 }
136.         }
137.         c.JSON(http.StatusInternalServerError, baseResponse{
138.                 Code: http.StatusInternalServerError,
139.                 Msg:  opts.Msg,
140.                 Data: data,
141.         })
142. }

复制代码

步伐入口

• main.go
  

1. package main
3. import (
4.         "log/slog"
5.         "net"
6.         "net/http/httputil"
7.         "os"
8.         "runtime/debug"
9.         "strings"
10.         "tmpgo/pkg/response"
12.         "github.com/gin-gonic/gin"
13. )
15. func main() {
16.         gin.SetMode(gin.ReleaseMode) // 生产环境设为 ReleaseMode
17.         r := gin.New()  // 不要用 gin.Default()
19.         // 添加 Logger 和 Recovery 中间件
20.         r.Use(gin.Logger())
21.         r.Use(CustomRecovery()) // 使用自定义异常恢复中间件
23.         // 注册路由
24.         r.GET("/a1", func(c *gin.Context) {
25.                 response.Success(c, nil, nil)
26.         })
27.         r.GET("/a2", func(c *gin.Context) {
28.                 var respData = struct {
29.                         Name string
30.                 }{
31.                         Name: "hello",
32.                 }
33.                 response.Success(c, respData, &response.ResponseOption{
34.                         Msg: "how a successful response",
35.                 })
36.         })
37.         r.GET("/b1", func(c *gin.Context) {
38.                 response.UnprocessableEntity(c, nil, nil)
39.         })
40.         r.GET("/b2", func(c *gin.Context) {
41.                 panic("panic something")
42.         })
44.         // 设置自定义 404 处理
45.         r.NoRoute(func(c *gin.Context) {
46.                 response.NotFound(c, nil, nil)
47.         })
49.         // 设置自定义 405 处理（方法不允许）
50.         r.NoMethod(func(c *gin.Context) {
51.                 response.MethodNotAllowed(c, nil, nil)
52.         })
54.         r.Run("127.0.0.1:10000")
55. }
57. // 在正式项目中，可以统一放到中间件的模块中
58. // CustomRecovery 自定义异常恢复中间件
59. func CustomRecovery() gin.HandlerFunc {
60.         return func(c *gin.Context) {
61.                 defer func() {
62.                         if err := recover(); err != nil {
63.                                 var brokenPipe bool
64.                                 // 检测是否是连接中断
65.                                 if ne, ok := err.(*net.OpError); ok {
66.                                         if se, ok := ne.Err.(*os.SyscallError); ok {
67.                                                 if strings.Contains(strings.ToLower(se.Error()), "broken pipe") ||
68.                                                         strings.Contains(strings.ToLower(se.Error()), "connection reset by peer") {
69.                                                         brokenPipe = true
70.                                                 }
71.                                         }
72.                                 }
74.                                 // 获取堆栈信息
75.                                 stack := string(debug.Stack())
77.                                 // 获取原始请求内容（可选，方便排查是哪个参数导致的崩溃）
78.                                 httpRequest, _ := httputil.DumpRequest(c.Request, false)
80.                                 if brokenPipe {
81.                                         c.Abort()
82.                                         response.InternalServerError(c, nil, &response.ResponseOption{Msg: "network abort"})
83.                                         return
84.                                 }
86.                                 slog.Error("exception catched", "error", err, "stack", stack, "request", string(httpRequest))
87.                                 // c.AbortWithStatusJSON()
88.                                 c.Abort()
89.                                 response.InternalServerError(c, nil, &response.ResponseOption{Msg: "server internal error"})
90.                         }
91.                 }()
92.                 c.Next()
93.         }
94. }

复制代码

调用示例

1. $ curl -X GET http://127.0.0.1:10000/a1
2. {"code":200,"msg":"success","data":null}
4. $ curl http://127.0.0.1:10000/a1
5. {"code":200,"msg":"success","data":null}
7. $ curl http://127.0.0.1:10000/a2
8. {"code":200,"msg":"how a successful response","data":{"Name":"hello"}}
10. $ curl http://127.0.0.1:10000/a3
11. {"code":404,"msg":"not found","data":null}
13. $ curl http://127.0.0.1:10000/b1
14. {"code":422,"msg":"unprocessable entity","data":null}
16. $ curl http://127.0.0.1:10000/b2
17. {"code":500,"msg":"server internal error","data":null}

复制代码