Gin

https://gin-gonic.com/en/docs
Admin
Gin is a high-performance HTTP web framework for Go, offering a Martini-like API with superior speed...
Tokens:89,835
Snippets:681
Trust Score:9.4
Update:2 days ago
Show doc for...
Tokens:
Raw
### GORM with Gin: Product CRUD Example

Source: https://gin-gonic.com/en/docs/server-config/database/

Complete example of using GORM with Gin. It sets up a PostgreSQL connection, auto-migrates a Product model, and defines POST and GET endpoints for creating and retrieving products. Requires a running PostgreSQL database with the given DSN.

```go
package main

import (
  "net/http"

  "github.com/gin-gonic/gin"
  "gorm.io/driver/postgres"
  "gorm.io/gorm"
)

type Product struct {
  gorm.Model
  Name  string  `json:"name"`
  Price float64 `json:"price"`
}

func main() {
  dsn := "host=localhost user=app dbname=mydb port=5432 sslmode=disable"
  db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
  if err != nil {
    panic("failed to connect to database")
  }

  // Auto-migrate the schema
  db.AutoMigrate(&Product{})

  r := gin.Default()

  r.POST("/products", func(c *gin.Context) {
    var p Product
    if err := c.ShouldBindJSON(&p); err != nil {
      c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
      return
    }
    if err := db.Create(&p).Error; err != nil {
      c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create product"})
      return
    }
    c.JSON(http.StatusCreated, p)
  })

  r.GET("/products/:id", func(c *gin.Context) {
    var p Product
    if err := db.First(&p, c.Param("id")).Error; err != nil {
      c.JSON(http.StatusNotFound, gin.H{"error": "product not found"})
      return
    }
    c.JSON(http.StatusOK, p)
  })

  r.Run(":8080")
}
```

--------------------------------

### Example Gin application with setupRouter and postUser

Source: https://gin-gonic.com/en/docs/testing/

Defines a User struct with JSON tags, a setupRouter function that creates a Gin engine with a GET /ping route, and a postUser function that adds a POST /user/add route binding JSON. The main function sets up the router and runs it on port 8080.

```go
package main

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

type User struct {
  Username string `json:"username"`
  Gender   string `json:"gender"`
}

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

func postUser(router *gin.Engine) *gin.Engine {
  router.POST("/user/add", func(c *gin.Context) {
    var user User
    c.BindJSON(&user)
    c.JSON(200, user)
  })
  return router
}

func main() {
  router := setupRouter()
  router = postUser(router)
  router.Run(":8080")
}
```

--------------------------------

### GET /welcome

Source: https://gin-gonic.com/en/docs/routing/querystring-param/

An example route that reads query parameters firstname and lastname, using a default value for firstname when missing.

```APIDOC
## GET /welcome

### Description
Reads the query parameters `firstname` and `lastname` from the request URL. If `firstname` is not provided, it defaults to "Guest". Returns a greeting string.

### Method
GET

### Endpoint
/welcome

### Parameters
#### Query Parameters
- **firstname** (string) - Optional - The first name to greet. Defaults to "Guest" if not provided.
- **lastname** (string) - Optional - The last name to greet. If not provided, an empty string is used.

### Request Example
```
curl "http://localhost:8080/welcome?firstname=Jane&lastname=Doe"
```

### Response
#### Success Response (200)
- **body** (string) - A greeting message in the format "Hello {firstname} {lastname}".

#### Response Example
```
Hello Jane Doe
```

```

--------------------------------

### Scaffold a full-featured example

Source: https://gin-gonic.com/en/docs/quickstart/

Downloads a basic Gin example from the official examples repository and saves it as main.go.

```bash
curl https://raw.githubusercontent.com/gin-gonic/examples/master/basic/main.go > main.go
```

--------------------------------

### Add Gin dependency

Source: https://gin-gonic.com/en/docs/quickstart/

Downloads and installs the Gin framework package using the go get command.

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

