gin中文文档示例

示例

该节列出了 api 的用法。

AsciiJSON

使用 AsciiJSON 生成具有转义的非 ASCII 字符的 ASCII-only JSON。

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

    r.GET("/someJSON", func(c *gin.Context) {
        data := map[string]interface{}{
            "lang": "GO语言",
            "tag":  "
",
        }

        // 输出 : {"lang":"GO\u8bed\u8a00","tag":"\u003cbr\u003e"}
        c.AsciiJSON(http.StatusOK, data)
    })

    // 监听并在 : 上启动服务
    r.Run(":")
}

HTML 渲染

使用 LoadHTMLGlob() 或者 LoadHTMLFiles()

func main() {
    router := gin.Default()
    router.LoadHTMLGlob("templates/*")
    //router.LoadHTMLFiles("templates/template1.html", "templates/template2.html")
    router.GET("/index", func(c *gin.Context) {
        c.HTML(http.StatusOK, "index.tmpl", gin.H{
            "title": "Main website",
        })
    })
    router.Run(":")
}

templates/index.tmpl


    
        {{ .title }}

使用不同目录下名称相同的模板

func main() {
    router := gin.Default()
    router.LoadHTMLGlob("templates/**/*")
    router.GET("/posts/index", func(c *gin.Context) {
        c.HTML(http.StatusOK, "posts/index.tmpl", gin.H{
            "title": "Posts",
        })
    })
    router.GET("/users/index", func(c *gin.Context) {
        c.HTML(http.StatusOK, "users/index.tmpl", gin.H{
            "title": "Users",
        })
    })
    router.Run(":")
}

templates/posts/index.tmpl

{{ define "posts/index.tmpl" }}

    {{ .title }}

Using posts/index.tmpl

{{ end }}

templates/users/index.tmpl

{{ define "users/index.tmpl" }}

    {{ .title }}

Using users/index.tmpl

{{ end }}

自定义模板渲染器

你可以使用自定义的 html 模板渲染

import "html/template"

func main() {
    router := gin.Default()
    html := template.Must(template.ParseFiles("file1", "file2"))
    router.SetHTMLTemplate(html)
    router.Run(":")
}

自定义分隔符

你可以使用自定义分隔

    r := gin.Default()
    r.Delims("{[{", "}]}")
    r.LoadHTMLGlob("/path/to/templates")

自定义模板功能

查看详细示例代码。

main.go

import (
    "fmt"
    "html/template"
    "net/http"
    "time"

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

func formatAsDate(t time.Time) string {
    year, month, day := t.Date()
    return fmt.Sprintf("%d/%02d/%02d", year, month, day)
}

func main() {
    router := gin.Default()
    router.Delims("{[{", "}]}")
    router.SetFuncMap(template.FuncMap{
        "formatAsDate": formatAsDate,
    })
    router.LoadHTMLFiles("./testdata/template/raw.tmpl")

    router.GET("/raw", func(c *gin.Context) {
        c.HTML(http.StatusOK, "raw.tmpl", map[string]interface{}{
            "now": time.Date, , , 0, 0, 0, 0, time.UTC),
        })
    })

    router.Run(":")
}

raw.tmpl

Date: {[{.now | formatAsDate}]}

结果：

Date: //

HTTP2 server 推送

http.Pusher 仅支持 go1.8+。更多信息，请查阅 golang blog。

package main

import (
    "html/template"
    "log"

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

var html = template.Must(template.New("https").Parse(`


  Https Test
  


  Welcome, Ginner!


`))

func main() {
    r := gin.Default()
    r.Static("/assets", "./assets")
    r.SetHTMLTemplate(html)

    r.GET("/", func(c *gin.Context) {
        if pusher := c.Writer.Pusher(); pusher != nil {
            // 使用 pusher.Push() 做服务器推送
            if err := pusher.Push("/assets/app.js", nil); err != nil {
                log.Printf("Failed to push: %v", err)
            }
        }
        c.HTML, "https", gin.H{
            "status": "success",
        })
    })

    // 监听并在 https://: 上启动服务
    r.RunTLS(":", "./testdata/server.pem", "./testdata/server.key")
}

JSONP

使用 JSONP 向不同域的服务器请求数据。如果查询参数存在回调，则将回调添加到响应体中。

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

    r.GET("/JSONP", func(c *gin.Context) {
        data := map[string]interface{}{
            "foo": "bar",
        }
        
        // /JSONP?callback=x
        // 将输出：x({\"foo\":\"bar\"})
        c.JSONP(http.StatusOK, data)
    })

    // 监听并在 : 上启动服务
    r.Run(":")
}

Multipart/Urlencoded 绑定

package main

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

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

func main() {
    router := gin.Default()
    router.POST("/login", func(c *gin.Context) {
        // 你可以使用显式绑定声明绑定 multipart form：
        // c.ShouldBindWith(&form, binding.Form)
        // 或者简单地使用 ShouldBind 方法自动绑定：
        var form LoginForm
        // 在这种情况下，将自动选择合适的绑定
        if c.ShouldBind(&form) == nil {
            if form.User == "user" && form.Password == "password" {
                c.JSON, gin.H{"status": "you are logged in"})
            } else {
                c.JSON, gin.H{"status": "unauthorized"})
            }
        }
    })
    router.Run(":")
}

