---- url: https://gin-gonic.com/en/docs/routing/grouping-routes/ ---- [Skip to content](#_top) # Grouping routes Route groups let you organize related routes under a shared URL prefix. This is useful for: * **API versioning** – group all v1 endpoints under `/v1` and v2 endpoints under `/v2`. * **Shared middleware** – apply authentication, logging, or rate-limiting to an entire set of routes at once instead of attaching middleware to every route individually. * **Code organization** – keep related handlers visually grouped in your source code. ### Basic grouping [Section titled “Basic grouping”](#basic-grouping) ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) func loginEndpoint(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"action": "login"}) } func submitEndpoint(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"action": "submit"}) } func readEndpoint(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"action": "read"}) } func main() { router := gin.Default() // Simple group: v1 { v1 := router.Group("/v1") v1.POST("/login", loginEndpoint) v1.POST("/submit", submitEndpoint) v1.POST("/read", readEndpoint) } // Simple group: v2 { v2 := router.Group("/v2") v2.POST("/login", loginEndpoint) v2.POST("/submit", submitEndpoint) v2.POST("/read", readEndpoint) } router.Run(":8080") } ``` ### Applying middleware to a group [Section titled “Applying middleware to a group”](#applying-middleware-to-a-group) You can pass middleware to `router.Group()` or call `Use()` on a group. Every route in that group will run the middleware before its handler. ``` // AuthRequired is a placeholder for your auth middleware. func AuthRequired() gin.HandlerFunc { return func(c *gin.Context) { // ... check token, session, etc. c.Next() } } func main() { router := gin.Default() // Public routes -- no auth required public := router.Group("/api") { public.GET("/health", healthCheck) } // Private routes -- auth middleware applied to the whole group private := router.Group("/api") private.Use(AuthRequired()) { private.GET("/profile", getProfile) private.POST("/settings", updateSettings) } router.Run(":8080") } ``` ### Nested groups [Section titled “Nested groups”](#nested-groups) Groups can be nested to build deeper URL hierarchies while keeping middleware scoped appropriately. /api ``` func main() { router := gin.Default() api := router.Group("/api") { // /api/v1 v1 := api.Group("/v1") { // /api/v1/users users := v1.Group("/users") users.GET("/", listUsers) users.GET("/:id", getUser) // /api/v1/posts posts := v1.Group("/posts") posts.GET("/", listPosts) posts.GET("/:id", getPost) } } router.Run(":8080") } ``` Each level inherits the prefix of its parent, so the final routes become `/api/v1/users/`, `/api/v1/users/:id`, and so on. ---- url: https://gin-gonic.com/en/docs/deployment/ ---- [Skip to content](#_top) # Deployment Gin projects can be deployed easily on any cloud provider. ## [Railway](https://www.railway.com) [Section titled “Railway”](#railway) Railway is a cutting-edge cloud development platform for deploying, managing, and scaling applications and services. It simplifies your infrastructure stack from servers to observability with a single, scalable, easy-to-use platform. Follow the Railway [guide to deploy your Gin projects](https://docs.railway.com/guides/gin). ## [Seenode](https://seenode.com) [Section titled “Seenode”](#seenode) Seenode is a modern cloud platform designed specifically for developers who want to deploy applications quickly and efficiently. It offers git-based deployment, automatic SSL certificates, built-in databases, and a streamlined interface that gets your Gin applications live in minutes. Follow the Seenode [guide to deploy your Gin projects](https://seenode.com/docs/frameworks/go/gin). ## [Koyeb](https://www.koyeb.com) [Section titled “Koyeb”](#koyeb) Koyeb is a developer-friendly serverless platform to deploy apps globally with git-based deployment, TLS encryption, native autoscaling, a global edge network, and built-in service mesh & discovery. Follow the Koyeb [guide to deploy your Gin projects](https://www.koyeb.com/tutorials/deploy-go-gin-on-koyeb). ## [Qovery](https://www.qovery.com) [Section titled “Qovery”](#qovery) Qovery provides free Cloud hosting with databases, SSL, a global CDN, and automatic deploys with Git. See [Qovery](https://hub.qovery.com/guides/getting-started/deploy-your-first-application/) for more information. ## [Render](https://render.com) [Section titled “Render”](#render) Render is a modern cloud platform that offers native support for Go, fully managed SSL, databases, zero-downtime deploys, HTTP/2, and websocket support. Follow the Render [guide to deploying Gin projects](https://render.com/docs/deploy-go-gin). ## [Google App Engine](https://cloud.google.com/appengine/) [Section titled “Google App Engine”](#google-app-engine) GAE has two ways to deploy Go applications. The standard environment is easier to use but less customizable and prevents [syscalls](https://github.com/gin-gonic/gin/issues/1639) for security reasons. The flexible environment can run any framework or library. Learn more and pick your preferred environment at [Go on Google App Engine](https://cloud.google.com/appengine/docs/go/). ## Self Hosted [Section titled “Self Hosted”](#self-hosted) Gin projects can also be deployed in a self-hosted manner. Deployment architecture and security considerations vary depending on the target environment. The following section only presents a high level overview of configuration options to consider when planning the deployment. ## Configuration Options [Section titled “Configuration Options”](#configuration-options) Gin project deployments can be tuned by using environment variables or directly in code. The following environment variables are available for configuring Gin: | Environment Variable | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PORT | The TCP port to listen on when starting the Gin server with `router.Run()` (i.e. without any arguments). | | GIN\_MODE | Set to one of `debug`, `release`, or `test`. Handles management of Gin modes, such as when to emit debug outputs. Can also be set in code using `gin.SetMode(gin.ReleaseMode)` or `gin.SetMode(gin.TestMode)` | The following code can be used to configure Gin. ``` // Don't specify the bind address or port for Gin. Defaults to binding on all interfaces on port 8080. // Can use the `PORT` environment variable to change the listen port when using `Run()` without any arguments. router := gin.Default() router.Run() // Specify the bind address and port for Gin. router := gin.Default() router.Run("192.168.1.100:8080") // Specify only the listen port. Will bind on all interfaces. router := gin.Default() router.Run(":8080") // Set which IP addresses or CIDRs, are considered to be trusted for setting headers to document real client IP addresses. // See the documentation for additional details. router := gin.Default() router.SetTrustedProxies([]string{"192.168.1.2"}) ``` For information on configuring trusted proxies, see [Trusted Proxies](/en/docs/server-config/trusted-proxies/). ---- url: https://gin-gonic.com/en/docs/rendering/serving-static-files/ ---- [Skip to content](#_top) # Serving static files Gin provides three methods for serving static content: * **`router.Static(relativePath, root)`** — Serves an entire directory. Requests to `relativePath` are mapped to files under `root`. For example, `router.Static("/assets", "./assets")` serves `./assets/style.css` at `/assets/style.css`. * **`router.StaticFS(relativePath, fs)`** — Like `Static`, but accepts an `http.FileSystem` interface, giving you more control over how files are resolved. Use this when you need to serve files from an embedded filesystem or want to customize directory listing behavior. * **`router.StaticFile(relativePath, filePath)`** — Serves a single file. Useful for endpoints like `/favicon.ico` or `/robots.txt`. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) 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") // Listen and serve on 0.0.0.0:8080 router.Run(":8080") } ``` ---- url: https://gin-gonic.com/en/docs/logging/skip-logging/ ---- [Skip to content](#_top) # Skip logging You can skip logging for specific paths or based on custom logic using `LoggerConfig`. * `SkipPaths` excludes specific routes from logging — useful for health checks or metrics endpoints that generate noise. * `Skip` is a function that receives the `*gin.Context` and returns `true` to skip logging — useful for conditional logic like skipping successful responses. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { router := gin.New() // skip logging for desired paths by setting SkipPaths in LoggerConfig loggerConfig := gin.LoggerConfig{SkipPaths: []string{"/metrics"}} // skip logging based on your logic by setting Skip func in LoggerConfig loggerConfig.Skip = func(c *gin.Context) bool { // as an example skip non server side errors return c.Writer.Status() < http.StatusInternalServerError } router.Use(gin.LoggerWithConfig(loggerConfig)) router.Use(gin.Recovery()) // skipped -- path is in SkipPaths router.GET("/metrics", func(c *gin.Context) { c.Status(http.StatusNotImplemented) }) // skipped -- status < 500 router.GET("/ping", func(c *gin.Context) { c.String(http.StatusOK, "pong") }) // not skipped -- status is 501 (>= 500) router.GET("/data", func(c *gin.Context) { c.Status(http.StatusNotImplemented) }) router.Run(":8080") } ``` ## Test it [Section titled “Test it”](#test-it) Terminal window ``` # This request is logged (status 501 >= 500) curl http://localhost:8080/data # This request is NOT logged (path in SkipPaths) curl http://localhost:8080/metrics # This request is NOT logged (status 200 < 500) curl http://localhost:8080/ping # Output: pong ``` ## See also [Section titled “See also”](#see-also) * [Custom log format](/en/docs/logging/custom-log-format/) * [Write log](/en/docs/logging/write-log/) ---- url: https://gin-gonic.com/en/docs/rendering/bind-single-binary-with-template/ ---- [Skip to content](#_top) # Build a single binary with templates ## Using `//go:embed` (recommended) [Section titled “Using //go:embed (recommended)”](#using-goembed-recommended) Since Go 1.16, the standard library supports embedding files directly into the binary with the `//go:embed` directive. No third-party dependencies are needed. ``` package main import ( "embed" "html/template" "net/http" "github.com/gin-gonic/gin" ) //go:embed templates/* var templateFS embed.FS func main() { router := gin.Default() t := template.Must(template.ParseFS(templateFS, "templates/*.tmpl")) router.SetHTMLTemplate(t) router.GET("/", func(c *gin.Context) { c.HTML(http.StatusOK, "index.tmpl", nil) }) router.Run(":8080") } ``` ## Using a third-party package [Section titled “Using a third-party package”](#using-a-third-party-package) You can also use a third-party package such as [go-assets](https://github.com/jessevdk/go-assets) to embed templates into the binary. ``` func main() { router := gin.New() t, err := loadTemplate() if err != nil { panic(err) } router.SetHTMLTemplate(t) router.GET("/", func(c *gin.Context) { c.HTML(http.StatusOK, "/html/index.tmpl", nil) }) router.Run(":8080") } // loadTemplate loads templates embedded by 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 := io.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 } ``` See a complete example in the [assets-in-binary/example01](https://github.com/gin-gonic/examples/tree/master/assets-in-binary/example01) directory. ---- url: https://gin-gonic.com/en/docs/routing/upload-file/single-file/ ---- [Skip to content](#_top) # Single file Use `c.FormFile` to receive a single uploaded file from a `multipart/form-data` request, then `c.SaveUploadedFile` to save it to disk. You can control the maximum memory used during multipart parsing by setting `router.MaxMultipartMemory` (default is 32 MiB). Files larger than this limit are stored in temporary files on disk instead of memory. ``` package main import ( "fmt" "log" "net/http" "path/filepath" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() // Set a lower memory limit for multipart forms (default is 32 MiB) router.MaxMultipartMemory = 8 << 20 // 8 MiB router.POST("/upload", func(c *gin.Context) { // single file file, err := c.FormFile("file") if err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } log.Println(file.Filename) // Upload the file to specific dst. dst := filepath.Join("./files/", filepath.Base(file.Filename)) c.SaveUploadedFile(file, dst) c.String(http.StatusOK, fmt.Sprintf("'%s' uploaded!", file.Filename)) }) router.Run(":8080") } ``` ## Test it [Section titled “Test it”](#test-it) Terminal window ``` curl -X POST http://localhost:8080/upload \ -F "file=@/path/to/your/file.zip" \ -H "Content-Type: multipart/form-data" # Output: 'file.zip' uploaded! ``` ## See also [Section titled “See also”](#see-also) * [Multiple files](/en/docs/routing/upload-file/multiple-file/) * [Limit upload size](/en/docs/routing/upload-file/limit-bytes/) ---- url: https://gin-gonic.com/en/docs/binding/binding-and-validation/ ---- [Skip to content](#_top) # Model binding and validation To bind a request body into a type, use model binding. We currently support binding of JSON, XML, YAML and standard form values (foo=bar\&boo=baz). Gin uses [**go-playground/validator/v10**](https://github.com/go-playground/validator) for validation. Check the full docs on tags usage [here](https://pkg.go.dev/github.com/go-playground/validator/v10#hdr-Baked_In_Validators_and_Tags). Note that you need to set the corresponding binding tag on all fields you want to bind. For example, when binding from JSON, set `json:"fieldname"`. Also, Gin provides two sets of methods for binding: * **Type** - Must bind * **Methods** - `Bind`, `BindJSON`, `BindXML`, `BindQuery`, `BindYAML` * **Behavior** - These methods use `MustBindWith` under the hood. If there is a binding error, the request is aborted with `c.AbortWithError(400, err).SetType(ErrorTypeBind)`. This sets the response status code to 400 and the `Content-Type` header is set to `text/plain; charset=utf-8`. Note that if you try to set the response code after this, it will result in a warning `[GIN-debug] [WARNING] Headers were already written. Wanted to override status code 400 with 422`. If you wish to have greater control over the behavior, consider using the `ShouldBind` equivalent method. * **Type** - Should bind * **Methods** - `ShouldBind`, `ShouldBindJSON`, `ShouldBindXML`, `ShouldBindQuery`, `ShouldBindYAML` * **Behavior** - These methods use `ShouldBindWith` under the hood. If there is a binding error, the error is returned and it is the developer’s responsibility to handle the request and error appropriately. When using the Bind-method, Gin tries to infer the binder depending on the Content-Type header. If you are sure what you are binding, you can use `MustBindWith` or `ShouldBindWith`. You can also specify that specific fields are required. If a field is decorated with `binding:"required"` and has a empty value when binding, an error will be returned. If one of the struct fields is itself a struct (nested struct) the fields of that struct will also need to be decorated with `binding:"required"` in order to validate correctly. ``` // Binding from 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() // Example for binding JSON ({"user": "manu", "password": "123"}) 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 != "123" { c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"}) return } c.JSON(http.StatusOK, gin.H{"status": "you are logged in"}) }) // Example for binding XML ( // // // manu // 123 // ) 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 != "123" { c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"}) return } c.JSON(http.StatusOK, gin.H{"status": "you are logged in"}) }) // Example for binding a HTML form (user=manu&password=123) router.POST("/loginForm", func(c *gin.Context) { var form Login // This will infer what binder to use depending on the 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 != "123" { c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"}) return } c.JSON(http.StatusOK, gin.H{"status": "you are logged in"}) }) // Listen and serve on 0.0.0.0:8080 router.Run(":8080") } ``` ### Sample request [Section titled “Sample request”](#sample-request) Terminal window ``` $ curl -v -X POST \ http://localhost:8080/loginJSON \ -H 'content-type: application/json' \ -d '{ "user": "manu" }' > POST /loginJSON HTTP/1.1 > Host: localhost:8080 > User-Agent: curl/7.51.0 > Accept: */* > content-type: application/json > Content-Length: 18 > * upload completely sent off: 18 out of 18 bytes < HTTP/1.1 400 Bad Request < Content-Type: application/json; charset=utf-8 < Date: Fri, 04 Aug 2017 03:51:31 GMT < Content-Length: 100 < {"error":"Key: 'Login.Password' Error:Field validation for 'Password' failed on the 'required' tag"} ``` ### Skip validate [Section titled “Skip validate”](#skip-validate) When running the above example using the above the `curl` command, it returns error. Because the example use `binding:"required"` for `Password`. If use `binding:"-"` for `Password`, then it will not return error when running the above example again. ## See also [Section titled “See also”](#see-also) * [Custom validators](/en/docs/binding/custom-validators/) * [Bind query or post data](/en/docs/binding/bind-query-or-post/) ---- url: https://gin-gonic.com/en/docs/binding/bind-custom-unmarshaler/ ---- [Skip to content](#_top) # Bind custom unmarshaler To override Gin’s default binding logic, define a function on your type that satisfies the `encoding.TextUnmarshaler` interface from the Go standard library. Then specify `parser=encoding.TextUnmarshaler` in the `uri`/`form` tag of the field being bound. ``` package main import ( "encoding" "strings" "github.com/gin-gonic/gin" ) type Birthday string func (b *Birthday) UnmarshalText(text []byte) error { *b = Birthday(strings.Replace(string(text), "-", "/", -1)) return nil } var _ encoding.TextUnmarshaler = (*Birthday)(nil) func main() { route := gin.Default() var request struct { Birthday Birthday `form:"birthday,parser=encoding.TextUnmarshaler"` Birthdays []Birthday `form:"birthdays,parser=encoding.TextUnmarshaler" collection_format:"csv"` BirthdaysDefault []Birthday `form:"birthdaysDef,default=2020-09-01;2020-09-02,parser=encoding.TextUnmarshaler" collection_format:"csv"` } route.GET("/test", func(ctx *gin.Context) { _ = ctx.BindQuery(&request) ctx.JSON(200, request) }) _ = route.Run(":8088") } ``` Test it with: Terminal window ``` curl 'localhost:8088/test?birthday=2000-01-01&birthdays=2000-01-01,2000-01-02' ``` Result: Terminal window ``` {"Birthday":"2000/01/01","Birthdays":["2000/01/01","2000/01/02"],"BirthdaysDefault":["2020/09/01","2020/09/02"]} ``` > **Note:** If `parser=encoding.TextUnmarshaler` is specified for a type that does **not** implement `encoding.TextUnmarshaler`, Gin will ignore it and proceed with its default binding logic. ### Using BindUnmarshaler [Section titled “Using BindUnmarshaler”](#using-bindunmarshaler) If a type already implements `encoding.TextUnmarshaler` but you want to customize how Gin binds the type differently (e.g., to change what error message is returned), you can implement the dedicated `BindUnmarshaler` interface instead. ``` package main import ( "strings" "github.com/gin-gonic/gin" "github.com/gin-gonic/gin/binding" ) type Birthday string func (b *Birthday) UnmarshalParam(param string) error { *b = Birthday(strings.Replace(param, "-", "/", -1)) return nil } var _ binding.BindUnmarshaler = (*Birthday)(nil) func main() { route := gin.Default() var request struct { Birthday Birthday `form:"birthday"` Birthdays []Birthday `form:"birthdays" collection_format:"csv"` BirthdaysDefault []Birthday `form:"birthdaysDef,default=2020-09-01;2020-09-02" collection_format:"csv"` } route.GET("/test", func(ctx *gin.Context) { _ = ctx.BindQuery(&request) ctx.JSON(200, request) }) _ = route.Run(":8088") } ``` > **Note:** If a type implements both `encoding.TextUnmarshaler` and `BindUnmarshaler`, Gin will use `BindUnmarshaler` by default unless you specify `parser=encoding.TextUnmarshaler` in the binding tag. ---- url: https://gin-gonic.com/en/docs/rendering/ascii-json/ ---- [Skip to content](#_top) # AsciiJSON `AsciiJSON` serializes data to JSON but escapes all non-ASCII characters into `\uXXXX` Unicode escape sequences. HTML-special characters like `<` and `>` are also escaped. The result is a response body that contains only 7-bit ASCII characters. **When to use AsciiJSON:** * Your API consumers require strictly ASCII-safe responses (for example, systems that cannot handle UTF-8 encoded bytes). * You need to embed JSON inside contexts that only support ASCII, such as certain logging systems or legacy transports. * You want to ensure that characters like `<`, `>`, and `&` are escaped to avoid injection issues when JSON is embedded in HTML. For most modern APIs, standard `c.JSON()` is sufficient since it outputs valid UTF-8. Use `AsciiJSON` only when ASCII safety is a specific requirement. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() router.GET("/someJSON", func(c *gin.Context) { data := map[string]interface{}{ "lang": "GO语言", "tag": "
", } // will output : {"lang":"GO\u8bed\u8a00","tag":"\u003cbr\u003e"} c.AsciiJSON(http.StatusOK, data) }) // Listen and serve on 0.0.0.0:8080 router.Run(":8080") } ``` You can test this endpoint with curl: Terminal window ``` curl http://localhost:8080/someJSON # Output: {"lang":"GO\u8bed\u8a00","tag":"\u003cbr\u003e"} ``` Notice that the Chinese characters `语言` are replaced with `\u8bed\u8a00`, and the `
` tag becomes `\u003cbr\u003e`. The response body is safe to consume in any ASCII-only environment. ---- url: https://gin-gonic.com/en/docs/server-config/trusted-proxies/ ---- [Skip to content](#_top) # Trusted proxies Gin lets you specify which headers to hold the real client IP (if any), as well as specifying which proxies (or direct clients) you trust to specify one of these headers. ### Why trusted proxy configuration matters [Section titled “Why trusted proxy configuration matters”](#why-trusted-proxy-configuration-matters) When your application sits behind a reverse proxy (Nginx, HAProxy, a cloud load balancer, etc.), the proxy forwards the original client’s IP address in headers like `X-Forwarded-For` or `X-Real-Ip`. The problem is that **any client can set these headers**. Without proper trusted proxy configuration, an attacker can forge `X-Forwarded-For` to: * **Bypass IP-based access controls** – If your application restricts certain routes to an internal IP range (e.g., `10.0.0.0/8`), an attacker can send `X-Forwarded-For: 10.0.0.1` from a public IP and bypass the restriction entirely. * **Poison logs and audit trails** – Forged IPs make incident investigation unreliable because you can no longer trace requests back to the real source. * **Evade rate limiting** – If rate limiting is keyed on `ClientIP()`, each request can claim a different IP address to avoid being throttled. `SetTrustedProxies` solves this by telling Gin which network addresses are legitimate proxies. When `ClientIP()` parses the `X-Forwarded-For` chain, it only trusts entries added by those proxies and discards anything a client may have prepended. If a request arrives directly (not from a trusted proxy), the forwarding headers are ignored entirely and the raw remote address is used. Use function `SetTrustedProxies()` on your `gin.Engine` to specify network addresses or network CIDRs from where clients which their request headers related to client IP can be trusted. They can be IPv4 addresses, IPv4 CIDRs, IPv6 addresses or IPv6 CIDRs. **Attention:** Gin trusts all proxies by default if you don’t specify a trusted proxy using the function above, **this is NOT safe**. At the same time, if you don’t use any proxy, you can disable this feature by using `Engine.SetTrustedProxies(nil)`, then `Context.ClientIP()` will return the remote address directly to avoid some unnecessary computation. ``` import ( "fmt" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() router.SetTrustedProxies([]string{"192.168.1.2"}) router.GET("/", func(c *gin.Context) { // If the client is 192.168.1.2, use the X-Forwarded-For // header to deduce the original client IP from the trust- // worthy parts of that header. // Otherwise, simply return the direct client IP fmt.Printf("ClientIP: %s\n", c.ClientIP()) }) router.Run() } ``` **Notice:** If you are using a CDN service, you can set the `Engine.TrustedPlatform` to skip TrustedProxies check, it has a higher priority than TrustedProxies. Look at the example below: ``` import ( "fmt" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() // Use predefined header gin.PlatformXXX // Google App Engine router.TrustedPlatform = gin.PlatformGoogleAppEngine // Cloudflare router.TrustedPlatform = gin.PlatformCloudflare // Fly.io router.TrustedPlatform = gin.PlatformFlyIO // Or, you can set your own trusted request header. But be sure your CDN // prevents users from passing this header! For example, if your CDN puts // the client IP in X-CDN-Client-IP: router.TrustedPlatform = "X-CDN-Client-IP" router.GET("/", func(c *gin.Context) { // If you set TrustedPlatform, ClientIP() will resolve the // corresponding header and return IP directly fmt.Printf("ClientIP: %s\n", c.ClientIP()) }) router.Run() } ``` ---- url: https://gin-gonic.com/en/docs/server-config/graceful-restart-or-stop/ ---- [Skip to content](#_top) # Graceful restart or stop When a server process receives a termination signal (e.g., during a deployment or scaling event), an immediate shutdown drops all in-flight requests, leaving clients with broken connections and potentially corrupted operations. A **graceful shutdown** solves this by: * **Completing in-flight requests** – Requests that are already being processed are given time to finish, so clients receive proper responses instead of connection resets. * **Draining connections** – The server stops accepting new connections while existing ones are allowed to complete, preventing a sudden cut-off. * **Cleaning up resources** – Open database connections, file handles, and background workers are closed properly, avoiding data corruption or resource leaks. * **Enabling zero-downtime deployments** – When combined with a load balancer, graceful shutdown lets you roll out new versions without any user-visible errors. There are several ways to achieve this in Go. We can use [fvbock/endless](https://github.com/fvbock/endless) to replace the default `ListenAndServe`. Refer issue [#296](https://github.com/gin-gonic/gin/issues/296) for more details. \[...] ``` router := gin.Default() router.GET("/", handler) endless.ListenAndServe(":4242", router) ``` An alternative to endless: * [manners](https://github.com/braintree/manners): A polite Go HTTP server that shuts down gracefully. * [graceful](https://github.com/tylerb/graceful): Graceful is a Go package enabling graceful shutdown of an http.Handler server. * [grace](https://github.com/facebookgo/grace): Graceful restart & zero downtime deploy for Go servers. If you are using Go 1.8 and later, you may not need to use this library! Consider using `http.Server`’s built-in [Shutdown()](https://golang.org/pkg/net/http/#Server.Shutdown) method for graceful shutdowns. See the full [graceful-shutdown](https://github.com/gin-gonic/examples/tree/master/graceful-shutdown) example with gin. ``` //go:build go1.8 // +build go1.8 package main import ( "context" "log" "net/http" "os" "os/signal" "syscall" "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: ":8080", Handler: router.Handler(), } go func() { // service connections if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed { log.Fatalf("listen: %s\n", err) } }() // Wait for interrupt signal to gracefully shutdown the server with // a timeout of 5 seconds. quit := make(chan os.Signal, 1) // kill (no params) by default sends syscall.SIGTERM // kill -2 is syscall.SIGINT // kill -9 is syscall.SIGKILL but can't be caught, so don't need add it signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM) <-quit log.Println("Shutdown Server ...") ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() if err := srv.Shutdown(ctx); err != nil { log.Println("Server Shutdown:", err) } log.Println("Server exiting") } ``` ---- url: https://gin-gonic.com/en/docs/build-tags/ ---- [Skip to content](#_top) # Build Tags Go [build tags](https://pkg.go.dev/go/build#hdr-Build_Constraints) (also called build constraints) are directives that tell the Go compiler to include or exclude files during compilation. Gin uses build tags to let you swap out internal implementations or disable optional features at compile time, without changing any application code. This is useful in several scenarios: * **Performance optimization** – Replace the default `encoding/json` package with a faster third-party encoder to speed up JSON serialization in your API. * **Binary size reduction** – Strip out features you do not use, such as MsgPack rendering, to produce a smaller compiled binary. * **Deployment tuning** – Choose different encoders for different environments (e.g., a high-throughput production build vs. a standard development build). Build tags are passed to the Go toolchain with the `-tags` flag: Terminal window ``` go build -tags= . ``` You can combine multiple tags by separating them with commas: Terminal window ``` go build -tags=nomsgpack,go_json . ``` ### Available build tags [Section titled “Available build tags”](#available-build-tags) | Tag | Effect | | ----------- | --------------------------------------------------------------------------------------------------------- | | `go_json` | Replaces `encoding/json` with [go-json](https://github.com/goccy/go-json) | | `jsoniter` | Replaces `encoding/json` with [jsoniter](https://github.com/json-iterator/go) | | `sonic avx` | Replaces `encoding/json` with [sonic](https://github.com/bytedance/sonic) (requires AVX CPU instructions) | | `nomsgpack` | Disables MsgPack rendering support | ## In this section [Section titled “In this section”](#in-this-section) The pages below cover each build tag in detail: * [**Build with JSON replacement**](./json-replacement/) – Replace the default JSON encoder with go-json, jsoniter, or sonic for faster serialization. * [**Build without MsgPack**](./nomsgpack/) – Disable MsgPack rendering with the `nomsgpack` build tag to reduce binary size. ---- url: https://gin-gonic.com/en/docs/build-tags/json-replacement/ ---- [Skip to content](#_top) # Build with JSON replacement Gin uses the standard library `encoding/json` package for JSON serialization and deserialization by default. The standard library encoder is well-tested and fully compatible, but it is not the fastest option available. If JSON performance is a bottleneck in your application – for example, in high-throughput APIs that serialize large response payloads – you can swap in a faster drop-in replacement at build time using build tags. No code changes are required. ## Available replacements [Section titled “Available replacements”](#available-replacements) Gin supports three alternative JSON encoders. Each one implements the same interface that Gin expects, so your handlers, middleware, and binding logic continue to work without modification. ### go-json [Section titled “go-json”](#go-json) [go-json](https://github.com/goccy/go-json) is a pure-Go JSON encoder that offers significant performance improvements over `encoding/json` while maintaining full compatibility. It works on all platforms and architectures. Terminal window ``` go build -tags=go_json . ``` ### jsoniter [Section titled “jsoniter”](#jsoniter) [jsoniter](https://github.com/json-iterator/go) (json-iterator) is another pure-Go, high-performance JSON library. It is API-compatible with `encoding/json` and provides a flexible configuration system for advanced use cases. Terminal window ``` go build -tags=jsoniter . ``` ### sonic [Section titled “sonic”](#sonic) [sonic](https://github.com/bytedance/sonic) is a blazing-fast JSON encoder developed by ByteDance. It uses JIT compilation and SIMD instructions to achieve maximum throughput, making it the fastest option among the three. Terminal window ``` go build -tags="sonic avx" . ``` ## Choosing a replacement [Section titled “Choosing a replacement”](#choosing-a-replacement) | Encoder | Platform support | Key strength | | ------------------------- | --------------------- | ------------------------------------------ | | `encoding/json` (default) | All | Maximum compatibility, no extra dependency | | go-json | All | Good speedup, pure Go, broad compatibility | | jsoniter | All | Good speedup, flexible configuration | | sonic | x86\_64 with AVX only | Highest throughput via JIT and SIMD | For most applications, **go-json** is a safe and effective choice – it works everywhere and provides meaningful performance gains. Choose **sonic** when you need maximum JSON throughput and your servers run on x86\_64 hardware. Choose **jsoniter** if you need its specific configuration features or are already using it elsewhere in your codebase. ## Verifying the replacement [Section titled “Verifying the replacement”](#verifying-the-replacement) You can confirm that the replacement is active by comparing serialization performance with a simple benchmark, or by checking the binary’s symbol table: Terminal window ``` # Build with go-json go build -tags=go_json -o myapp . # Check that go-json symbols are present go tool nm myapp | grep goccy ``` The build tag also works with other Go commands: Terminal window ``` go run -tags=go_json . go test -tags=go_json ./... ``` ---- url: https://gin-gonic.com/en/docs/rendering/jsonp/ ---- [Skip to content](#_top) # JSONP JSONP (JSON with Padding) is a technique for making cross-domain requests from browsers that predate CORS support. It works by wrapping a JSON response in a JavaScript function call. The browser loads the response via a `

Welcome, Ginner!

`)) func main() { router := gin.Default() router.Static("/assets", "./assets") router.SetHTMLTemplate(html) router.GET("/", func(c *gin.Context) { if pusher := c.Writer.Pusher(); pusher != nil { // use pusher.Push() to do server push if err := pusher.Push("/assets/app.js", nil); err != nil { log.Printf("Failed to push: %v", err) } } c.HTML(200, "https", gin.H{ "status": "success", }) }) // Listen and Serve in https://127.0.0.1:8080 router.RunTLS(":8080", "./testdata/server.pem", "./testdata/server.key") } ``` ---- url: https://gin-gonic.com/en/docs/routing/api-design/ ---- [Skip to content](#_top) # API Design Patterns Building a RESTful API with Gin goes beyond defining routes. A well-designed API uses consistent response formats, predictable pagination, clear versioning, and structured error handling. This guide covers practical patterns you can apply to production Gin applications. ## Consistent response format [Section titled “Consistent response format”](#consistent-response-format) Wrapping every response in a standard envelope makes life easier for API consumers. They always know where to find data, errors, and metadata. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) // Response is the standard API envelope. type Response struct { Success bool `json:"success"` Data interface{} `json:"data,omitempty"` Error *ErrorInfo `json:"error,omitempty"` Meta *Meta `json:"meta,omitempty"` } type ErrorInfo struct { Code string `json:"code"` Message string `json:"message"` } type Meta struct { Page int `json:"page,omitempty"` PerPage int `json:"per_page,omitempty"` Total int `json:"total,omitempty"` TotalPages int `json:"total_pages,omitempty"` } // OK sends a success response. func OK(c *gin.Context, data interface{}) { c.JSON(http.StatusOK, Response{ Success: true, Data: data, }) } // Fail sends an error response. func Fail(c *gin.Context, status int, code, message string) { c.JSON(status, Response{ Success: false, Error: &ErrorInfo{Code: code, Message: message}, }) } func main() { r := gin.Default() r.GET("/api/users/:id", func(c *gin.Context) { id := c.Param("id") // Simulate a lookup if id == "0" { Fail(c, http.StatusNotFound, "USER_NOT_FOUND", "no user with that ID") return } OK(c, gin.H{"id": id, "name": "Alice"}) }) r.Run(":8080") } ``` ## Pagination [Section titled “Pagination”](#pagination) ### Limit/offset pagination [Section titled “Limit/offset pagination”](#limitoffset-pagination) Limit/offset is the simplest approach. It works well for small-to-medium datasets where the total row count is affordable to compute. ``` package main import ( "net/http" "strconv" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/api/articles", func(c *gin.Context) { limit, _ := strconv.Atoi(c.DefaultQuery("limit", "20")) offset, _ := strconv.Atoi(c.DefaultQuery("offset", "0")) if limit > 100 { limit = 100 // cap the page size } // articles, total := db.ListArticles(limit, offset) c.JSON(http.StatusOK, gin.H{ "success": true, "data": []gin.H{}, // articles "meta": gin.H{ "limit": limit, "offset": offset, "total": 0, // total }, }) }) r.Run(":8080") } ``` ### Cursor-based pagination [Section titled “Cursor-based pagination”](#cursor-based-pagination) Cursor-based pagination avoids the performance problems of large offsets. Pass the last item’s ID (or another unique, sortable field) as the cursor. ``` package main import ( "net/http" "strconv" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/api/events", func(c *gin.Context) { cursor := c.Query("cursor") // e.g. last event ID limit, _ := strconv.Atoi(c.DefaultQuery("limit", "20")) if limit > 100 { limit = 100 } // events, nextCursor := db.ListEvents(cursor, limit) _ = cursor c.JSON(http.StatusOK, gin.H{ "success": true, "data": []gin.H{}, // events "next_cursor": "", // nextCursor (empty string means no more pages) }) }) r.Run(":8080") } ``` ## Filtering and sorting [Section titled “Filtering and sorting”](#filtering-and-sorting) Accept filtering and sorting through query parameters. Keep the interface predictable by using consistent parameter names. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() // GET /api/products?category=electronics&min_price=10&sort=price&order=asc r.GET("/api/products", func(c *gin.Context) { category := c.Query("category") minPrice := c.Query("min_price") maxPrice := c.Query("max_price") sortBy := c.DefaultQuery("sort", "created_at") order := c.DefaultQuery("order", "desc") // Validate the sort field against an allow-list to prevent injection. allowed := map[string]bool{"created_at": true, "price": true, "name": true} if !allowed[sortBy] { sortBy = "created_at" } if order != "asc" && order != "desc" { order = "desc" } // Build and execute your query using these filters... _ = category _ = minPrice _ = maxPrice c.JSON(http.StatusOK, gin.H{ "success": true, "data": []gin.H{}, "filters": gin.H{ "category": category, "min_price": minPrice, "max_price": maxPrice, "sort": sortBy, "order": order, }, }) }) r.Run(":8080") } ``` ## API versioning [Section titled “API versioning”](#api-versioning) ### URL path versioning [Section titled “URL path versioning”](#url-path-versioning) URL path versioning is the most common strategy. It is explicit, easy to route, and simple to test with `curl`. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() v1 := r.Group("/api/v1") { v1.GET("/users", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"version": "v1", "users": []string{}}) }) } v2 := r.Group("/api/v2") { v2.GET("/users", func(c *gin.Context) { // v2 returns a different shape c.JSON(http.StatusOK, gin.H{ "version": "v2", "data": []gin.H{}, "meta": gin.H{"total": 0}, }) }) } r.Run(":8080") } ``` ### Header-based versioning [Section titled “Header-based versioning”](#header-based-versioning) Header versioning keeps URLs clean but requires clients to set a custom header. A middleware can read the header and store the version in the context. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) // VersionMiddleware reads the API version from the Accept-Version header. func VersionMiddleware() gin.HandlerFunc { return func(c *gin.Context) { version := c.GetHeader("Accept-Version") if version == "" { version = "v1" // default } c.Set("api_version", version) c.Next() } } func main() { r := gin.Default() r.Use(VersionMiddleware()) r.GET("/api/users", func(c *gin.Context) { version := c.GetString("api_version") switch version { case "v2": c.JSON(http.StatusOK, gin.H{"version": "v2", "data": []gin.H{}}) default: c.JSON(http.StatusOK, gin.H{"version": "v1", "users": []string{}}) } }) r.Run(":8080") } ``` ## Error handling patterns [Section titled “Error handling patterns”](#error-handling-patterns) ### Custom error types [Section titled “Custom error types”](#custom-error-types) Define application-level error types so handlers can return meaningful, structured errors. ``` package main import ( "errors" "net/http" "github.com/gin-gonic/gin" ) // AppError represents a structured API error. type AppError struct { Status int `json:"-"` Code string `json:"code"` Message string `json:"message"` } func (e *AppError) Error() string { return e.Message } var ( ErrNotFound = &AppError{Status: 404, Code: "NOT_FOUND", Message: "resource not found"} ErrUnauthorized = &AppError{Status: 401, Code: "UNAUTHORIZED", Message: "authentication required"} ErrBadRequest = &AppError{Status: 400, Code: "BAD_REQUEST", Message: "invalid request"} ) // ErrorHandler is a middleware that catches errors set via c.Error(). func ErrorHandler() gin.HandlerFunc { return func(c *gin.Context) { c.Next() if len(c.Errors) == 0 { return } err := c.Errors.Last().Err var appErr *AppError if errors.As(err, &appErr) { c.JSON(appErr.Status, gin.H{ "success": false, "error": gin.H{"code": appErr.Code, "message": appErr.Message}, }) } else { c.JSON(http.StatusInternalServerError, gin.H{ "success": false, "error": gin.H{"code": "INTERNAL", "message": "an unexpected error occurred"}, }) } } } func main() { r := gin.Default() r.Use(ErrorHandler()) r.GET("/api/items/:id", func(c *gin.Context) { id := c.Param("id") if id == "0" { _ = c.Error(ErrNotFound) return } c.JSON(http.StatusOK, gin.H{"success": true, "data": gin.H{"id": id}}) }) r.Run(":8080") } ``` ## Resource-based route organization [Section titled “Resource-based route organization”](#resource-based-route-organization) As your API grows, organize routes by resource. Each resource gets its own file with a function that registers routes on a `gin.RouterGroup`. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) // RegisterUserRoutes sets up all /users endpoints. func RegisterUserRoutes(rg *gin.RouterGroup) { users := rg.Group("/users") { users.GET("/", listUsers) users.POST("/", createUser) users.GET("/:id", getUser) users.PUT("/:id", updateUser) users.DELETE("/:id", deleteUser) } } // RegisterOrderRoutes sets up all /orders endpoints. func RegisterOrderRoutes(rg *gin.RouterGroup) { orders := rg.Group("/orders") { orders.GET("/", listOrders) orders.POST("/", createOrder) orders.GET("/:id", getOrder) } } func listUsers(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"action": "list_users"}) } func createUser(c *gin.Context) { c.JSON(http.StatusCreated, gin.H{"action": "create_user"}) } func getUser(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"action": "get_user"}) } func updateUser(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"action": "update_user"}) } func deleteUser(c *gin.Context) { c.Status(http.StatusNoContent) } func listOrders(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"action": "list_orders"}) } func createOrder(c *gin.Context) { c.JSON(http.StatusCreated, gin.H{"action": "create_order"}) } func getOrder(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"action": "get_order"}) } func main() { r := gin.Default() api := r.Group("/api/v1") RegisterUserRoutes(api) RegisterOrderRoutes(api) r.Run(":8080") } ``` In a real project you would put `RegisterUserRoutes` in a `routes/users.go` file and `RegisterOrderRoutes` in `routes/orders.go`, then call both from `main.go`. This keeps each resource self-contained and makes it easy to add or remove resources without touching unrelated code. ---- url: https://gin-gonic.com/en/docs/server-config/support-lets-encrypt/ ---- [Skip to content](#_top) # Support Let's Encrypt The [gin-gonic/autotls](https://github.com/gin-gonic/autotls) package provides automatic HTTPS via Let’s Encrypt. It handles certificate issuance and renewal automatically, so you can serve HTTPS with minimal configuration. ## Quick start [Section titled “Quick start”](#quick-start) The simplest way is to call `autotls.Run` with your router and one or more domain names: ``` package main import ( "log" "github.com/gin-gonic/autotls" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() router.GET("/ping", func(c *gin.Context) { c.String(200, "pong") }) log.Fatal(autotls.Run(router, "example1.com", "example2.com")) } ``` ## Custom autocert manager [Section titled “Custom autocert manager”](#custom-autocert-manager) For more control — such as specifying a certificate cache directory or restricting allowed hostnames — use `autotls.RunWithManager` with a custom `autocert.Manager`: ``` package main import ( "log" "github.com/gin-gonic/autotls" "github.com/gin-gonic/gin" "golang.org/x/crypto/acme/autocert" ) func main() { router := gin.Default() router.GET("/ping", func(c *gin.Context) { c.String(200, "pong") }) m := autocert.Manager{ Prompt: autocert.AcceptTOS, HostPolicy: autocert.HostWhitelist("example1.com", "example2.com"), Cache: autocert.DirCache("/var/www/.cache"), } log.Fatal(autotls.RunWithManager(router, &m)) } ``` ## See also [Section titled “See also”](#see-also) * [Custom HTTP configuration](/en/docs/server-config/custom-http-config/) ---- url: https://gin-gonic.com/en/docs/build-tags/nomsgpack/ ---- [Skip to content](#_top) # Build without MsgPack [MsgPack](https://msgpack.org/) (MessagePack) is a compact binary serialization format – think of it as a faster, smaller alternative to JSON. Gin includes MsgPack rendering and binding support by default, which means your application can accept and return MsgPack-encoded data out of the box using `c.Bind()` and `c.Render()` with the appropriate content type. However, many applications only use JSON and never need MsgPack. In that case, the MsgPack dependency adds unnecessary weight to your compiled binary. You can strip it out with the `nomsgpack` build tag. ## Building without MsgPack [Section titled “Building without MsgPack”](#building-without-msgpack) Pass the `nomsgpack` tag to `go build`: Terminal window ``` go build -tags=nomsgpack . ``` This also works with other Go commands: Terminal window ``` go run -tags=nomsgpack . go test -tags=nomsgpack ./... ``` ## What changes [Section titled “What changes”](#what-changes) When you build with `nomsgpack`, Gin excludes the MsgPack rendering and binding code at compile time. This has a few practical effects: * The compiled binary is smaller because the MsgPack serialization library is not linked in. * Any handler that attempts to render or bind MsgPack data will no longer work. If you use `c.ProtoBuf()` or other non-MsgPack renderers, those are unaffected. * All JSON, XML, YAML, TOML, and ProtoBuf features continue to work normally. ## Verifying the result [Section titled “Verifying the result”](#verifying-the-result) You can confirm the binary size reduction by comparing builds: Terminal window ``` # Standard build go build -o gin-app . ls -lh gin-app # Build without MsgPack go build -tags=nomsgpack -o gin-app-nomsgpack . ls -lh gin-app-nomsgpack ``` The exact savings depend on your application, but removing MsgPack typically shaves a small amount off the final binary. For more background, see the [original pull request](https://github.com/gin-gonic/gin/pull/1852). ---- url: https://gin-gonic.com/en/docs/rendering/serving-data-from-reader/ ---- [Skip to content](#_top) # Serving data from reader `DataFromReader` lets you stream data from any `io.Reader` directly to the HTTP response without buffering the entire content in memory first. This is essential for building proxy endpoints or serving large files from remote sources efficiently. **Common use cases:** * **Proxying remote resources** — Fetching a file from an external service (such as a cloud storage API or CDN) and forwarding it to the client. The data flows through your server without being fully loaded into memory. * **Serving generated content** — Streaming dynamically generated data (such as CSV exports or report files) as it is produced. * **Large file downloads** — Serving files that are too large to hold in memory, by reading them in chunks from disk or from a remote source. The method signature is `c.DataFromReader(code, contentLength, contentType, reader, extraHeaders)`. You provide the HTTP status code, the content length (so the client knows the total size), the MIME type, the `io.Reader` to stream from, and an optional map of extra response headers (such as `Content-Disposition` for file downloads). ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) 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(":8080") } ``` In this example, Gin fetches an image from GitHub and streams it directly to the client as a downloadable attachment. The image bytes flow from the upstream HTTP response body through to the client response without being accumulated in a buffer. Note that `response.Body` is automatically closed by the HTTP server after the handler returns, since `DataFromReader` reads it to completion during the response write. ---- url: https://gin-gonic.com/en/docs/server-config/run-multiple-service/ ---- [Skip to content](#_top) # Run multiple service You can run multiple Gin servers in the same process — each on a different port — by using `errgroup.Group` from the `golang.org/x/sync/errgroup` package. This is useful when you need to expose separate APIs (for example, a public API on port 8080 and an admin API on port 8081) without deploying separate binaries. Each server gets its own router, middleware stack, and `http.Server` configuration. ``` 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, "message": "Welcome server 01", }) }) 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, "message": "Welcome server 02", }) }) return e } func main() { server01 := &http.Server{ Addr: ":8080", Handler: router01(), ReadTimeout: 5 * time.Second, WriteTimeout: 10 * time.Second, } server02 := &http.Server{ Addr: ":8081", Handler: router02(), ReadTimeout: 5 * time.Second, WriteTimeout: 10 * 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) } } ``` ## Test it [Section titled “Test it”](#test-it) Terminal window ``` # Server 01 on port 8080 curl http://localhost:8080/ # Output: {"code":200,"message":"Welcome server 01"} # Server 02 on port 8081 curl http://localhost:8081/ # Output: {"code":200,"message":"Welcome server 02"} ``` ## See also [Section titled “See also”](#see-also) * [Custom HTTP configuration](/en/docs/server-config/custom-http-config/) * [Graceful restart or stop](/en/docs/server-config/graceful-restart-or-stop/) ---- url: https://gin-gonic.com/en/docs/server-config/websocket/ ---- [Skip to content](#_top) # WebSocket Support Gin does not include a built-in WebSocket implementation, but it integrates seamlessly with the [gorilla/websocket](https://github.com/gorilla/websocket) package. Because Gin handlers receive the underlying `http.ResponseWriter` and `*http.Request`, you can upgrade any Gin route to a WebSocket connection with minimal effort. ## Installation [Section titled “Installation”](#installation) Install the `gorilla/websocket` package: Terminal window ``` go get github.com/gorilla/websocket ``` ## Basic Echo Server [Section titled “Basic Echo Server”](#basic-echo-server) The simplest WebSocket server reads a message from the client and echoes it back. This is a good starting point for understanding the upgrade process. ``` package main import ( "log" "net/http" "github.com/gin-gonic/gin" "github.com/gorilla/websocket" ) var upgrader = websocket.Upgrader{ // Allow all origins for development; restrict this in production. CheckOrigin: func(r *http.Request) bool { return true }, } func handleWebSocket(c *gin.Context) { conn, err := upgrader.Upgrade(c.Writer, c.Request, nil) if err != nil { log.Printf("WebSocket upgrade error: %v", err) return } defer conn.Close() for { messageType, message, err := conn.ReadMessage() if err != nil { log.Printf("Read error: %v", err) break } log.Printf("Received: %s", message) if err := conn.WriteMessage(messageType, message); err != nil { log.Printf("Write error: %v", err) break } } } func main() { router := gin.Default() router.GET("/ws", handleWebSocket) router.Run(":8080") } ``` ## Chat Broadcast Example [Section titled “Chat Broadcast Example”](#chat-broadcast-example) A more practical example: a simple chat server that broadcasts every incoming message to all connected clients. ``` package main import ( "log" "net/http" "sync" "github.com/gin-gonic/gin" "github.com/gorilla/websocket" ) var upgrader = websocket.Upgrader{ CheckOrigin: func(r *http.Request) bool { return true }, } type Hub struct { mu sync.RWMutex clients map[*websocket.Conn]bool } func newHub() *Hub { return &Hub{ clients: make(map[*websocket.Conn]bool), } } func (h *Hub) addClient(conn *websocket.Conn) { h.mu.Lock() defer h.mu.Unlock() h.clients[conn] = true } func (h *Hub) removeClient(conn *websocket.Conn) { h.mu.Lock() defer h.mu.Unlock() delete(h.clients, conn) conn.Close() } func (h *Hub) broadcast(messageType int, message []byte) { h.mu.RLock() defer h.mu.RUnlock() for conn := range h.clients { if err := conn.WriteMessage(messageType, message); err != nil { log.Printf("Broadcast error: %v", err) } } } func main() { hub := newHub() router := gin.Default() router.GET("/ws", func(c *gin.Context) { conn, err := upgrader.Upgrade(c.Writer, c.Request, nil) if err != nil { log.Printf("Upgrade error: %v", err) return } hub.addClient(conn) defer hub.removeClient(conn) for { messageType, message, err := conn.ReadMessage() if err != nil { log.Printf("Read error: %v", err) break } hub.broadcast(messageType, message) } }) router.Run(":8080") } ``` > **Note:** The broadcast example above writes to multiple connections while holding a read lock. For production use, consider sending messages through a channel per client to avoid blocking the broadcast loop on a slow connection. See the [gorilla/websocket chat example](https://github.com/gorilla/websocket/tree/main/examples/chat) for a production-ready pattern. ## Connection Upgrade and Configuration [Section titled “Connection Upgrade and Configuration”](#connection-upgrade-and-configuration) The `websocket.Upgrader` controls how HTTP connections are upgraded to WebSocket. Key fields: ``` var upgrader = websocket.Upgrader{ // ReadBufferSize and WriteBufferSize specify the I/O buffer sizes in bytes. // The default (4096) works for most use cases. Increase them for large messages. ReadBufferSize: 1024, WriteBufferSize: 1024, // CheckOrigin controls whether the request Origin header is acceptable. // By default it rejects cross-origin requests. Override it for CORS support. CheckOrigin: func(r *http.Request) bool { origin := r.Header.Get("Origin") return origin == "https://your-app.example.com" }, // Subprotocols specifies the server's supported protocols in order of preference. Subprotocols: []string{"graphql-ws", "graphql-transport-ws"}, } ``` You can also set response headers during the upgrade: ``` func handleWebSocket(c *gin.Context) { responseHeader := http.Header{} responseHeader.Set("X-Custom-Header", "value") conn, err := upgrader.Upgrade(c.Writer, c.Request, responseHeader) if err != nil { log.Printf("Upgrade error: %v", err) return } defer conn.Close() // ... } ``` ## Best Practices [Section titled “Best Practices”](#best-practices) ### Ping/Pong for Connection Health [Section titled “Ping/Pong for Connection Health”](#pingpong-for-connection-health) WebSocket connections can go stale silently. Use ping/pong frames to detect dead connections: ``` import "time" const ( pongWait = 60 * time.Second pingPeriod = (pongWait * 9) / 10 // must be less than pongWait ) func handleWebSocket(c *gin.Context) { conn, err := upgrader.Upgrade(c.Writer, c.Request, nil) if err != nil { return } defer conn.Close() conn.SetReadDeadline(time.Now().Add(pongWait)) conn.SetPongHandler(func(string) error { conn.SetReadDeadline(time.Now().Add(pongWait)) return nil }) // Start a goroutine to send pings. go func() { ticker := time.NewTicker(pingPeriod) defer ticker.Stop() for range ticker.C { if err := conn.WriteMessage(websocket.PingMessage, nil); err != nil { return } } }() // Read loop for { _, message, err := conn.ReadMessage() if err != nil { break } log.Printf("Received: %s", message) } } ``` ### Connection Cleanup [Section titled “Connection Cleanup”](#connection-cleanup) Always close connections and release resources when done: * Use `defer conn.Close()` immediately after a successful upgrade. * Remove connections from any shared data structures (such as the hub in the chat example) when the read loop exits. * Set read and write deadlines to prevent goroutine leaks from idle connections. ### Concurrent Writes [Section titled “Concurrent Writes”](#concurrent-writes) The `gorilla/websocket` package does **not** support concurrent writes to a single connection. If multiple goroutines need to write, serialize access with one of these approaches: * **Mutex:** Protect writes with a `sync.Mutex`. * **Channel:** Funnel all outgoing messages through a single channel consumed by one writer goroutine. The channel approach is generally preferred because it naturally handles back-pressure and keeps the writing logic in one place. ## Testing [Section titled “Testing”](#testing) ### Using wscat [Section titled “Using wscat”](#using-wscat) [wscat](https://github.com/websockets/wscat) is a command-line WebSocket client. Install it with npm: Terminal window ``` npm install -g wscat ``` Connect to your server: Terminal window ``` wscat -c ws://localhost:8080/ws ``` Type a message and press Enter. The echo server will send it back. ### Using curl [Section titled “Using curl”](#using-curl) curl 7.86+ supports WebSocket. Send a message to the echo server: Terminal window ``` curl --include \ --no-buffer \ --header "Connection: Upgrade" \ --header "Upgrade: websocket" \ --header "Sec-WebSocket-Version: 13" \ --header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \ http://localhost:8080/ws ``` > For interactive testing, `wscat` is more convenient than curl because it handles the WebSocket framing protocol automatically. ## See Also [Section titled “See Also”](#see-also) * [gorilla/websocket documentation](https://pkg.go.dev/github.com/gorilla/websocket) * [gorilla/websocket chat example](https://github.com/gorilla/websocket/tree/main/examples/chat) – production-ready chat with per-client write goroutines * [RFC 6455 – The WebSocket Protocol](https://datatracker.ietf.org/doc/html/rfc6455) * [Custom HTTP configuration](/docs/en/docs/server-config/custom-http-config/) – customizing the underlying HTTP server used with Gin ---- url: https://gin-gonic.com/en/docs/learning-resources/ ---- [Skip to content](#_top) # Learning Resources ## Official Resources [Section titled “Official Resources”](#official-resources) These are maintained by the Gin team and are the most authoritative sources of information. * **[Gin GitHub Repository](https://github.com/gin-gonic/gin)** – Source code, issue tracker, and the latest release notes. * **[Gin Examples Repository](https://github.com/gin-gonic/examples)** – A collection of self-contained example projects covering common use cases such as file uploads, graceful shutdown, JWT authentication, and more. * **[Gin API Reference (pkg.go.dev)](https://pkg.go.dev/github.com/gin-gonic/gin)** – Auto-generated API documentation for every exported type and function. ## Go Language Resources [Section titled “Go Language Resources”](#go-language-resources) A solid understanding of Go itself will make working with Gin much easier. * **[A Tour of Go](https://go.dev/tour/)** – The official interactive introduction to Go. * **[Effective Go](https://go.dev/doc/effective_go)** – Best practices and idiomatic patterns for writing Go code. * **[Go by Example](https://gobyexample.com/)** – Annotated example programs covering Go fundamentals. * **[Go Standard Library Documentation](https://pkg.go.dev/std)** – Reference for every package in the standard library, including `net/http`, which Gin builds on. ## Tutorials and Articles [Section titled “Tutorials and Articles”](#tutorials-and-articles) Community-written guides that walk through building real applications with Gin. * **[Building a RESTful API with Go and Gin (Go.dev)](https://go.dev/doc/tutorial/web-service-gin)** – An official Go tutorial that uses Gin to build a simple web service. * **[Build a REST API with Go, Gin, and GORM (Digital Ocean)](https://www.digitalocean.com/community/tutorials/how-to-build-and-deploy-a-go-application)** – Covers project layout, database integration, and deployment. ## Interactive Learning Platforms [Section titled “Interactive Learning Platforms”](#interactive-learning-platforms) Looking to practice Gin concepts through hands-on exercises? Here are some community-driven learning resources: ### Go Interview Practice - Gin Challenges [Section titled “Go Interview Practice - Gin Challenges”](#go-interview-practice---gin-challenges) A comprehensive platform offering progressive Gin challenges that complement the official documentation: #### What You'll Learn: * Basic routing and HTTP methods * Middleware implementation and patterns * Request validation and error handling * Authentication and security practices #### See It In Action: A brief introduction to the Go Interview Practice platform [Explore Gin Challenges →](https://github.com/RezaSi/go-interview-practice) \-- ---- url: https://gin-gonic.com/en/docs/binding/bind-body-into-different-structs/ ---- [Skip to content](#_top) # Try to bind body into different structs The standard binding methods like `c.ShouldBind` consume `c.Request.Body`, which is an `io.ReadCloser` — once read, it cannot be read again. This means you cannot call `c.ShouldBind` multiple times on the same request to try different struct shapes. To solve this, use `c.ShouldBindBodyWith`. It reads the body once and stores it in the context, allowing subsequent bindings to reuse the cached body. ``` package main import ( "net/http" "github.com/gin-gonic/gin" "github.com/gin-gonic/gin/binding" ) type formA struct { Foo string `json:"foo" xml:"foo" binding:"required"` } type formB struct { Bar string `json:"bar" xml:"bar" binding:"required"` } func main() { router := gin.Default() router.POST("/bind", func(c *gin.Context) { objA := formA{} objB := formB{} // This reads c.Request.Body and stores the result into the context. if errA := c.ShouldBindBodyWith(&objA, binding.JSON); errA == nil { c.JSON(http.StatusOK, gin.H{"message": "matched formA", "foo": objA.Foo}) return } // At this time, it reuses body stored in the context. if errB := c.ShouldBindBodyWith(&objB, binding.JSON); errB == nil { c.JSON(http.StatusOK, gin.H{"message": "matched formB", "bar": objB.Bar}) return } c.JSON(http.StatusBadRequest, gin.H{"error": "request body did not match any known format"}) }) router.Run(":8080") } ``` ## Test it [Section titled “Test it”](#test-it) Terminal window ``` # Body matches formA curl -X POST http://localhost:8080/bind \ -H "Content-Type: application/json" \ -d '{"foo":"hello"}' # Output: {"foo":"hello","message":"matched formA"} # Body matches formB curl -X POST http://localhost:8080/bind \ -H "Content-Type: application/json" \ -d '{"bar":"world"}' # Output: {"bar":"world","message":"matched formB"} ``` ## See also [Section titled “See also”](#see-also) * [Binding and validation](/en/docs/binding/binding-and-validation/) * [Bind query string or post data](/en/docs/binding/bind-query-or-post/) ---- url: https://gin-gonic.com/en/docs/rendering/multiple-template/ ---- [Skip to content](#_top) # Multitemplate Gin allows by default only one `html.Template`. Check [multitemplate](https://github.com/gin-contrib/multitemplate) for using features like `block template`. ``` package main import ( "github.com/gin-contrib/multitemplate" "github.com/gin-gonic/gin" ) func createMyRender() multitemplate.Renderer { r := multitemplate.NewRenderer() r.AddFromFiles("index", "templates/base.html", "templates/index.html") r.AddFromFiles("article", "templates/base.html", "templates/article.html") return r } func main() { router := gin.Default() router.HTMLRender = createMyRender() router.GET("/", func(c *gin.Context) { c.HTML(200, "index", gin.H{"title": "Home"}) }) router.GET("/article", func(c *gin.Context) { c.HTML(200, "article", gin.H{"title": "Article"}) }) router.Run(":8080") } ``` ---- url: https://gin-gonic.com/en/docs/rendering/serving-data-from-file/ ---- [Skip to content](#_top) # Serving data from file Gin provides several methods for serving files to clients. Each method suits a different use case: * **`c.File(path)`** – Serves a file from the local filesystem. The content type is detected automatically. Use this when you know the exact file path at compile time or have already validated it. * **`c.FileFromFS(path, fs)`** – Serves a file from an `http.FileSystem` interface. Useful when serving files from embedded filesystems (`embed.FS`), custom storage backends, or when you want to restrict access to a specific directory tree. * **`c.FileAttachment(path, filename)`** – Serves a file as a download by setting the `Content-Disposition: attachment` header. The browser will prompt the user to save the file using the filename you provide, regardless of the original file name on disk. ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() // Serve a file inline (displayed in browser) router.GET("/local/file", func(c *gin.Context) { c.File("local/file.go") }) // Serve a file from an http.FileSystem var fs http.FileSystem = http.Dir("/var/www/assets") router.GET("/fs/file", func(c *gin.Context) { c.FileFromFS("fs/file.go", fs) }) // Serve a file as a downloadable attachment with a custom filename router.GET("/download", func(c *gin.Context) { c.FileAttachment("local/report-2024-q1.xlsx", "quarterly-report.xlsx") }) router.Run(":8080") } ``` You can test the download endpoint with curl: Terminal window ``` # The -v flag shows the Content-Disposition header curl -v http://localhost:8080/download --output report.xlsx # Serve a file inline curl http://localhost:8080/local/file ``` For streaming data from an `io.Reader` (such as a remote URL or dynamically generated content), use `c.DataFromReader()` instead. See [Serving data from reader](/en/docs/rendering/serving-data-from-reader/) for details. ---- url: https://gin-gonic.com/en/docs/rendering/ ---- [Skip to content](#_top) # Rendering Gin supports rendering responses in multiple formats including JSON, XML, YAML, ProtoBuf, HTML, and more. Every rendering method follows the same pattern: call a method on `*gin.Context` with an HTTP status code and the data to serialize. Gin handles content-type headers, serialization, and writing the response automatically. ``` // All rendering methods share this pattern: c.JSON(http.StatusOK, data) // application/json c.XML(http.StatusOK, data) // application/xml c.YAML(http.StatusOK, data) // application/x-yaml c.TOML(http.StatusOK, data) // application/toml c.ProtoBuf(http.StatusOK, data) // application/x-protobuf ``` You can use the `Accept` header or a query parameter to serve the same data in multiple formats from a single handler: ``` package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() router.GET("/user", func(c *gin.Context) { user := gin.H{"name": "Lena", "role": "admin"} switch c.Query("format") { case "xml": c.XML(http.StatusOK, user) case "yaml": c.YAML(http.StatusOK, user) default: c.JSON(http.StatusOK, user) } }) router.Run(":8080") } ``` ## In this section [Section titled “In this section”](#in-this-section) * [**XML/JSON/YAML/ProtoBuf rendering**](./rendering/) – Render responses in multiple formats with automatic content-type handling * [**SecureJSON**](./secure-json/) – Prevent JSON hijacking attacks in legacy browsers * [**JSONP**](./jsonp/) – Support cross-domain requests from legacy clients without CORS * [**AsciiJSON**](./ascii-json/) – Escape non-ASCII characters for safe transport * [**PureJSON**](./pure-json/) – Render JSON without escaping HTML characters * [**Serving static files**](./serving-static-files/) – Serve directories of static assets * [**Serving data from file**](./serving-data-from-file/) – Serve individual files, attachments, and downloads * [**Serving data from reader**](./serving-data-from-reader/) – Stream data from any `io.Reader` to the response * [**HTML rendering**](./html-rendering/) – Render HTML templates with dynamic data * [**Multiple templates**](./multiple-template/) – Use multiple template sets in a single application * [**Bind single binary with template**](./bind-single-binary-with-template/) – Embed templates into your compiled binary ---- url: https://gin-gonic.com/en/docs/faq/ ---- [Skip to content](#_top) # FAQ ## General Questions [Section titled “General Questions”](#general-questions) ### How do I enable live reload during development? [Section titled “How do I enable live reload during development?”](#how-do-i-enable-live-reload-during-development) Use [Air](https://github.com/air-verse/air) for automatic live reloading during development. Air watches your files and rebuilds/restarts your application when changes are detected. **Installation:** Terminal window ``` go install github.com/air-verse/air@latest ``` **Setup:** Create a `.air.toml` configuration file in your project root: Terminal window ``` air init ``` Then run `air` in your project directory instead of `go run`: Terminal window ``` air ``` Air will watch your `.go` files and automatically rebuild/restart your Gin application on changes. See the [Air documentation](https://github.com/air-verse/air) for configuration options. ### How do I handle CORS in Gin? [Section titled “How do I handle CORS in Gin?”](#how-do-i-handle-cors-in-gin) Use the official [gin-contrib/cors](https://github.com/gin-contrib/cors) middleware: ``` package main import ( "time" "github.com/gin-contrib/cors" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() // Default CORS configuration r.Use(cors.Default()) // Or customize CORS settings r.Use(cors.New(cors.Config{ AllowOrigins: []string{"https://example.com"}, AllowMethods: []string{"GET", "POST", "PUT", "DELETE"}, AllowHeaders: []string{"Origin", "Content-Type", "Authorization"}, ExposeHeaders: []string{"Content-Length"}, AllowCredentials: true, MaxAge: 12 * time.Hour, })) r.GET("/ping", func(c *gin.Context) { c.JSON(200, gin.H{"message": "pong"}) }) r.Run() } ``` For a complete security overview, see [Security best practices](/en/docs/middleware/security-guide/). ### How do I serve static files? [Section titled “How do I serve static files?”](#how-do-i-serve-static-files) Use `Static()` or `StaticFS()` to serve static files: ``` func main() { r := gin.Default() // Serve files from ./assets directory at /assets/* r.Static("/assets", "./assets") // Serve a single file r.StaticFile("/favicon.ico", "./resources/favicon.ico") // Serve from embedded filesystem (Go 1.16+) r.StaticFS("/public", http.FS(embedFS)) r.Run() } ``` See [Serving data from file](/en/docs/rendering/serving-data-from-file/) for more details. ### How do I handle file uploads? [Section titled “How do I handle file uploads?”](#how-do-i-handle-file-uploads) Use `FormFile()` for single files or `MultipartForm()` for multiple files: ``` // Single file upload r.POST("/upload", func(c *gin.Context) { file, _ := c.FormFile("file") c.SaveUploadedFile(file, "./uploads/"+file.Filename) c.String(200, "File %s uploaded successfully", file.Filename) }) // Multiple files upload r.POST("/upload-multiple", func(c *gin.Context) { form, _ := c.MultipartForm() files := form.File["files"] for _, file := range files { c.SaveUploadedFile(file, "./uploads/"+file.Filename) } c.String(200, "%d files uploaded", len(files)) }) ``` See the [Upload file](/en/docs/routing/upload-file/) documentation for more details. ### How do I implement authentication with JWT? [Section titled “How do I implement authentication with JWT?”](#how-do-i-implement-authentication-with-jwt) Use [gin-contrib/jwt](https://github.com/gin-contrib/jwt) or implement custom middleware. Here’s a minimal example: ``` package main import ( "net/http" "time" "github.com/gin-gonic/gin" "github.com/golang-jwt/jwt/v5" ) var jwtSecret = []byte("your-secret-key") type Claims struct { Username string `json:"username"` jwt.RegisteredClaims } func AuthMiddleware() gin.HandlerFunc { return func(c *gin.Context) { tokenString := c.GetHeader("Authorization") if tokenString == "" { c.JSON(http.StatusUnauthorized, gin.H{"error": "Missing authorization token"}) c.Abort() return } // Remove "Bearer " prefix if present if len(tokenString) > 7 && tokenString[:7] == "Bearer " { tokenString = tokenString[7:] } token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) { return jwtSecret, nil }) if err != nil || !token.Valid { c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid token"}) c.Abort() return } if claims, ok := token.Claims.(*Claims); ok { c.Set("username", claims.Username) c.Next() } } } ``` For session-based authentication, see [Session management](/en/docs/middleware/session-management/). ### How do I set up request logging? [Section titled “How do I set up request logging?”](#how-do-i-set-up-request-logging) Gin includes a default logger middleware via `gin.Default()`. For structured JSON logging in production, see [Structured logging](/en/docs/logging/structured-logging/). For basic log customization: ``` r := gin.New() r.Use(gin.LoggerWithConfig(gin.LoggerConfig{ SkipPaths: []string{"/healthz"}, })) r.Use(gin.Recovery()) ``` See the [Logging](/en/docs/logging/) section for all options including custom formats, file output, and skipping query strings. ### How do I handle graceful shutdown? [Section titled “How do I handle graceful shutdown?”](#how-do-i-handle-graceful-shutdown) See [Graceful restart or stop](/en/docs/server-config/graceful-restart-or-stop/) for a complete guide with code examples. ### Why am I getting “404 Not Found” instead of “405 Method Not Allowed”? [Section titled “Why am I getting “404 Not Found” instead of “405 Method Not Allowed”?”](#why-am-i-getting-404-not-found-instead-of-405-method-not-allowed) By default, Gin returns 404 for routes that don’t support the requested HTTP method. Set `HandleMethodNotAllowed = true` to return 405 instead: ``` r := gin.Default() r.HandleMethodNotAllowed = true r.GET("/ping", func(c *gin.Context) { c.JSON(200, gin.H{"message": "pong"}) }) r.Run() ``` Terminal window ``` $ curl -X POST localhost:8080/ping HTTP/1.1 405 Method Not Allowed Allow: GET ``` ### How do I bind query parameters and POST data together? [Section titled “How do I bind query parameters and POST data together?”](#how-do-i-bind-query-parameters-and-post-data-together) Use `ShouldBind()` which automatically selects the binding based on content type: ``` type User struct { Name string `form:"name" json:"name"` Email string `form:"email" json:"email"` Page int `form:"page"` } r.POST("/user", func(c *gin.Context) { var user User if err := c.ShouldBind(&user); err != nil { c.JSON(400, gin.H{"error": err.Error()}) return } c.JSON(200, user) }) ``` See the [Binding](/en/docs/binding/) section for all binding options. ### How do I validate request data? [Section titled “How do I validate request data?”](#how-do-i-validate-request-data) Gin uses [go-playground/validator](https://github.com/go-playground/validator) for validation. Add validation tags to your structs: ``` type User struct { Name string `json:"name" binding:"required,min=3,max=50"` Email string `json:"email" binding:"required,email"` Age int `json:"age" binding:"gte=0,lte=130"` } r.POST("/user", func(c *gin.Context) { var user User if err := c.ShouldBindJSON(&user); err != nil { c.JSON(400, gin.H{"error": err.Error()}) return } c.JSON(200, gin.H{"message": "User is valid"}) }) ``` See [Binding and validation](/en/docs/binding/binding-and-validation/) for custom validators and advanced usage. ### How do I run Gin in production mode? [Section titled “How do I run Gin in production mode?”](#how-do-i-run-gin-in-production-mode) Set the `GIN_MODE` environment variable to `release`: Terminal window ``` export GIN_MODE=release # or GIN_MODE=release ./your-app ``` Or set it programmatically: ``` gin.SetMode(gin.ReleaseMode) ``` Release mode disables debug logging and improves performance. ### How do I handle database connections with Gin? [Section titled “How do I handle database connections with Gin?”](#how-do-i-handle-database-connections-with-gin) See [Database integration](/en/docs/server-config/database/) for a complete guide covering `database/sql`, GORM, connection pooling, and dependency injection patterns. ### How do I test Gin handlers? [Section titled “How do I test Gin handlers?”](#how-do-i-test-gin-handlers) Use `net/http/httptest` to test your routes: ``` func TestPingRoute(t *testing.T) { router := gin.Default() router.GET("/ping", func(c *gin.Context) { c.JSON(200, gin.H{"message": "pong"}) }) w := httptest.NewRecorder() req, _ := http.NewRequest("GET", "/ping", nil) router.ServeHTTP(w, req) assert.Equal(t, 200, w.Code) assert.Contains(t, w.Body.String(), "pong") } ``` See the [Testing](/en/docs/testing/) documentation for more examples. ## Performance Questions [Section titled “Performance Questions”](#performance-questions) ### How do I optimize Gin for high traffic? [Section titled “How do I optimize Gin for high traffic?”](#how-do-i-optimize-gin-for-high-traffic) 1. **Use Release Mode**: Set `GIN_MODE=release` 2. **Disable unnecessary middleware**: Only use what you need 3. **Use `gin.New()` instead of `gin.Default()`** for manual middleware control 4. **Connection pooling**: Configure database connection pools (see [Database integration](/en/docs/server-config/database/)) 5. **Caching**: Implement caching for frequently accessed data 6. **Load balancing**: Use reverse proxy (nginx, HAProxy) 7. **Profiling**: Use Go’s pprof to identify bottlenecks 8. **Monitoring**: Set up [metrics and monitoring](/en/docs/server-config/metrics/) to track performance ### Is Gin production-ready? [Section titled “Is Gin production-ready?”](#is-gin-production-ready) Yes. Gin is used in production by many companies and has been battle-tested at scale. See [Users](/en/docs/users/) for examples of projects using Gin in production. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### Why are my route parameters not working? [Section titled “Why are my route parameters not working?”](#why-are-my-route-parameters-not-working) Ensure route parameters use `:` syntax and are properly extracted: ``` // Correct r.GET("/user/:id", func(c *gin.Context) { id := c.Param("id") c.String(200, "User ID: %s", id) }) // Not: /user/{id} or /user/ ``` See [Parameters in path](/en/docs/routing/param-in-path/) for details. ### Why is my middleware not executing? [Section titled “Why is my middleware not executing?”](#why-is-my-middleware-not-executing) Middleware must be registered before routes or route groups: ``` // Correct order r := gin.New() r.Use(MyMiddleware()) // Register middleware first r.GET("/ping", handler) // Then routes // For route groups auth := r.Group("/admin") auth.Use(AuthMiddleware()) // Middleware for this group { auth.GET("/dashboard", handler) } ``` See [Using middleware](/en/docs/middleware/using-middleware/) for details. ### Why is request binding failing? [Section titled “Why is request binding failing?”](#why-is-request-binding-failing) Common reasons: 1. **Missing binding tags**: Add `json:"field"` or `form:"field"` tags 2. **Content-Type mismatch**: Ensure client sends correct Content-Type header 3. **Validation errors**: Check validation tags and requirements 4. **Unexported fields**: Only exported (capitalized) struct fields are bound ``` type User struct { Name string `json:"name" binding:"required"` // ✓ Correct Email string `json:"email"` // ✓ Correct age int `json:"age"` // ✗ Won't bind (unexported) } ``` See [Binding and validation](/en/docs/binding/binding-and-validation/) for details. ---- url: https://gin-gonic.com/en/docs/rendering/html-rendering/ ---- [Skip to content](#_top) # HTML rendering Gin uses the [html/template](https://pkg.go.dev/html/template) package for HTML rendering. For more information about how to use them, including available placeholders, see the documentation for [text/template](https://pkg.go.dev/text/template) Use LoadHTMLGlob() or LoadHTMLFiles() to select the HTML files to load. ``` 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(":8080") } ``` templates/index.tmpl ```

{{ .title }}

``` Using templates with same name in different directories ``` 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(":8080") } ``` **Note:** Please wrap your HTML template in the `{{define }} {{end}}` block and define your template file with the relative path ``. Otherwise, GIN will not properly parse the template files. 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 }} ``` ### Loading templates from an http.FileSystem (v1.11+) [Section titled “Loading templates from an http.FileSystem (v1.11+)”](#loading-templates-from-an-httpfilesystem-v111) If your templates are embedded or provided by an `http.FileSystem`, use `LoadHTMLFS`: ``` import ( "embed" "io/fs" "net/http" "github.com/gin-gonic/gin" ) //go:embed templates var tmplFS embed.FS func main() { r := gin.Default() sub, _ := fs.Sub(tmplFS, "templates") r.LoadHTMLFS(http.FS(sub), "**/*.tmpl") r.GET("/", func(c *gin.Context) { c.HTML(http.StatusOK, "index.tmpl", gin.H{"title": "From FS"}) }) r.Run(":8080") } ``` ### Security warning: `template.HTML()` bypasses auto-escaping [Section titled “Security warning: template.HTML() bypasses auto-escaping”](#security-warning-templatehtml-bypasses-auto-escaping) Go’s `html/template` package automatically escapes values inserted into templates to prevent Cross-Site Scripting (XSS). However, when you cast a string to `template.HTML()`, you explicitly bypass this protection. If the string contains user-supplied input, an attacker can inject arbitrary JavaScript. **Unsafe – never use `template.HTML()` with user input:** ``` // DANGEROUS: attacker controls userInput, which could be: // c.HTML(http.StatusOK, "page.tmpl", gin.H{ "content": template.HTML(userInput), // XSS vulnerability! }) ``` **Safe – let the template engine escape user input automatically:** ``` // SAFE: html/template will escape any HTML/JS in userInput c.HTML(http.StatusOK, "page.tmpl", gin.H{ "content": userInput, // auto-escaped by html/template }) ``` Only use `template.HTML()` for content you fully control, such as static HTML snippets defined in your own code. Never use it with values that originate from user input, database fields populated by users, or any other untrusted source. ### Custom Template renderer [Section titled “Custom Template renderer”](#custom-template-renderer) You can also use your own html template render ``` import "html/template" func main() { router := gin.Default() html := template.Must(template.ParseFiles("file1", "file2")) router.SetHTMLTemplate(html) router.Run(":8080") } ``` ### Custom Delimiters [Section titled “Custom Delimiters”](#custom-delimiters) You may use custom delims ``` router := gin.Default() router.Delims("{[{", "}]}") router.LoadHTMLGlob("/path/to/templates") ``` ### Custom Template Funcs [Section titled “Custom Template Funcs”](#custom-template-funcs) See the detail [example code](https://github.com/gin-gonic/examples/tree/master/template). 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(2017, 07, 01, 0, 0, 0, 0, time.UTC), }) }) router.Run(":8080") } ``` raw\.tmpl Terminal window ``` Date: {[{.now | formatAsDate}]} ``` Result: Terminal window ``` Date: 2017/07/01 ``` ---- url: https://gin-gonic.com/en/docs/middleware/ ---- [Skip to content](#_top) # Middleware Middleware in Gin provides a way to process HTTP requests before they reach route handlers. A middleware function has the same signature as a route handler – `gin.HandlerFunc` – and typically calls `c.Next()` to pass control to the next handler in the chain. ## How middleware works [Section titled “How middleware works”](#how-middleware-works) Gin uses an **onion model** for middleware execution. Each middleware runs in two phases: 1. **Pre-handler** – code before `c.Next()` runs before the route handler. 2. **Post-handler** – code after `c.Next()` runs after the route handler returns. This means middleware wraps around the handler like layers of an onion. The first middleware attached is the outermost layer. ``` func Logger() gin.HandlerFunc { return func(c *gin.Context) { start := time.Now() // Pre-handler phase c.Next() // Post-handler phase latency := time.Since(start) log.Printf("Request took %v", latency) } } ``` ## Attaching middleware [Section titled “Attaching middleware”](#attaching-middleware) There are three ways to attach middleware in Gin: ``` // 1. Global -- applies to all routes router := gin.New() router.Use(Logger(), Recovery()) // 2. Group -- applies to all routes in the group v1 := router.Group("/v1") v1.Use(AuthRequired()) { v1.GET("/users", listUsers) } // 3. Per-route -- applies to a single route router.GET("/benchmark", BenchmarkMiddleware(), benchHandler) ``` Middleware attached at a broader scope runs first. In the example above, a request to `GET /v1/users` would execute `Logger` then `Recovery` then `AuthRequired` then `listUsers`. ## In this section [Section titled “In this section”](#in-this-section) * [**Using middleware**](./using-middleware/) – Attach middleware globally, to groups, or individual routes * [**Custom middleware**](./custom-middleware/) – Write your own middleware functions * [**Using BasicAuth middleware**](./using-basicauth/) – HTTP Basic Authentication * [**Goroutines inside middleware**](./goroutines-inside-middleware/) – Safely run background tasks from middleware * [**Custom HTTP configuration**](./custom-http-config/) – Error handling and recovery in middleware * [**Security headers**](./security-headers/) – Set common security headers ---- url: https://gin-gonic.com/en/docs/middleware/custom-middleware/ ---- [Skip to content](#_top) # Custom Middleware Gin middleware is a function that returns a `gin.HandlerFunc`. Middleware runs before and/or after the main handler, which makes it useful for logging, authentication, error handling, and other cross-cutting concerns. ### Middleware execution flow [Section titled “Middleware execution flow”](#middleware-execution-flow) A middleware function has two phases, divided by the call to `c.Next()`: * **Before `c.Next()`** – Code here runs before the request reaches the main handler. Use this phase for setup tasks such as recording the start time, validating tokens, or setting context values with `c.Set()`. * **`c.Next()`** – This calls the next handler in the chain (which may be another middleware or the final route handler). Execution pauses here until all downstream handlers have completed. * **After `c.Next()`** – Code here runs after the main handler has finished. Use this phase for cleanup, logging response status, or measuring latency. If you want to stop the chain entirely (for example, when authentication fails), call `c.Abort()` instead of `c.Next()`. This prevents any remaining handlers from executing. You can combine it with a response, for example `c.AbortWithStatusJSON(401, gin.H{"error": "unauthorized"})`. ``` package main import ( "log" "time" "github.com/gin-gonic/gin" ) func Logger() gin.HandlerFunc { return func(c *gin.Context) { t := time.Now() // Set example variable c.Set("example", "12345") // before request c.Next() // after request latency := time.Since(t) log.Print(latency) // access the status we are sending 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) // it would print: "12345" log.Println(example) }) // Listen and serve on 0.0.0.0:8080 r.Run(":8080") } ``` ### Try it [Section titled “Try it”](#try-it) Terminal window ``` curl http://localhost:8080/test ``` The server logs will show the request latency and HTTP status code for every request that passes through the `Logger` middleware. ## See also [Section titled “See also”](#see-also) * [Error handling middleware](/en/docs/middleware/error-handling-middleware/) * [Using middleware](/en/docs/middleware/using-middleware/) ---- url: https://gin-gonic.com/en/docs/rendering/secure-json/ ---- [Skip to content](#_top) # SecureJSON `SecureJSON` protects against a class of vulnerability known as **JSON hijacking**. In older browsers (primarily Internet Explorer 9 and earlier), a malicious page could include a `