--------------------------------

### Setting up global, group, and per-route middleware in Gin

Source: https://gin-gonic.com/en/docs/middleware/using-middleware/

Complete example showing how to create a Gin router with gin.New(), add global middleware (Logger and Recovery), per-route middleware, and group middleware with nested groups. Note that gin.Default() is a convenience function that includes Logger and Recovery by default, while gin.New() starts with no middleware.

```go
package main

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

func main() {
  // Creates a router without any middleware by default
  router := gin.New()

  // Global middleware
  // Logger middleware will write the logs to gin.DefaultWriter even if you set with GIN_MODE=release.
  // By default gin.DefaultWriter = os.Stdout
  router.Use(gin.Logger())

  // Recovery middleware recovers from any panics and writes a 500 if there was one.
  router.Use(gin.Recovery())

  // Per route middleware, you can add as many as you desire.
  router.GET("/benchmark", MyBenchLogger(), benchEndpoint)

  // Authorization group
  // authorized := router.Group("/", AuthRequired())
  // exactly the same as:
  authorized := router.Group("/")
  // per group middleware! in this case we use the custom created
  // AuthRequired() middleware just in the "authorized" group.
  authorized.Use(AuthRequired())
  {
    authorized.POST("/login", loginEndpoint)
    authorized.POST("/submit", submitEndpoint)
    authorized.POST("/read", readEndpoint)

    // nested group
    testing := authorized.Group("testing")
    testing.GET("/analytics", analyticsEndpoint)
  }

  // Listen and serve on 0.0.0.0:8080
  router.Run(":8080")
}
```

--------------------------------

### Basic tests for GET /ping and POST /user/add using httptest and testify

Source: https://gin-gonic.com/en/docs/testing/

Uses net/http/httptest to create a recorder and send requests to the router. TestPingRoute checks the GET /ping response, while TestPostUser marshals an example user to JSON, posts it to /user/add, and asserts the response body matches the input JSON.

```go
package main

import (
  "net/http"
  "net/http/httptest"
  "encoding/json"
  "testing"
  "strings"

  "github.com/stretchr/testify/assert"
)

func TestPingRoute(t *testing.T) {
  router := setupRouter()

  w := httptest.NewRecorder()
  req, _ := http.NewRequest("GET", "/ping", nil)
  router.ServeHTTP(w, req)

  assert.Equal(t, 200, w.Code)
  assert.Equal(t, "pong", w.Body.String())
}

// Test for POST /user/add
func TestPostUser(t *testing.T) {
  router := setupRouter()
  router = postUser(router)

  w := httptest.NewRecorder()

  // Create an example user for testing
  exampleUser := User{
    Username: "test_name",
    Gender:   "male",
  }
  userJson, _ := json.Marshal(exampleUser)
  req, _ := http.NewRequest("POST", "/user/add", strings.NewReader(string(userJson)))
  router.ServeHTTP(w, req)

  assert.Equal(t, 200, w.Code)
  // Compare the response body with the json data of exampleUser
  assert.Equal(t, string(userJson), w.Body.String())
}
```

--------------------------------

### Set and get a cookie with Gin

Source: https://gin-gonic.com/en/docs/server-config/cookie/

A complete Gin example that sets a cookie if none exists and reads it. Uses c.Cookie() to read and c.SetCookie() to set with maxAge 3600, path '/', domain 'localhost', secure false, httpOnly true.

```go
import (
  "fmt"

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

func main() {

  router := gin.Default()

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

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

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

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

  router.Run()
}
```

--------------------------------

### Install wscat with npm

Source: https://gin-gonic.com/en/docs/server-config/websocket/

Install the wscat command-line WebSocket client globally using npm.

```bash
npm install -g wscat
```

--------------------------------

### Test Gin handlers with httptest

Source: https://gin-gonic.com/en/docs/faq/

Use net/http/httptest to create a test request and recorder, then assert on the response code and body. The example tests a GET /ping route and uses assert.Equal and assert.Contains.