测试：

$ curl -v --form user=user --form password=password http://localhost:/login

Multipart/Urlencoded 表单

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

    router.POST("/form_post", func(c *gin.Context) {
        message := c.PostForm("message")
        nick := c.DefaultPostForm("nick", "anonymous")

        c.JSON, gin.H{
            "status":  "posted",
            "message": message,
            "nick":    nick,
        })
    })
    router.Run(":")
}

PureJSON

通常，JSON 使用 unicode 替换特殊 HTML 字符，例如 < 变为 \ u003c。如果要按字面对这些字符进行编码，则可以使用 PureJSON。Go 及更低版本无法使用此功能。

func main() {
    r := gin.Default()
    
    // 提供 unicode 实体
    r.GET("/json", func(c *gin.Context) {
        c.JSON, gin.H{
            "html": "Hello, world!",
        })
    })
    
    // 提供字面字符
    r.GET("/purejson", func(c *gin.Context) {
        c.PureJSON, gin.H{
            "html": "Hello, world!",
        })
    })
    
    // 监听并在 : 上启动服务
    r.Run(":")
}

Query 和 post form

POST /post?id=&page=1 HTTP/
Content-Type: application/x-www-form-urlencoded

name=manu&message=this_is_great
func main() {
    router := gin.Default()

    router.POST("/post", func(c *gin.Context) {

        id := c.Query("id")
        page := c.DefaultQuery("page", "0")
        name := c.PostForm("name")
        message := c.PostForm("message")

        fmt.Printf("id: %s; page: %s; name: %s; message: %s", id, page, name, message)
    })
    router.Run(":")
}
id: ; page: 1; name: manu; message: this_is_great

SecureJSON

使用 SecureJSON 防止 json 劫持。如果给定的结构是数组值，则默认预置 "while(1)," 到响应体。

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

    // 你也可以使用自己的 SecureJSON 前缀
    // r.SecureJsonPrefix(")]}',\n")

    r.GET("/someJSON", func(c *gin.Context) {
        names := []string{"lena", "austin", "foo"}

        // 将输出：while(1);["lena","austin","foo"]
        c.SecureJSON(http.StatusOK, names)
    })

    // 监听并在 : 上启动服务
    r.Run(":")
}

XML/JSON/YAML/ProtoBuf 渲染

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

    // gin.H 是 map[string]interface{} 的一种快捷方式
    r.GET("/someJSON", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
    })

    r.GET("/moreJSON", func(c *gin.Context) {
        // 你也可以使用一个结构体
        var msg struct {
            Name    string `json:"user"`
            Message string
            Number  int
        }
        msg.Name = "Lena"
        msg.Message = "hey"
        msg.Number = 
        // 注意 msg.Name 在 JSON 中变成了 "user"
        // 将输出：{"user": "Lena", "Message": "hey", "Number": }
        c.JSON(http.StatusOK, msg)
    })

    r.GET("/someXML", func(c *gin.Context) {
        c.XML(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
    })

    r.GET("/someYAML", func(c *gin.Context) {
        c.YAML(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
    })

    r.GET("/someProtoBuf", func(c *gin.Context) {
        reps := []int64{int64(1), int64(2)}
        label := "test"
        // protobuf 的具体定义写在 testdata/protoexample 文件中。
        data := &protoexample.Test{
            Label: &label,
            Reps:  reps,
        }
        // 请注意，数据在响应中变为二进制数据
        // 将输出被 protoexample.Test protobuf 序列化了的数据
        c.ProtoBuf(http.StatusOK, data)
    })

    // 监听并在 : 上启动服务
    r.Run(":")
}

上传文件

本节列出了上传图片的 api 用法。

单文件

参考 issue # 和详细示例代码.

func main() {
    router := gin.Default()
    // 为 multipart forms 设置较低的内存限制 (默认是  MiB)
    router.MaxMultipartMemory = 8 <<   // 8 MiB
    router.POST("/upload", func(c *gin.Context) {
        // 单文件
        file, _ := c.FormFile("file")
        log.Println(file.Filename)

        // 上传文件至指定目录
        c.SaveUploadedFile(file, dst)

        c.String(http.StatusOK, fmt.Sprintf("'%s' uploaded!", file.Filename))
    })
    router.Run(":")
}

如何使用 curl：

curl -X POST http://localhost:/upload \
  -F "file=@/Users/appleboy/test.zip" \
  -H "Content-Type: multipart/form-data"

多文件

查看详细示例代码.

func main() {
    router := gin.Default()
    // 为 multipart forms 设置较低的内存限制 (默认是  MiB)
    router.MaxMultipartMemory = 8 <<   // 8 MiB
    router.POST("/upload", func(c *gin.Context) {
        // Multipart form
        form, _ := c.MultipartForm()
        files := form.File["upload[]"]

        for _, file := range files {
            log.Println(file.Filename)

            // 上传文件至指定目录
            c.SaveUploadedFile(file, dst)
        }
        c.String(http.StatusOK, fmt.Sprintf("%d files uploaded!", len(files)))
    })
    router.Run(":")
}

如何使用 curl:

curl -X POST http://localhost:/upload \
  -F "upload[]=@/Users/appleboy/test1.zip" \
  -F "upload[]=@/Users/appleboy/test2.zip" \
  -H "Content-Type: multipart/form-data"

不使用默认的中间件

使用

r := gin.New()

代替

// Default 使用 Logger 和 Recovery 中间件
r := gin.Default()

从 reader 读取数据

func main() {
    router := gin.Default()
    router.GET("/someDataFromReader", func(c *gin.Context) {
        response, err := http.Get("https://raw.githubusercontent.com/gin-gonic/logo/master/color.png")
        if err != nil || response.StatusCode != http.StatusOK {
            c.Status(http.StatusServiceUnavailable)
            return
        }

        reader := response.Body
        contentLength := response.ContentLength
        contentType := response.Header.Get("Content-Type")

        extraHeaders := map[string]string{
            "Content-Disposition": `attachment; filename="gopher.png"`,
        }

        c.DataFromReader(http.StatusOK, contentLength, contentType, reader, extraHeaders)
    })
    router.Run(":")
}

优雅地重启或停止

你想优雅地重启或停止 web 服务器吗？有一些方法可以做到这一点。

我们可以使用 fvbock/endless 来替换默认的 ListenAndServe。更多详细信息，请参阅 issue #。

router := gin.Default()
router.GET("/", handler)
// [...]
endless.ListenAndServe(":", router)

替代方案:

manners：可以优雅关机的 Go Http 服务器。
graceful：Graceful 是一个 Go 扩展包，可以优雅地关闭 http.Handler 服务器。
grace：Go 服务器平滑重启和零停机时间部署。

如果你使用的是 Go ，可以不需要这些库！考虑使用 http.Server 内置的 Shutdown() 方法优雅地关机. 请参阅 gin 完整的 graceful-shutdown 示例。

// +build go1.8

package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "time"

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

func main() {
    router := gin.Default()
    router.GET("/", func(c *gin.Context) {
        time.Sleep(5 * time.Second)
        c.String(http.StatusOK, "Welcome Gin Server")
    })

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

    go func() {
        // 服务连接
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatalf("listen: %s\n", err)
        }
    }()

    // 等待中断信号以优雅地关闭服务器（设置 5 秒的超时时间）
    quit := make(chan os.Signal)
    signal.Notify(quit, os.Interrupt)
    <-quit
    log.Println("Shutdown Server ...")

    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    if err := srv.Shutdown(ctx); err != nil {
        log.Fatal("Server Shutdown:", err)
    }
    log.Println("Server exiting")
}

