Gin框架快速入门指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00361/article/details/148323311

Gin框架快速入门指南

gin gin-gonic/gin: 是一个基于 Go 语言的 HTTP 框架，支持多种 HTTP 协议和服务。该项目提供了一个简单易用的 HTTP 框架，可以方便地实现 HTTP 服务的开发和部署，同时支持多种 HTTP 协议和服务。项目地址: https://gitcode.com/gh_mirrors/gi/gin

Gin是一个用Go语言编写的高性能Web框架，以其简洁的API和出色的性能著称。本文将带你快速了解Gin框架的核心功能和使用方法。

构建选项

替换JSON处理库

Gin默认使用encoding/json作为JSON处理库，但你可以通过构建标签替换为其他高性能库：

jsoniter：提供更快的JSON处理速度
```
go build -tags=jsoniter .
```
go-json：另一个高性能JSON库
```
go build -tags=go_json .
```
sonic：字节跳动开发的高性能JSON库
```
go build -tags=sonic .
```

禁用MsgPack渲染功能

Gin默认启用MsgPack渲染功能，可以通过构建标签禁用以减小二进制文件大小：

go build -tags=nomsgpack .

核心API示例

HTTP方法支持

Gin支持所有常见的HTTP方法：

router := gin.Default()

router.GET("/someGet", gettingHandler)
router.POST("/somePost", postingHandler)
router.PUT("/somePut", puttingHandler)
router.DELETE("/someDelete", deletingHandler)
router.PATCH("/somePatch", patchingHandler)
router.HEAD("/someHead", headHandler)
router.OPTIONS("/someOptions", optionsHandler)

router.Run() // 默认监听8080端口

路径参数

Gin支持两种路径参数格式：

必选参数：/user/:name 匹配/user/john但不匹配/user/
可选参数：/user/:name/*action 匹配/user/john/和/user/john/send

router.GET("/user/:name", func(c *gin.Context) {
    name := c.Param("name")
    c.String(200, "Hello %s", name)
})

查询参数

获取URL查询参数的方法：

router.GET("/welcome", func(c *gin.Context) {
    firstname := c.DefaultQuery("firstname", "Guest") // 带默认值
    lastname := c.Query("lastname") // 不带默认值
    c.String(200, "Hello %s %s", firstname, lastname)
})

表单处理

处理POST表单数据：

router.POST("/form_post", func(c *gin.Context) {
    message := c.PostForm("message")
    nick := c.DefaultPostForm("nick", "anonymous")
    
    c.JSON(200, gin.H{
        "status":  "posted",
        "message": message,
        "nick":    nick,
    })
})

文件上传

单文件上传

router.MaxMultipartMemory = 8 << 20 // 8MB限制
router.POST("/upload", func(c *gin.Context) {
    file, _ := c.FormFile("file")
    c.SaveUploadedFile(file, dst)
    c.String(200, "'%s' uploaded!", file.Filename)
})

多文件上传

router.POST("/upload", func(c *gin.Context) {
    form, _ := c.MultipartForm()
    files := form.File["upload[]"]
    
    for _, file := range files {
        c.SaveUploadedFile(file, dst)
    }
    c.String(200, "%d files uploaded!", len(files))
})

路由分组

路由分组有助于组织API结构：

v1 := router.Group("/v1")
{
    v1.POST("/login", loginEndpoint)
    v1.POST("/submit", submitEndpoint)
    v1.POST("/read", readEndpoint)
}

v2 := router.Group("/v2")
{
    v2.POST("/login", loginEndpoint)
    v2.POST("/submit", submitEndpoint)
    v2.POST("/read", readEndpoint)
}

中间件

使用内置中间件

// 创建不带默认中间件的路由
r := gin.New()

// 全局中间件
r.Use(gin.Logger())    // 日志记录
r.Use(gin.Recovery())  // 错误恢复

// 路由级中间件
r.GET("/benchmark", MyBenchLogger(), benchEndpoint)

// 分组中间件
authorized := r.Group("/")
authorized.Use(AuthRequired())
{
    authorized.POST("/login", loginEndpoint)
}

自定义错误恢复

r.Use(gin.CustomRecovery(func(c *gin.Context, recovered any) {
    if err, ok := recovered.(string); ok {
        c.String(500, fmt.Sprintf("error: %s", err))
    }
    c.AbortWithStatus(500)
}))

日志配置

自定义日志格式

router.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
    return fmt.Sprintf("%s - [%s] \"%s %s %s %d %s \"%s\" %s\"\n",
        param.ClientIP,
        param.TimeStamp.Format(time.RFC1123),
        param.Method,
        param.Path,
        param.Request.Proto,
        param.StatusCode,
        param.Latency,
        param.Request.UserAgent(),
        param.ErrorMessage,
    )
}))

日志输出控制

// 禁用控制台颜色
gin.DisableConsoleColor()

// 记录到文件
f, _ := os.Create("gin.log")
gin.DefaultWriter = io.MultiWriter(f)

// 同时输出到文件和控制台
// gin.DefaultWriter = io.MultiWriter(f, os.Stdout)

数据绑定与验证

Gin提供了强大的数据绑定和验证功能：

type Login struct {
    User     string `form:"user" json:"user" binding:"required"`
    Password string `form:"password" json:"password" binding:"required"`
}

// 绑定JSON
router.POST("/loginJSON", func(c *gin.Context) {
    var json Login
    if err := c.ShouldBindJSON(&json); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    
    if json.User != "manu" || json.Password != "123" {
        c.JSON(401, gin.H{"status": "unauthorized"})
        return
    } 
    
    c.JSON(200, gin.H{"status": "you are logged in"})
})

模板渲染

HTML模板

router.LoadHTMLGlob("templates/*")
router.GET("/", func(c *gin.Context) {
    c.HTML(200, "index.tmpl", gin.H{
        "title": "Main website",
    })
})

多模板

router := gin.New()
router.HTMLRender = multitemplate.NewRenderer()
router.HTMLRender.Add("index", "templates/base.tmpl", "templates/index.tmpl")
router.GET("/", func(c *gin.Context) {
    c.HTML(200, "index", gin.H{
        "title": "Main website",
    })
})

高级功能

HTTP/2服务器推送

router.GET("/", func(c *gin.Context) {
    if pusher := c.Writer.Pusher(); pusher != nil {
        if err := pusher.Push("/static/style.css", nil); err != nil {
            log.Printf("Failed to push: %v", err)
        }
    }
    c.HTML(200, "index", gin.H{"title": "Main website"})
})

优雅关闭

server := &http.Server{
    Addr:    ":8080",
    Handler: router,
}

go func() {
    if err := server.ListenAndServe(); err != nil {
        log.Printf("listen: %s\n", err)
    }
}()

// 捕获中断信号
quit := make(chan os.Signal)
signal.Notify(quit, os.Interrupt)
<-quit
log.Println("Shutdown Server...")

// 设置5秒超时
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := server.Shutdown(ctx); err != nil {
    log.Fatal("Server Shutdown:", err)
}
log.Println("Server exiting")