```go
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")
}
```

--------------------------------

### Install gorilla/websocket package

Source: https://gin-gonic.com/en/docs/server-config/websocket/

Run this command to install the gorilla/websocket package, which is required for WebSocket support in Gin.

```bash
go get github.com/gorilla/websocket
```

--------------------------------

### Use gin-helmet for Default Security Headers

Source: https://gin-gonic.com/en/docs/middleware/security-headers/

Alternative approach using the gin-helmet package to apply default security headers. Requires installing the package with `go get github.com/danielkov/gin-helmet/ginhelmet`.

```go
package main

import (
  "github.com/gin-gonic/gin"
  "github.com/danielkov/gin-helmet/ginhelmet"
)

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

  // Use default security headers
  r.Use(ginhelmet.Default())

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

  r.Run()
}
```

--------------------------------

### Gin HTTP method routing example

Source: https://gin-gonic.com/en/docs/routing/http-method/

Complete Go program that creates a Gin router with default middleware and registers handlers for GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS methods. Each handler returns a JSON response with the method name, except HEAD and OPTIONS which return status OK. The server runs on :8080 by default or uses the PORT environment variable.

```go
package main

import (
  "net/http"

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

func getting(c *gin.Context) {
  c.JSON(http.StatusOK, gin.H{"method": "GET"})
}

func posting(c *gin.Context) {
  c.JSON(http.StatusOK, gin.H{"method": "POST"})
}

func putting(c *gin.Context) {
  c.JSON(http.StatusOK, gin.H{"method": "PUT"})
}

func deleting(c *gin.Context) {
  c.JSON(http.StatusOK, gin.H{"method": "DELETE"})
}

func patching(c *gin.Context) {
  c.JSON(http.StatusOK, gin.H{"method": "PATCH"})
}

func head(c *gin.Context) {
  c.Status(http.StatusOK)
}

func options(c *gin.Context) {
  c.Status(http.StatusOK)
}

func main() {
  // Creates a gin router with default middleware:
  // logger and recovery (crash-free) middleware
  router := gin.Default()

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

  // By default it serves on :8080 unless a
  // PORT environment variable was defined.
  router.Run()
  // router.Run(":3000") for a hard coded port
}
```

--------------------------------

### Install gin-contrib/openmetrics

Source: https://gin-gonic.com/en/docs/server-config/metrics/

Command to install the gin-contrib/openmetrics middleware package.

```bash
go get github.com/gin-contrib/openmetrics
```

--------------------------------

### Install gin-contrib/sessions

Source: https://gin-gonic.com/en/docs/middleware/session-management/

Command to install the gin-contrib/sessions middleware package.

```bash
go get github.com/gin-contrib/sessions
```

--------------------------------

### Quick start with autotls.Run

Source: https://gin-gonic.com/en/docs/server-config/support-lets-encrypt/

Use autotls.Run to serve HTTPS automatically for the given domains. Requires the gin-gonic/autotls package and a Gin router. The server must be reachable on ports 80 and 443 from the public internet.

```go
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"))
}
```

--------------------------------

### Install Air for live reload

Source: https://gin-gonic.com/en/docs/faq/

Install the Air tool for automatic live reloading during development. Run this command in a terminal.

```bash
go install github.com/air-verse/air@latest
```

--------------------------------

### Render JSON, XML, YAML, and ProtoBuf responses with Gin

Source: https://gin-gonic.com/en/docs/rendering/rendering/

Sets up a Gin router with endpoints for each format. Uses c.JSON, c.XML, c.YAML, and c.ProtoBuf, each accepting an HTTP status code and data. The JSON example shows both a gin.H map and a struct with a json tag. The ProtoBuf example uses a test proto message from the testdata/protoexample package.