使用 BasicAuth 中间件

// 模拟一些私人数据
var secrets = gin.H{
    "foo":    gin.H{"email": "foo@bar.com", "phone": ""},
    "austin": gin.H{"email": "austin@example.com", "phone": ""},
    "lena":   gin.H{"email": "lena@guapa.com", "phone": ""},
}

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

    // 路由组使用 gin.BasicAuth() 中间件
    // gin.Accounts 是 map[string]string 的一种快捷方式
    authorized := r.Group("/admin", gin.BasicAuth(gin.Accounts{
        "foo":    "bar",
        "austin": "",
        "lena":   "hello2",
        "manu":   "",
    }))

    // /admin/secrets 端点
    // 触发 "localhost:/admin/secrets
    authorized.GET("/secrets", func(c *gin.Context) {
        // 获取用户，它是由 BasicAuth 中间件设置的
        user := c.MustGet(gin.AuthUserKey).(string)
        if secret, ok := secrets[user]; ok {
            c.JSON(http.StatusOK, gin.H{"user": user, "secret": secret})
        } else {
            c.JSON(http.StatusOK, gin.H{"user": user, "secret": "NO SECRET :("})
        }
    })

    // 监听并在 : 上启动服务
    r.Run(":")
}

使用 HTTP 方法

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

    // 使用默认中间件（logger 和 recovery 中间件）创建 gin 路由
    router := gin.Default()

    router.GET("/someGet", getting)
    router.POST("/somePost", posting)
    router.PUT("/somePut", putting)
    router.DELETE("/someDelete", deleting)
    router.PATCH("/somePatch", patching)
    router.HEAD("/someHead", head)
    router.OPTIONS("/someOptions", options)

    // 默认在  端口启动服务，除非定义了一个 PORT 的环境变量。
    router.Run()
    // router.Run(":") hardcode 端口号
}

使用中间件

