Gin 框架使用教程

一、简介

Gin 是一个用 Go 编写的轻量级、高性能 Web 框架，提供简单易用的 API，适合快速开发。

特点：

极高性能：基于 httprouter。
灵活的路由和中间件机制。
内置 JSON 解析和验证。

官方网站：https://gin-gonic.com/

二、快速开始

安装 Gin

go get -u github.com/gin-gonic/gin

基本示例

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    r.GET("/ping", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "pong",
        })
    })

    r.Run() // 默认监听 :8080
}

三、核心功能

1. 路由

Gin 的路由非常灵活，支持 GET、POST 等多种 HTTP 方法。

r.GET("/get", func(c *gin.Context) {
    c.JSON(200, gin.H{"method": "GET"})
})

r.POST("/post", func(c *gin.Context) {
    c.JSON(200, gin.H{"method": "POST"})
})

路由参数：

r.GET("/user/:id", func(c *gin.Context) {
    id := c.Param("id")
    c.JSON(200, gin.H{"id": id})
})

2. 中间件

中间件可以在请求处理前后执行额外逻辑。

// 自定义中间件
func Logger() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 请求前
        t := time.Now()

        // 处理请求
        c.Next()

        // 请求后
        latency := time.Since(t)
        fmt.Printf("%v\n", latency)
    }
}

r.Use(Logger())

3. 数据绑定

绑定 JSON 数据

r.POST("/json", func(c *gin.Context) {
    var json struct {
        Name string `json:"name"`
        Age  int    `json:"age"`
    }

    if err := c.ShouldBindJSON(&json); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    c.JSON(200, gin.H{"name": json.Name, "age": json.Age})
})

4. 返回响应

r.GET("/response", func(c *gin.Context) {
    c.JSON(200, gin.H{"message": "success"})
})

r.GET("/xml", func(c *gin.Context) {
    c.XML(200, gin.H{"message": "success"})
})

四、进阶功能

1. 文件上传

单文件上传：

r.POST("/upload", func(c *gin.Context) {
    file, err := c.FormFile("file")
    if err != nil {
        c.JSON(400, gin.H{"error": "Invalid file"})
        return
    }

    err = c.SaveUploadedFile(file, "./uploads/"+file.Filename)
    if err != nil {
        c.JSON(500, gin.H{"error": "Failed to save file"})
        return
    }

    c.JSON(200, gin.H{"message": "File uploaded successfully"})
})

多文件上传：

r.POST("/uploads", func(c *gin.Context) {
    form, _ := c.MultipartForm()
    files := form.File["files"]

    for _, file := range files {
        err := c.SaveUploadedFile(file, "./uploads/"+file.Filename)
        if err != nil {
            c.JSON(500, gin.H{"error": "Failed to save file"})
            return
        }
    }

    c.JSON(200, gin.H{"message": "Files uploaded successfully"})
})

2. WebSocket 支持

import (
    "net/http"
    "github.com/gin-gonic/gin"
    "github.com/gorilla/websocket"
)

var upgrader = websocket.Upgrader{
    CheckOrigin: func(r *http.Request) bool {
        return true
    },
}

r.GET("/ws", func(c *gin.Context) {
    conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
    if err != nil {
        c.JSON(500, gin.H{"error": "Failed to establish WebSocket connection"})
        return
    }
    defer conn.Close()

    for {
        messageType, message, err := conn.ReadMessage()
        if err != nil {
            break
        }

        err = conn.WriteMessage(messageType, message)
        if err != nil {
            break
        }
    }
})

通过 /ws 端点，客户端可以建立 WebSocket 连接。

3. 自定义错误处理

r.Use(func(c *gin.Context) {
    c.Next()

    if len(c.Errors) > 0 {
        c.JSON(-1, gin.H{
            "status":  "error",
            "messages": c.Errors.Errors(),
        })
    }
})

4. 分组路由

api := r.Group("/api")
{
    api.GET("/user", func(c *gin.Context) {
        c.JSON(200, gin.H{"user": "info"})
    })

    api.POST("/user", func(c *gin.Context) {
        c.JSON(200, gin.H{"status": "created"})
    })
}