```go
package main

import (
  "net/http"

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

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

  // gin.H is a shortcut for map[string]interface{}
  router.GET("/someJSON", func(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
  })

  router.GET("/moreJSON", func(c *gin.Context) {
    // You also can use a struct
    var msg struct {
      Name    string `json:"user"`
      Message string
      Number  int
    }
    msg.Name = "Lena"
    msg.Message = "hey"
    msg.Number = 123
    // Note that msg.Name becomes "user" in the JSON
    // Will output  :   {"user": "Lena", "Message": "hey", "Number": 123}
    c.JSON(http.StatusOK, msg)
  })

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

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

  router.GET("/someProtoBuf", func(c *gin.Context) {
    reps := []int64{int64(1), int64(2)}
    label := "test"
    // The specific definition of protobuf is written in the testdata/protoexample file.
    data := &protoexample.Test{
      Label: &label,
      Reps:  reps,
    }
    // Note that data becomes binary data in the response
    // Will output protoexample.Test protobuf serialized data
    c.ProtoBuf(http.StatusOK, data)
  })

  // Listen and serve on 0.0.0.0:8080
  router.Run(":8080")
}
```

--------------------------------

### Redis-based session example

Source: https://gin-gonic.com/en/docs/middleware/session-management/

Complete Gin application using Redis-backed sessions. It creates a Redis store with a pool size, network, address, password, and secret key, and provides /set and /get endpoints to store and retrieve a counter.

```go
package main

import (
  "net/http"

  "github.com/gin-contrib/sessions"
  "github.com/gin-contrib/sessions/redis"
  "github.com/gin-gonic/gin"
)

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

  // Connect to Redis for session storage
  store, err := redis.NewStore(10, "tcp", "localhost:6379", "", []byte("secret"))
  if err != nil {
    panic(err)
  }
  r.Use(sessions.Sessions("mysession", store))

  r.GET("/set", func(c *gin.Context) {
    session := sessions.Default(c)
    session.Set("count", 1)
    session.Save()
    c.JSON(http.StatusOK, gin.H{"count": 1})
  })

  r.GET("/get", func(c *gin.Context) {
    session := sessions.Default(c)
    count := session.Get("count")
    c.JSON(http.StatusOK, gin.H{"count": count})
  })

  r.Run(":8080")
}
```

--------------------------------

### TrustedPlatform example

Source: https://gin-gonic.com/en/docs/server-config/trusted-proxies/

Shows how to set Engine.TrustedPlatform to a predefined platform header (Google App Engine, Cloudflare, Fly.io) or a custom header (e.g., X-CDN-Client-IP) to skip TrustedProxies checks. TrustedPlatform has higher priority than TrustedProxies.

```go
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()
}
```

--------------------------------

### Register GET and POST routes with Gin

Source: https://gin-gonic.com/en/docs/routing/

Shows how to register routes using router.GET and router.POST, handling a GET request with c.String and a POST request with c.PostForm and c.JSON. The server runs on port 8080 via router.Run.

```go
package main

import (
  "net/http"

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

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

  router.GET("/hello", func(c *gin.Context) {
    c.String(http.StatusOK, "Hello, World!")
  })

  router.POST("/users", func(c *gin.Context) {
    name := c.PostForm("name")
    c.JSON(http.StatusCreated, gin.H{"user": name})
  })

  router.Run(":8080")
}
```

--------------------------------

### Build with multiple build tags

Source: https://gin-gonic.com/en/docs/build-tags/

Combine multiple build tags by separating them with commas in the -tags flag. This example disables MsgPack and enables go-json simultaneously.

```bash
go build -tags=nomsgpack,go_json .
```

--------------------------------

### Go: Logger middleware and main function

Source: https://gin-gonic.com/en/docs/middleware/custom-middleware/

Complete example of a custom Logger middleware in Gin. It sets a context variable 'example', logs the request latency and response status after c.Next(). The main function registers the middleware with r.Use(Logger()) and defines a /test route that reads the context variable. Run with 'go run' and test with curl.

```go
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")
}
```

--------------------------------