func main() {
    // 新建一个没有任何默认中间件的路由
    r := gin.New()

    // 全局中间件
    // Logger 中间件将日志写入 gin.DefaultWriter，即使你将 GIN_MODE 设置为 release。
    // By default gin.DefaultWriter = os.Stdout
    r.Use(gin.Logger())

    // Recovery 中间件会 recover 任何 panic。如果有 panic 的话，会写入 。
    r.Use(gin.Recovery())

    // 你可以为每个路由添加任意数量的中间件。
    r.GET("/benchmark", MyBenchLogger(), benchEndpoint)

    // 认证路由组
    // authorized := r.Group("/", AuthRequired())
    // 和使用以下两行代码的效果完全一样:
    authorized := r.Group("/")
    // 路由组中间件! 在此例中，我们在 "authorized" 路由组中使用自定义创建的 
    // AuthRequired() 中间件
    authorized.Use(AuthRequired())
    {
        authorized.POST("/login", loginEndpoint)
        authorized.POST("/submit", submitEndpoint)
        authorized.POST("/read", readEndpoint)

        // 嵌套路由组
        testing := authorized.Group("testing")
        testing.GET("/analytics", analyticsEndpoint)
    }

    // 监听并在 : 上启动服务
    r.Run(":")
}

只绑定 url 查询字符串

ShouldBindQuery 函数只绑定 url 查询参数而忽略 post 数据。参阅详细信息.

package main

import (
    "log"

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

type Person struct {
    Name    string `form:"name"`
    Address string `form:"address"`
}

func main() {
    route := gin.Default()
    route.Any("/testing", startPage)
    route.Run(":")
}

func startPage(c *gin.Context) {
    var person Person
    if c.ShouldBindQuery(&person) == nil {
        log.Println("====== Only Bind By Query String ======")
        log.Println(person.Name)
        log.Println(person.Address)
    }
    c.String, "Success")
}

在中间件中使用 Goroutine

当在中间件或 handler 中启动新的 Goroutine 时，不能使用原始的上下文，必须使用只读副本。

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

    r.GET("/long_async", func(c *gin.Context) {
        // 创建在 goroutine 中使用的副本
        cCp := c.Copy()
        go func() {
            // 用 time.Sleep() 模拟一个长任务。
            time.Sleep(5 * time.Second)

            // 请注意您使用的是复制的上下文 "cCp"，这一点很重要
            log.Println("Done! in path " + cCp.Request.URL.Path)
        }()
    })

    r.GET("/long_sync", func(c *gin.Context) {
        // 用 time.Sleep() 模拟一个长任务。
        time.Sleep(5 * time.Second)

        // 因为没有使用 goroutine，不需要拷贝上下文
        log.Println("Done! in path " + c.Request.URL.Path)
    })

    // 监听并在 : 上启动服务
    r.Run(":")
}

多模板

Gin 默认允许只使用一个 html 模板。查看多模板渲染以使用 go block template 等功能。

如何记录日志

func main() {
    // 禁用控制台颜色，将日志写入文件时不需要控制台颜色。
    gin.DisableConsoleColor()

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

    // 如果需要同时将日志写入文件和控制台，请使用以下代码。
    // gin.DefaultWriter = io.MultiWriter(f, os.Stdout)

    router := gin.Default()
    router.GET("/ping", func(c *gin.Context) {
        c.String, "pong")
    })

    router.Run(":")
}

定义路由日志的格式

默认的路由日志格式：

[GIN-debug] POST   /foo                      --> main.main.func1 (3 handlers)
[GIN-debug] GET    /bar                      --> main.main.func2 (3 handlers)
[GIN-debug] GET    /status                   --> main.main.func3 (3 handlers)

如果你想要以指定的格式（例如 JSON，key values 或其他格式）记录信息，则可以使用 gin.DebugPrintRouteFunc 指定格式。在下面的示例中，我们使用标准日志包记录所有路由，但你可以使用其他满足你需求的日志工具。

