Gin HTTP Web Framework for Go

Gin is a high-performance HTTP web framework. In real-world routing workloads (modeled after the GitHub API with 203 routes), Gin ranks in the top tier of routers, achieving approximately 9,944 ns/op with zero heap allocations and zero allocations per operation. This makes it highly suitable for latency-sensitive applications.

/* 
Benchmark Results (GitHub API - 203 routes):
| Rank | Router | ns/op | B/op | allocs/op |
| :--: | :--- | ---: | ---: | ---: |
| 1 | Gin | 9,944 | 0 | 0 |
*/

Gin provides two ways to initialize a router:

1. gin.Default(): Creates a router with Logger and Recovery middleware already attached.
2. gin.New(): Creates a blank router without any middleware by default. Use this if you want full control over your middleware stack.

// Default with Logger and Recovery middleware
r := gin.Default()

// Blank Gin without middleware
r := gin.New()

If you want to customize how a specific type is parsed from a string (like a date format), you can implement the encoding.TextUnmarshaler interface. To tell Gin to use this interface, add parser=encoding.TextUnmarshaler to the uri or form tag.

Alternatively, if you want to customize how Gin binds the type specifically (and potentially override error messages), implement the binding.BindUnmarshaler interface. If a type implements both, Gin uses BindUnmarshaler by default.

// Using encoding.TextUnmarshaler
type Birthday string

func (b *Birthday) UnmarshalText(text []byte) error {
  *b = Birthday(strings.Replace(string(text), "-", "/", -1))
  return nil
}

type request struct {
  Birthday Birthday `form:"birthday,parser=encoding.TextUnmarshaler"` 
}

Gin supports an extensible middleware system for tasks like authentication, logging, CORS, and more. You can find official and community middleware in these repositories:

• gin-contrib: Official collection including JWT, Basic Auth, Sessions, CORS, Rate limiting, Compression, Logging, Metrics, Tracing, Static file serving, and Template engines.
• gin-gonic/contrib: Additional community-contributed middleware.

When starting a new Goroutine inside a Gin handler or middleware, do not use the original *gin.Context. The original context is not thread-safe and may be recycled before the Goroutine finishes. Instead, use c.Copy() to create a read-only copy of the context specifically for use within the Goroutine.

r.GET("/long_async", func(c *gin.Context) {
  // create copy to be used inside the goroutine
  cCp := c.Copy()
  go func() {
    time.Sleep(5 * time.Second)
    // use the copied context "cCp"
    log.Println("Done! in path " + cCp.Request.URL.Path)
  }()
})

Standard binding methods like ShouldBindJSON or ShouldBindXML consume the c.Request.Body stream. Once read, the body is empty (EOF) and cannot be read again by another binding call.

To bind the same request body into different structs (e.g., to try multiple formats), use ShouldBindBodyWith. This method reads the body and stores it in the Gin context so it can be reused.

Note: This has a slight performance impact because the body is buffered. Use it only when necessary. It is primarily useful for JSON, XML, MsgPack, and ProtoBuf formats.

// Use ShouldBindBodyWith to allow multiple bindings
if err := c.ShouldBindBodyWith(&objA, binding.JSON); err == nil {
  // Success with JSON
} else if err := c.ShouldBindBodyWith(&objB, binding.XML); err == nil {
  // Success with XML
}

To reduce the binary size of your executable, you can disable the MsgPack rendering feature by specifying the nomsgpack build tag during compilation.

go build -tags=nomsgpack .

You can extend Gin's validation capabilities by registering custom validation functions with the underlying validator engine. This is useful for domain-specific logic, such as checking if a date is in the future.

To do this, access the validator engine via binding.Validator.Engine() and call RegisterValidation.

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

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

// Use in struct:
type Booking struct {
  CheckIn time.Time `form:"check_in" binding:"required,bookabledate"` 
}

To handle file uploads, set router.MaxMultipartMemory to limit memory usage (default is 32 MiB).

Single file: Use c.FormFile("field") to get the file and c.SaveUploadedFile(file, dst) to save it.

Multiple files: Use c.MultipartForm() to get the form, then iterate over form.File["field[]"].

router.MaxMultipartMemory = 8 << 20 // 8 MiB
router.POST("/upload", func(c *gin.Context) {
  file, _ := c.FormFile("file")
  c.SaveUploadedFile(file, "/path/to/destination")
  c.String(http.StatusOK, "'%s' uploaded!", file.Filename)
})

router.MaxMultipartMemory = 8 << 20
router.POST("/upload", func(c *gin.Context) {
  file, _ := c.FormFile("file")
  c.SaveUploadedFile(file, "/path/to/destination")
})

Sources: docs/doc.md

To run the application after saving it as main.go:

1. Execute go run main.go in your terminal.
2. The server will start listening on 0.0.0.0:8080 (or localhost:8080 on Windows).
3. Access the endpoint at http://localhost:8080/ping to see the JSON response.