### Sample output of custom log format

Source: https://gin-gonic.com/en/docs/logging/custom-log-format/

Example log line produced by the custom formatter, showing the format with client IP, timestamp, request details, status, latency, and user agent.

```text
::1 - [Fri, 07 Dec 2018 17:04:38 JST] "GET /ping HTTP/1.1 200 122.767µs "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.80 Safari/537.36" "
```

--------------------------------

### CORS middleware example with gin-contrib/cors

Source: https://gin-gonic.com/en/docs/faq/

Use the official gin-contrib/cors middleware to enable CORS. Shows default configuration and a customized configuration with allowed origins, methods, headers, credentials, and max age.

```go
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()
}
```

--------------------------------

### Cookie-based session example

Source: https://gin-gonic.com/en/docs/middleware/session-management/

Complete Gin application using cookie-based sessions. It sets up a session store with a secret key, and provides /login, /profile, and /logout endpoints to set, retrieve, and clear session data.

```go
package main

import (
  "net/http"

  "github.com/gin-contrib/sessions"
  "github.com/gin-contrib/sessions/cookie"
  "github.com/gin-gonic/gin"
)

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

  // Create cookie-based session store with a secret key
  store := cookie.NewStore([]byte("your-secret-key"))
  r.Use(sessions.Sessions("mysession", store))

  r.GET("/login", func(c *gin.Context) {
    session := sessions.Default(c)
    session.Set("user", "john")
    session.Save()
    c.JSON(http.StatusOK, gin.H{"message": "logged in"})
  })

  r.GET("/profile", func(c *gin.Context) {
    session := sessions.Default(c)
    user := session.Get("user")
    if user == nil {
      c.JSON(http.StatusUnauthorized, gin.H{"error": "not logged in"})
      return
    }
    c.JSON(http.StatusOK, gin.H{"user": user})
  })

  r.GET("/logout", func(c *gin.Context) {
    session := sessions.Default(c)
    session.Clear()
    session.Save()
    c.JSON(http.StatusOK, gin.H{"message": "logged out"})
  })

  r.Run(":8080")
}
```

--------------------------------

### Initialize Go module and project directory

Source: https://gin-gonic.com/en/docs/quickstart/

Creates a new project folder and initializes a Go module named 'gin-quickstart'. Run these commands in a terminal.

```bash
mkdir gin-quickstart && cd gin-quickstart
go mod init gin-quickstart
```

--------------------------------

### Serve static files with Static, StaticFS, and StaticFile

Source: https://gin-gonic.com/en/docs/rendering/serving-static-files/

Complete Gin example that serves a directory with Static, a custom file system with StaticFS, and a single file with StaticFile. The router listens on 0.0.0.0:8080. Note that the directory passed to Static or http.Dir is fully accessible to clients, so avoid sensitive files.

```go
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")
}
```

--------------------------------

### GET /user - Format Selection via Query Parameter

Source: https://gin-gonic.com/en/docs/rendering/

Example handler that serves the same data in multiple formats (JSON, XML, YAML) based on a 'format' query parameter.

```APIDOC
## GET /user

### Description
Returns user data in a format specified by the 'format' query parameter. Supports 'xml', 'yaml', and defaults to JSON.

### Method
GET

### Endpoint
/user

### Parameters
#### Query Parameters
- **format** (string) - Optional - Specifies the response format. Accepted values: 'xml', 'yaml'. If omitted or any other value, JSON is returned.

### Request Example
```
GET /user?format=xml
```

### Response
#### Success Response (200)
Returns user data in the requested format. The content-type header is set accordingly.

#### Response Example
For format=xml:
```xml
<map><name>Lena</name><role>admin</role></map>
```

For format=yaml:
```yaml
name: Lena
role: admin
```

For default (JSON):
```json
{"name":"Lena","role":"admin"}
```
```

--------------------------------

### Serve files with c.File, c.FileFromFS, and c.FileAttachment