import (
    "log"
    "net/http"

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

func main() {
    r := gin.Default()
    gin.DebugPrintRouteFunc = func(httpMethod, absolutePath, handlerName string, nuHandlers int) {
        log.Printf("endpoint %v %v %v %v\n", httpMethod, absolutePath, handlerName, nuHandlers)
    }

    r.POST("/foo", func(c *gin.Context) {
        c.JSON(http.StatusOK, "foo")
    })

    r.GET("/bar", func(c *gin.Context) {
        c.JSON(http.StatusOK, "bar")
    })

    r.GET("/status", func(c *gin.Context) {
        c.JSON(http.StatusOK, "ok")
    })

    // 监听并在 : 上启动服务
    r.Run()
}

将 request body 绑定到不同的结构体中

一般通过调用 c.Request.Body 方法绑定数据，但不能多次调用这个方法。

type formA struct {
  Foo string `json:"foo" xml:"foo" binding:"required"`
}

type formB struct {
  Bar string `json:"bar" xml:"bar" binding:"required"`
}

func SomeHandler(c *gin.Context) {
  objA := formA{}
  objB := formB{}
  // c.ShouldBind 使用了 c.Request.Body，不可重用。
  if errA := c.ShouldBind(&objA); errA == nil {
    c.String(http.StatusOK, `the body should be formA`)
  // 因为现在 c.Request.Body 是 EOF，所以这里会报错。
  } else if errB := c.ShouldBind(&objB); errB == nil {
    c.String(http.StatusOK, `the body should be formB`)
  } else {
    ...
  }
}

要想多次绑定，可以使用 c.ShouldBindBodyWith.

func SomeHandler(c *gin.Context) {
  objA := formA{}
  objB := formB{}
  // 读取 c.Request.Body 并将结果存入上下文。
  if errA := c.ShouldBindBodyWith(&objA, binding.JSON); errA == nil {
    c.String(http.StatusOK, `the body should be formA`)
  // 这时, 复用存储在上下文中的 body。
  } else if errB := c.ShouldBindBodyWith(&objB, binding.JSON); errB == nil {
    c.String(http.StatusOK, `the body should be formB JSON`)
  // 可以接受其他格式
  } else if errB2 := c.ShouldBindBodyWith(&objB, binding.XML); errB2 == nil {
    c.String(http.StatusOK, `the body should be formB XML`)
  } else {
    ...
  }
}

c.ShouldBindBodyWith 会在绑定之前将 body 存储到上下文中。这会对性能造成轻微影响，如果调用一次就能完成绑定的话，那就不要用这个方法。
只有某些格式需要此功能，如 JSON, XML, MsgPack, ProtoBuf。对于其他格式, 如 Query, Form, FormPost, FormMultipart 可以多次调用 c.ShouldBind() 而不会造成任任何性能损失 (详见 #)。

控制日志输出颜色

根据检测到的 TTY，控制台的日志输出默认是有颜色的。

禁止日志颜色化:

func main() {
    // 禁止日志的颜色
    gin.DisableConsoleColor()

    // 用默认中间件创建一个 gin 路由:
    // 日志和恢复（无崩溃）中间件
    router := gin.Default()

    router.GET("/ping", func(c *gin.Context) {
        c.String, "pong")
    })

    router.Run(":")
}

日志颜色化:

func main() {
    // 强制日志颜色化
    gin.ForceConsoleColor()

    // 用默认中间件创建一个 gin 路由:
    // 日志和恢复（无崩溃）中间件
    router := gin.Default()

    router.GET("/ping", func(c *gin.Context) {
        c.String, "pong")
    })

    router.Run(":")
}

支持 Let's Encrypt

一行代码支持 LetsEncrypt HTTPS servers 示例。

package main

import (
    "log"

    "github.com/gin-gonic/autotls"
    "github.com/gin-gonic/gin"
)

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

    // Ping handler
    r.GET("/ping", func(c *gin.Context) {
        c.String, "pong")
    })

    log.Fatal(autotls.Run(r, "example1.com", "example2.com"))
}

自定义 autocert manager 示例。

package main

import (
    "log"

    "github.com/gin-gonic/autotls"
    "github.com/gin-gonic/gin"
    "golang.org/x/crypto/acme/autocert"
)

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

    // Ping handler
    r.GET("/ping", func(c *gin.Context) {
        c.String, "pong")
    })

    m := autocert.Manager{
        Prompt:     autocert.AcceptTOS,
        HostPolicy: autocert.HostWhitelist("example1.com", "example2.com"),
        Cache:      autocert.DirCache("/var/www/.cache"),
    }

    log.Fatal(autotls.RunWithManager(r, &m))
}

映射查询字符串或表单参数

POST /post?ids[a]=&ids[b]=hello HTTP/
Content-Type: application/x-www-form-urlencoded

names[first]=thinkerou&names[second]=tianou
func main() {
    router := gin.Default()

    router.POST("/post", func(c *gin.Context) {

        ids := c.QueryMap("ids")
        names := c.PostFormMap("names")

        fmt.Printf("ids: %v; names: %v", ids, names)
    })
    router.Run(":")
}
ids: map[b:hello a:], names: map[second:tianou first:thinkerou]

查询字符串参数

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

    // 使用现有的基础请求对象解析查询字符串参数。
    // 示例 URL： /welcome?firstname=Jane&lastname=Doe
    router.GET("/welcome", func(c *gin.Context) {
        firstname := c.DefaultQuery("firstname", "Guest")
        lastname := c.Query("lastname") // c.Request.URL.Query().Get("lastname") 的一种快捷方式

        c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
    })
    router.Run(":")
}

模型绑定和验证

要将请求体绑定到结构体中，使用模型绑定。 Gin目前支持JSON、XML、YAML和标准表单值的绑定（foo=bar＆boo=baz）。

Gin使用
go-playground/validator.v8 进行验证。查看标签用法的全部文档.

使用时，需要在要绑定的所有字段上，设置相应的tag。例如，使用 JSON 绑定时，设置字段标签为 json:"fieldname"。

Gin提供了两类绑定方法：

Type

- Must bind

Methods - Bind, BindJSON, BindXML, BindQuery, BindYAML
Behavior - 这些方法属于 MustBindWith 的具体调用。如果发生绑定错误，则请求终止，并触发 c.AbortWithError, err).SetType(ErrorTypeBind)。响应状态码被设置为并且 Content-Type 被设置为 text/plain; charset=utf-8。如果您在此之后尝试设置响应状态码，Gin会输出日志 [GIN-debug] [WARNING] Headers were already written. Wanted to override status code with 。如果您希望更好地控制绑定，考虑使用 ShouldBind 等效方法。
Type

- Should bind

