Gin框架快速入门指南

Gin框架快速入门指南

快速开始

安装Gin

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

最小化示例

package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()
    r.GET("/", func(c *gin.Context) {
        c.String(200, "Hello Gin!")
    })
    r.Run() // 默认监听 0.0.0.0:8080
}

核心功能

路由配置

基础路由方法

// GET请求处理
r.GET("/user", getUserList)

// POST请求处理
r.POST("/user", createUser)

// 匹配所有HTTP方法
r.Any("/ping", pingHandler)

路由分组

v1 := r.Group("/v1")
{
    v1.GET("/users", getV1Users)
    v1.POST("/upload", v1Upload)
}

请求处理

路径参数

r.GET("/user/:id", func(c *gin.Context) {
    id := c.Param("id")
    // 处理逻辑
})

查询参数

r.GET("/search", func(c *gin.Context) {
    keyword := c.Query("q")
    page := c.DefaultQuery("page", "1")
})

表单数据

r.POST("/login", func(c *gin.Context) {
    username := c.PostForm("username")
    password := c.PostForm("password")
})

文件上传

r.POST("/upload", func(c *gin.Context) {
    file, _ := c.FormFile("file")
    c.SaveUploadedFile(file, "./uploads/"+file.Filename)
})

响应处理

常见响应类型

// JSON响应
c.JSON(200, gin.H{"status": "ok"})

// XML响应
c.XML(200, config{...})

// 文件响应
c.File("./static/logo.png")

// 重定向
c.Redirect(302, "/new-location")

模板渲染

// 设置模板目录
r.LoadHTMLGlob("templates/*")

// 渲染HTML
r.GET("/", func(c *gin.Context) {
    c.HTML(200, "index.html", gin.H{
        "title": "首页",
    })
})

中间件

自定义中间件

func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        if token := c.GetHeader("Authorization"); token != "" {
            // 验证逻辑
            c.Next()
        } else {
            c.AbortWithStatus(401)
        }
    }
}

// 全局使用
r.Use(AuthMiddleware())

// 路由组使用
authGroup := r.Group("/admin")
authGroup.Use(AuthMiddleware())

内置中间件

// 日志中间件
r.Use(gin.Logger())

// 恢复中间件
r.Use(gin.Recovery())

// 静态文件服务
r.Use(gin.Static("/static", "./public"))

高级功能

参数绑定

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

r.POST("/login", func(c *gin.Context) {
    var form LoginForm
    if err := c.ShouldBind(&form); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    // 处理登录逻辑
})

验证器

type User struct {
    Age   int    `form:"age" binding:"required,gt=18"`
    Email string `form:"email" binding:"required,email"`
}

优雅关闭

srv := &http.Server{
    Addr:    ":8080",
    Handler: r,
}

go func() {
    if err := srv.ListenAndServe(); err != nil {
        log.Printf("Server closed: %v", err)
    }
}()

// 捕获中断信号
quit := make(chan os.Signal)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
srv.Shutdown(ctx)

日志处理

默认配置

r := gin.Default() // 包含Logger和Recovery中间件

自定义格式

r := gin.New()
r.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
    return fmt.Sprintf("%s - [%s] \"%s %s %d %s\"\n",
        param.ClientIP,
        param.TimeStamp.Format(time.RFC1123),
        param.Method,
        param.Path,
        param.StatusCode,
        param.Latency,
    )
}))

文件输出

f, _ := os.Create("gin.log")
gin.DefaultWriter = io.MultiWriter(f, os.Stdout)
r := gin.Default()

禁用功能

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

// 禁用日志输出
gin.DefaultWriter = io.Discard

Zap集成

import (
    "go.uber.org/zap"
    "github.com/gin-contrib/zap"
)

logger, _ := zap.NewProduction()
r.Use(ginzap.Ginzap(logger, time.RFC3339, true))
r.Use(ginzap.RecoveryWithZap(logger, true))