Source: https://gin-gonic.com/en/docs/rendering/serving-data-from-file/

Complete Gin router setup demonstrating three file-serving methods: c.File for inline display, c.FileFromFS for http.FileSystem, and c.FileAttachment for downloads with a custom filename. Requires a local file 'local/file.go' and a directory '/var/www/assets'.

```go
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")
}
```

--------------------------------

### Initialize Air configuration

Source: https://gin-gonic.com/en/docs/faq/

Create a `.air.toml` configuration file in your project root by running `air init`.

```bash
air init
```

--------------------------------

### Basic usage: http.ListenAndServe with Gin router

Source: https://gin-gonic.com/en/docs/server-config/custom-http-config/

Pass the Gin router directly to http.ListenAndServe to start a basic HTTP server on port 8080. The router handles a GET /ping endpoint that returns 'pong'.

```go
package main

import (
  "net/http"

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

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

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

  http.ListenAndServe(":8080", router)
}
```

--------------------------------

### Return 405 Method Not Allowed with HandleMethodNotAllowed

Source: https://gin-gonic.com/en/docs/faq/

Set HandleMethodNotAllowed = true on a gin.Engine to return 405 instead of 404 for routes that don't support the requested HTTP method. The example shows a GET route and the resulting curl output.

```go
r := gin.Default()
r.HandleMethodNotAllowed = true

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

r.Run()
```

```bash
$ curl -X POST localhost:8080/ping

HTTP/1.1 405 Method Not Allowed
Allow: GET
```

--------------------------------

### main.go: Set up custom template funcs and route

Source: https://gin-gonic.com/en/docs/rendering/html-rendering/

Defines a formatAsDate function and registers it with Gin's SetFuncMap. Uses custom delimiters {[{ and }]} and loads raw.tmpl. Serves the /raw route with a date value.

```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")
}
```

--------------------------------

### Pass context to outbound HTTP call with NewRequestWithContext

Source: https://gin-gonic.com/en/docs/server-config/context/

Use c.Request.Context() to create an outbound HTTP request that is cancelled together with the incoming request. The example defines a GET /api/proxy handler that forwards the request to https://httpbin.org/delay/3 and returns the response.

```go
package main

import (
  "io"
  "net/http"

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

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

  r.GET("/api/proxy", func(c *gin.Context) {
    ctx := c.Request.Context()

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://httpbin.org/delay/3", nil)
    if err != nil {
      c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
      return
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
      c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
      return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    c.Data(resp.StatusCode, resp.Header.Get("Content-Type"), body)
  })

  r.Run(":8080")
}
```

--------------------------------

### Create a blank Gin engine with gin.New() and attach only Recovery middleware

Source: https://gin-gonic.com/en/docs/middleware/without-middleware/

This example creates a blank Gin router using gin.New(), attaches only the Recovery middleware, and defines a simple /ping endpoint. It omits the default Logger middleware, allowing you to replace it with your own logging or leave it out entirely.

```go
package main

import (
  "log"
  "net/http"

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

func main() {
  // Create a blank engine with no middleware.
  r := gin.New()

  // Attach only the middleware you need.
  r.Use(gin.Recovery())

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

  log.Fatal(r.Run(":8080"))
}
```

--------------------------------

### Serve static files with Static(), StaticFile(), and StaticFS()

Source: https://gin-gonic.com/en/docs/faq/

Use `Static()` to serve a directory, `StaticFile()` for a single file, and `StaticFS()` for an embedded filesystem (Go 1.16+).

```go
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()
}
```

--------------------------------

### Complete Gin application with /ping endpoint

Source: https://gin-gonic.com/en/docs/

A complete Gin application that creates a router with default middleware, defines a GET /ping endpoint returning JSON, and starts the server on port 8080. Save as main.go and run with 'go run main.go'.