Methods - ShouldBind, ShouldBindJSON, ShouldBindXML, ShouldBindQuery, ShouldBindYAML
Behavior - 这些方法属于 ShouldBindWith 的具体调用。如果发生绑定错误，Gin 会返回错误并由开发者处理错误和请求。

使用 Bind 方法时，Gin 会尝试根据 Content-Type 推断如何绑定。如果你明确知道要绑定什么，可以使用 MustBindWith 或 ShouldBindWith。

你也可以指定必须绑定的字段。如果一个字段的 tag 加上了 binding:"required"，但绑定时是空值, Gin 会报错。

// 绑定 JSON
type Login struct {
    User     string `form:"user" json:"user" xml:"user"  binding:"required"`
    Password string `form:"password" json:"password" xml:"password" binding:"required"`
}

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

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

    // 绑定 XML (
    //  
    //  
    //      user
    //      
    //  )
    router.POST("/loginXML", func(c *gin.Context) {
        var xml Login
        if err := c.ShouldBindXML(&xml); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        
        if xml.User != "manu" || xml.Password != "" {
            c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
            return
        } 
        
        c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
    })

    // 绑定 HTML 表单 (user=manu&password=)
    router.POST("/loginForm", func(c *gin.Context) {
        var form Login
        // 根据 Content-Type Header 推断使用哪个绑定器。
        if err := c.ShouldBind(&form); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        
        if form.User != "manu" || form.Password != "" {
            c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
            return
        } 
        
        c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
    })

    // 监听并在 : 上启动服务
    router.Run(":")
}

示例请求

$ curl -v -X POST \
  http://localhost:/loginJSON \
  -H 'content-type: application/json' \
  -d '{ "user": "manu" }'