```go
package main

import (
  "net/http"

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

func main() {
  // Create a Gin router with default middleware (logger and recovery)
  r := gin.Default()

  // Define a simple GET endpoint
  r.GET("/ping", func(c *gin.Context) {
    // Return JSON response
    c.JSON(http.StatusOK, gin.H{
      "message": "pong",
    })
  })

  // Start server on port 8080 (default)
  // Server will listen on 0.0.0.0:8080 (localhost:8080 on Windows)
  r.Run()
}
```

--------------------------------

### Access request context with c.Request.Context()

Source: https://gin-gonic.com/en/docs/server-config/context/

Use c.Request.Context() to get the standard context.Context for the current request. Pass this context to downstream calls like database queries or HTTP requests. The example logs the context's Done channel and returns a JSON response.

```go
package main

import (
  "log"
  "net/http"

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

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

  r.GET("/api/data", func(c *gin.Context) {
    ctx := c.Request.Context()

    // Pass ctx to any downstream function that accepts context.Context.
    log.Println("request context deadline:", ctx.Done())

    c.JSON(http.StatusOK, gin.H{"status": "ok"})
  })

  r.Run(":8080")
}
```

--------------------------------

### Set up multitemplate renderer with multiple templates

Source: https://gin-gonic.com/en/docs/rendering/multiple-template/

Use the multitemplate package to create a renderer that supports multiple templates. Add template files with AddFromFiles, assign the renderer to router.HTMLRender, and serve pages with c.HTML. This enables using block templates in Gin.

```go
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")
}
```

--------------------------------

### HTTP2 server push example with Gin

Source: https://gin-gonic.com/en/docs/server-config/http2-server-push/

Complete Go program using Gin to set up an HTTPS server with HTTP/2 server push. It serves a static asset and pushes it using pusher.Push() when the root route is accessed. Requires go1.8+ and runs with TLS using provided certificates.

```go
package main

import (
  "html/template"
  "log"

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

var html = template.Must(template.New("https").Parse(`
<html>
<head>
  <title>Https Test</title>
  <script src="/assets/app.js"></script>
</head>
<body>
  <h1 style="color:red;">Welcome, Ginner!</h1>
</body>
</html>
`))

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")
}
```

--------------------------------

### Pass context to database query with QueryRowContext

Source: https://gin-gonic.com/en/docs/server-config/context/

Use c.Request.Context() to pass the request context to a database query so it is cancelled if the client disconnects or the request times out. The example opens a PostgreSQL connection, defines a GET /api/users/:id handler, and uses QueryRowContext to fetch a user name.

```go
package main

import (
  "database/sql"
  "net/http"

  "github.com/gin-gonic/gin"
  _ "github.com/lib/pq"
)

func main() {
  db, err := sql.Open("postgres", "postgres://localhost/mydb?sslmode=disable")
  if err != nil {
    panic(err)
  }

  r := gin.Default()

  r.GET("/api/users/:id", func(c *gin.Context) {
    ctx := c.Request.Context()
    id := c.Param("id")

    var name string
    err := db.QueryRowContext(ctx, "SELECT name FROM users WHERE id = $1", id).Scan(&name)
    if err != nil {
      c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
      return
    }

    c.JSON(http.StatusOK, gin.H{"id": id, "name": name})
  })

  r.Run(":8080")
}
```

--------------------------------

### Create main.go file

Source: https://gin-gonic.com/en/docs/quickstart/

Creates an empty main.go file in the current directory.

```bash
touch main.go
```

--------------------------------

### Example JSON log output from slog middleware

Source: https://gin-gonic.com/en/docs/logging/structured-logging/

Sample log entry produced by the slog middleware when a GET request to /ping is made. Shows the structured JSON format with fields for time, level, message, method, path, query, status, latency, client IP, and body size.

```json
{"time":"2024-01-15T10:30:00Z","level":"INFO","msg":"request","method":"GET","path":"/ping","query":"","status":200,"latency":"125µs","client_ip":"127.0.0.1","body_size":18}
```

--------------------------------

### Custom binding using customerTag 'url'

Source: https://gin-gonic.com/en/docs/binding/bind-form-data-custom-struct-tag/

Defines a custom binding that implements the binding.Binding interface. It parses form and multipart data, then uses binding.MapFormWithTag to map values to struct fields using the 'url' tag. The example includes a FormA struct with a 'url' tag and a GET route that uses MustBindWith.

```go
package main

import (
  "net/http"

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

const (
  customerTag   = "url"
  defaultMemory = 32 << 20
)

type customerBinding struct{}

func (customerBinding) Name() string {
  return "form"
}

func (customerBinding) Bind(req *http.Request, obj any) error {
  if err := req.ParseForm(); err != nil {
    return err
  }
  if err := req.ParseMultipartForm(defaultMemory); err != nil {
    if err != http.ErrNotMultipart {
      return err
    }
  }
  if err := binding.MapFormWithTag(obj, req.Form, customerTag); err != nil {
    return err
  }
  return validate(obj)
}

func validate(obj any) error {
  if binding.Validator == nil {
    return nil
  }
  return binding.Validator.ValidateStruct(obj)
}

// FormA is an external type that we can't modify its tag
type FormA struct {
  FieldA string `url:"field_a"`
}

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

  router.GET("/list", func(c *gin.Context) {
    var urlBinding = customerBinding{}
    var opt FormA
    if err := c.MustBindWith(&opt, urlBinding); err != nil {
      return
    }
    c.JSON(http.StatusOK, gin.H{"field_a": opt.FieldA})
  })

  router.Run(":8080")
}
```

--------------------------------

### Limit/offset pagination in Gin

Source: https://gin-gonic.com/en/docs/routing/api-design/

Implements a GET /api/articles endpoint with limit and offset query parameters, defaulting to 20 and 0 respectively, and capping limit at 100. The response includes a meta object with limit, offset, and total. The database call is commented out, so the example returns an empty data array and total of 0.

```go
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")
}
```

--------------------------------

### Gin handler using c.DefaultQuery and c.Query

Source: https://gin-gonic.com/en/docs/routing/querystring-param/

Sets up a Gin router with a GET /welcome endpoint. Uses c.DefaultQuery("firstname", "Guest") to provide a default when the parameter is missing, and c.Query("lastname") to read the lastname parameter. Responds with a greeting string.

```go
package main

import (
  "net/http"

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

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

  // Query string parameters are parsed using the existing underlying request object.
  // The request responds to a url matching:  /welcome?firstname=Jane&lastname=Doe
  router.GET("/welcome", func(c *gin.Context) {
    firstname := c.DefaultQuery("firstname", "Guest")
    lastname := c.Query("lastname") // shortcut for c.Request.URL.Query().Get("lastname")

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

--------------------------------

### Gin model binding example with JSON, XML, and form endpoints

Source: https://gin-gonic.com/en/docs/binding/binding-and-validation/

Complete Go program defining a Login struct with binding tags and three POST handlers using ShouldBindJSON, ShouldBindXML, and ShouldBind (inferred by Content-Type). Demonstrates required field validation and error responses.

```go
// 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 (
  //  <?xml version="1.0" encoding="UTF-8"?>
  //  <root>
  //    <user>manu</user>
  //    <password>123</password>
  //  </root>)
  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")
}
```

--------------------------------

### GET /someGet

Source: https://gin-gonic.com/en/docs/routing/http-method/

Registers a route that responds to HTTP GET requests. The handler returns a JSON response with the method name.

```APIDOC
## GET /someGet

### Description
Registers a route that responds to HTTP GET requests. The handler returns a JSON response with the method name.

### Method
GET

### Endpoint
/someGet

### Request Example
```
curl -X GET http://localhost:8080/someGet
```

### Response
#### Success Response (200)
- **method** (string) - The HTTP method name, e.g., "GET"

#### Response Example
```json
{"method":"GET"}
```
```
Tokens:
Raw