> POST /loginJSON HTTP/
> Host: localhost:
> User-Agent: curl/
> Accept: */*
> content-type: application/json
> Content-Length: 
>
* upload completely sent off:  out of  bytes
< HTTP/ Bad Request
< Content-Type: application/json; charset=utf-8
< Date: Fri,  Aug :: GMT
< Content-Length: 
<
{"error":"Key: 'Login.Password' Error:Field validation for 'Password' failed on the 'required' tag"}

忽略验证

使用上述的 curl 命令运行上面的示例时会返回错误。因为示例中 Password 使用了 binding:"required"。如果 Password 使用 binding:"-"，再次运行上面的示例就不会返回错误。

绑定 HTML 复选框

参见详细信息

main.go

...

type myForm struct {
    Colors []string `form:"colors[]"`
}

...

func formHandler(c *gin.Context) {
    var fakeForm myForm
    c.ShouldBind(&fakeForm)
    c.JSON, gin.H{"color": fakeForm.Colors})
}

...

form.html


    Check some colors
    Red
    
    Green
    
    Blue

结果:

{"color":["red","green","blue"]}

绑定 Uri

查看详细信息.

package main

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

type Person struct {
    ID string `uri:"id" binding:"required,uuid"`
    Name string `uri:"name" binding:"required"`
}

func main() {
    route := gin.Default()
    route.GET("/:name/:id", func(c *gin.Context) {
        var person Person
        if err := c.ShouldBindUri(&person); err != nil {
            c.JSON, gin.H{"msg": err})
            return
        }
        c.JSON, gin.H{"name": person.Name, "uuid": person.ID})
    })
    route.Run(":")
}

测试:

$ curl -v localhost:/thinkerou/987fbc97-4bed--9f07-9141ba07c9f3
$ curl -v localhost:/thinkerou/not-uuid

绑定查询字符串或表单数据

查看详细信息。

package main

import (
    "log"
    "time"

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

type Person struct {
    Name     string    `form:"name"`
    Address  string    `form:"address"`
    Birthday time.Time `form:"birthday" time_format:"" time_utc:"1"`
}

func main() {
    route := gin.Default()
    route.GET("/testing", startPage)
    route.Run(":")
}

func startPage(c *gin.Context) {
    var person Person
    // 如果是 `GET` 请求，只使用 `Form` 绑定引擎（`query`）。
    // 如果是 `POST` 请求，首先检查 `content-type` 是否为 `JSON` 或 `XML`，然后再使用 `Form`（`form-data`）。
    // 查看更多：https://github.com/gin-gonic/gin/blob/master/binding/binding.go#L48
    if c.ShouldBind(&person) == nil {
        log.Println(person.Name)
        log.Println(person.Address)
        log.Println(person.Birthday)
    }

    c.String, "Success")
}

测试：

$ curl -X GET "localhost:/testing?name=appleboy&address=xyz&birthday="

绑定表单数据至自定义结构体

以下示例使用自定义结构体：

type StructA struct {
    FieldA string `form:"field_a"`
}

type StructB struct {
    NestedStruct StructA
    FieldB string `form:"field_b"`
}

type StructC struct {
    NestedStructPointer *StructA
    FieldC string `form:"field_c"`
}

type StructD struct {
    NestedAnonyStruct struct {
        FieldX string `form:"field_x"`
    }
    FieldD string `form:"field_d"`
}

func GetDataB(c *gin.Context) {
    var b StructB
    c.Bind(&b)
    c.JSON, gin.H{
        "a": b.NestedStruct,
        "b": b.FieldB,
    })
}

func GetDataC(c *gin.Context) {
    var b StructC
    c.Bind(&b)
    c.JSON, gin.H{
        "a": b.NestedStructPointer,
        "c": b.FieldC,
    })
}

func GetDataD(c *gin.Context) {
    var b StructD
    c.Bind(&b)
    c.JSON, gin.H{
        "x": b.NestedAnonyStruct,
        "d": b.FieldD,
    })
}

func main() {
    r := gin.Default()
    r.GET("/getb", GetDataB)
    r.GET("/getc", GetDataC)
    r.GET("/getd", GetDataD)

    r.Run()
}

使用 curl 命令结果：

$ curl "http://localhost:/getb?field_a=hello&field_b=world"
{"a":{"FieldA":"hello"},"b":"world"}
$ curl "http://localhost:/getc?field_a=hello&field_c=world"
{"a":{"FieldA":"hello"},"c":"world"}
$ curl "http://localhost:/getd?field_x=hello&field_d=world"
{"d":"world","x":{"FieldX":"hello"}}

注意：不支持以下格式结构体：

type StructX struct {
    X struct {} `form:"name_x"` // 有 form
}

type StructY struct {
    Y StructX `form:"name_y"` // 有 form
}

type StructZ struct {
    Z *StructZ `form:"name_z"` // 有 form
}

总之, 目前仅支持没有 form 的嵌套结构体。

自定义 HTTP 配置

直接使用 http.ListenAndServe()，如下所示：

func main() {
    router := gin.Default()
    http.ListenAndServe(":", router)
}

或

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

    s := &http.Server{
        Addr:           ":",
        Handler:        router,
        ReadTimeout:     * time.Second,
        WriteTimeout:    * time.Second,
        MaxHeaderBytes: 1 << ,
    }
    s.ListenAndServe()
}

自定义中间件

func Logger() gin.HandlerFunc {
    return func(c *gin.Context) {
        t := time.Now()

        // 设置 example 变量
        c.Set("example", "")

        // 请求前

        c.Next()

        // 请求后
        latency := time.Since(t)
        log.Print(latency)

        // 获取发送的 status
        status := c.Writer.Status()
        log.Println(status)
    }
}

func main() {
    r := gin.New()
    r.Use(Logger())

    r.GET("/test", func(c *gin.Context) {
        example := c.MustGet("example").(string)

        // 打印：""
        log.Println(example)
    })

    // 监听并在 : 上启动服务
    r.Run(":")
}

自定义验证器

注册自定义验证器，查看示例代码.

package main

import (
    "net/http"
    "reflect"
    "time"

    "github.com/gin-gonic/gin"
    "github.com/gin-gonic/gin/binding"
    "github.com/go-playground/validator/v10"
)

// Booking 包含绑定和验证的数据。
type Booking struct {
    CheckIn  time.Time `form:"check_in" binding:"required,bookabledate" time_format:""`
    CheckOut time.Time `form:"check_out" binding:"required,gtfield=CheckIn,bookabledate" time_format:""`
}

var bookableDate validator.Func = func(fl validator.FieldLevel) bool {
    date, ok := fl.Field().Interface().(time.Time)
    if ok {
        today := time.Now()
        if today.After(date) {
            return false
        }
    }
    return true
}

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

    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
        v.RegisterValidation("bookabledate", bookableDate)
    }

    route.GET("/bookable", getBookable)
    route.Run(":")
}

func getBookable(c *gin.Context) {
    var b Booking
    if err := c.ShouldBindWith(&b, binding.Query); err == nil {
        c.JSON(http.StatusOK, gin.H{"message": "Booking dates are valid!"})
    } else {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
    }
}
$ curl "localhost:/bookable?check_in=&check_out="
{"message":"Booking dates are valid!"}

$ curl "localhost:/bookable?check_in=&check_out="
{"error":"Key: 'Booking.CheckIn' Error:Field validation for 'CheckIn' failed on the 'bookabledate' tag"}

结构体级别的验证器也可以通过其他的方式注册。更多信息请参阅 struct-lvl-validation 示例。

设置和获取 Cookie

import (
    "fmt"

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

func main() {

    router := gin.Default()

    router.GET("/cookie", func(c *gin.Context) {

        cookie, err := c.Cookie("gin_cookie")

        if err != nil {
            cookie = "NotSet"
            c.SetCookie("gin_cookie", "test", , "/", "localhost", false, true)
        }

        fmt.Printf("Cookie value: %s \n", cookie)
    })

    router.Run()
}

路由参数

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

    // 此 handler 将匹配 /user/john 但不会匹配 /user/ 或者 /user
    router.GET("/user/:name", func(c *gin.Context) {
        name := c.Param("name")
        c.String(http.StatusOK, "Hello %s", name)
    })

    // 此 handler 将匹配 /user/john/ 和 /user/john/send
    // 如果没有其他路由匹配 /user/john，它将重定向到 /user/john/
    router.GET("/user/:name/*action", func(c *gin.Context) {
        name := c.Param("name")
        action := c.Param("action")
        message := name + " is " + action
        c.String(http.StatusOK, message)
    })

    router.Run(":")
}

路由组

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

    // 简单的路由组: v1
    v1 := router.Group("/v1")
    {
        v1.POST("/login", loginEndpoint)
        v1.POST("/submit", submitEndpoint)
        v1.POST("/read", readEndpoint)
    }

    // 简单的路由组: v2
    v2 := router.Group("/v2")
    {
        v2.POST("/login", loginEndpoint)
        v2.POST("/submit", submitEndpoint)
        v2.POST("/read", readEndpoint)
    }

    router.Run(":")
}

运行多个服务

请参阅 issues 并尝试以下示例：

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/gin-gonic/gin"
    "golang.org/x/sync/errgroup"
)

var (
    g errgroup.Group
)

func router01() http.Handler {
    e := gin.New()
    e.Use(gin.Recovery())
    e.GET("/", func(c *gin.Context) {
        c.JSON(
            http.StatusOK,
            gin.H{
                "code":  http.StatusOK,
                "error": "Welcome server ",
            },
        )
    })

    return e
}

func router02() http.Handler {
    e := gin.New()
    e.Use(gin.Recovery())
    e.GET("/", func(c *gin.Context) {
        c.JSON(
            http.StatusOK,
            gin.H{
                "code":  http.StatusOK,
                "error": "Welcome server ",
            },
        )
    })

    return e
}

func main() {
    server01 := &http.Server{
        Addr:         ":",
        Handler:      router01(),
        ReadTimeout:  5 * time.Second,
        WriteTimeout:  * time.Second,
    }

    server02 := &http.Server{
        Addr:         ":",
        Handler:      router02(),
        ReadTimeout:  5 * time.Second,
        WriteTimeout:  * time.Second,
    }

    g.Go(func() error {
        return server01.ListenAndServe()
    })

    g.Go(func() error {
        return server02.ListenAndServe()
    })

    if err := g.Wait(); err != nil {
        log.Fatal(err)
    }
}

重定向

HTTP 重定向很容易。内部、外部重定向均支持。

r.GET("/test", func(c *gin.Context) {
    c.Redirect(http.StatusMovedPermanently, "http://www.google.com/")
})

通过 POST 方法进行 HTTP 重定向。请参考 issue：#

r.POST("/test", func(c *gin.Context) {
    c.Redirect(http.StatusFound, "/foo")
})

路由重定向，使用 HandleContext：

r.GET("/test", func(c *gin.Context) {
    c.Request.URL.Path = "/test2"
    r.HandleContext(c)
})
r.GET("/test2", func(c *gin.Context) {
    c.JSON, gin.H{"hello": "world"})
})

静态文件服务

func main() {
    router := gin.Default()
    router.Static("/assets", "./assets")
    router.StaticFS("/more_static", http.Dir("my_file_system"))
    router.StaticFile("/favicon.ico", "./resources/favicon.ico")

    // 监听并在 : 上启动服务
    router.Run(":")
}

静态资源嵌入

你可以使用 go-assets 将静态资源打包到可执行文件中。

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

    t, err := loadTemplate()
    if err != nil {
        panic(err)
    }
    r.SetHTMLTemplate(t)

    r.GET("/", func(c *gin.Context) {
        c.HTML(http.StatusOK, "/html/index.tmpl", nil)
    })
    r.Run(":")
}

// loadTemplate 加载由 go-assets-builder 嵌入的模板
func loadTemplate() (*template.Template, error) {
    t := template.New("")
    for name, file := range Assets.Files {
        if file.IsDir() || !strings.HasSuffix(name, ".tmpl") {
            continue
        }
        h, err := ioutil.ReadAll(file)
        if err != nil {
            return nil, err
        }
        t, err = t.New(name).Parse(string(h))
        if err != nil {
            return nil, err
        }
    }
    return t, nil
}

请参阅 examples/assets-in-binary 目录中的完整示例。

安装_Gin中文文档_安装gz文件

示例

AsciiJSON

HTML 渲染

{{ .title }}

{{ .title }}

{{ .title }}

自定义模板渲染器

自定义分隔符

自定义模板功能

HTTP2 server 推送

Welcome, Ginner!

JSONP

Multipart/Urlencoded 绑定

Multipart/Urlencoded 表单

PureJSON

Query 和 post form

SecureJSON

XML/JSON/YAML/ProtoBuf 渲染

上传文件

单文件

多文件

不使用默认的中间件

从 reader 读取数据

优雅地重启或停止

使用 BasicAuth 中间件

使用 HTTP 方法

使用中间件

只绑定 url 查询字符串

在中间件中使用 Goroutine

多模板

如何记录日志

定义路由日志的格式

将 request body 绑定到不同的结构体中

控制日志输出颜色

支持 Let's Encrypt

映射查询字符串或表单参数

查询字符串参数

模型绑定和验证

示例请求

忽略验证

绑定 HTML 复选框

绑定 Uri

绑定查询字符串或表单数据

绑定表单数据至自定义结构体

自定义 HTTP 配置

自定义中间件

自定义验证器

设置和获取 Cookie

路由参数

路由组

运行多个服务

重定向

静态文件服务

静态资源嵌入