Exploring Gin 1.12: New Features That Boost Performance and Flexibility

BSON Protocol Support

Handlers can return MongoDB documents directly as BSON, eliminating the need for a second JSON conversion step. The response automatically sets Content-Type: application/bson.

package main

import (
    "context"
    "log"
    "time"
    "github.com/gin-gonic/gin"
    "go.mongodb.org/mongo-driver/bson"
    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
)

type User struct {
    Name   string    `bson:"name" json:"name"`
    Age    int       `bson:"age" json:"age"`
    Email  string    `bson:"email" json:"email"`
    JoinAt time.Time `bson:"join_at" json:"join_at"`
}

func main() {
    r := gin.Default()
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    client, _ := mongo.Connect(ctx, options.Client().ApplyURI("mongodb://localhost:27017"))
    col := client.Database("test_db").Collection("users")

    r.GET("/user/:name", func(c *gin.Context) {
        var user User
        err := col.FindOne(ctx, bson.M{"name": c.Param("name")}).Decode(&user)
        if err != nil {
            c.JSON(404, gin.H{"error": "user not found"})
            return
        }
        c.BSON(200, user) // auto sets Content-Type: application/bson
    })
    r.Run(":8080")
}

Benefits include reduced serialization overhead (≈15‑30% faster response), native support for MongoDB‑specific types such as ObjectID and Decimal128, and simpler code without manual bson.Marshal calls.

Context Enhancements

The new SetError / GetError API stores typed errors in the Gin context, allowing downstream handlers to retrieve them without type assertions.

// Middleware: verify Authorization header
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        if c.GetHeader("Authorization") == "" {
            c.SetError(gin.Error{Err: fmt.Errorf("missing Authorization header"), Type: gin.ErrorTypePublic})
            c.AbortWithStatus(401)
            return
        }
        c.Next()
    }
}

// Route using the middleware
r.GET("/profile", AuthMiddleware(), func(c *gin.Context) {
    if err := c.GetError(); err != nil {
        c.JSON(401, gin.H{"msg": err.Err.Error()}) // no type assertion needed
        return
    }
    c.JSON(200, gin.H{"data": "ok"})
})

Flexible Binding with Custom Types

Custom types that implement UnmarshalText are automatically parsed from query parameters. The example defines a Date type and binds it via ShouldBindQuery. Invalid formats trigger a 400 response.

type Date time.Time

func (d *Date) UnmarshalText(text []byte) error {
    t, err := time.Parse("2006-01-02", string(text))
    if err != nil {
        return err
    }
    *d = Date(t)
    return nil
}

type QueryParams struct {
    StartDate Date `form:"start_date" binding:"required"`
    EndDate   Date `form:"end_date" binding:"required"`
}

r.GET("/stats", func(c *gin.Context) {
    var params QueryParams
    if err := c.ShouldBindQuery(¶ms); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, params) // UnmarshalText invoked automatically
})

// Test cases
// ✅ Correct format
// curl "http://localhost:8080/stats?start_date=2026-03-01&end_date=2026-03-10"
// ❌ Bad format, auto 400
// curl "http://localhost:8080/stats?start_date=2026/03/01"

Escaped Path Routing

Enabling UseRawPath = true and disabling automatic unescaping preserves characters such as / and : in path parameters.

func main() {
    r := gin.Default()
    r.UseRawPath = true
    r.UnescapePathValues = false
    r.GET("/user/:id", func(c *gin.Context) {
        // c.Param("id") returns the decoded value
        c.JSON(200, gin.H{"user_id": c.Param("id")})
    })
    r.Run(":8080")
}

// Request example
// curl "http://localhost:8080/user/user%3A123%2F456"
// Response: {"user_id":"user:123/456"}

Colored Latency Logs

The logger colors output based on request latency: green for < 100 ms, yellow for 100‑500 ms, and red for > 500 ms. This helps operators spot slow requests quickly.

[GIN]2026/03/13-10:24:35|200|🟢 3.2ms|GET /api/fast
[GIN]2026/03/13-10:24:36|200|🔴 852ms|POST /api/slow-task

Production environments can disable console colors with gin.DisableConsoleColor() to keep log files clean.

Protobuf Content Negotiation

Handlers can negotiate between JSON and Protobuf based on the Accept header. The example compiles a user.proto file to a Go struct UserResponse and uses c.Negotiate to select the appropriate representation.

// Assume user.proto generated:
// type UserResponse struct { Name string; Age int32; ... }

r.GET("/user/1", func(c *gin.Context) {
    protoData := &UserResponse{Name: "Alice", Age: 28}
    c.Negotiate(200, gin.Negotiate{Offered: []string{gin.MIMEJSON, "application/x-protobuf"}, Data: map[string]interface{}{
        gin.MIMEJSON: gin.H{"name": "Alice", "age": 28},
        "application/x-protobuf": protoData,
    }})
})

// Client requests
// curl -H "Accept: application/json" /user/1   # JSON response
// curl -H "Accept: application/x-protobuf" /user/1   # Protobuf response

Comprehensive Demo: User Microservice

The following example combines all new capabilities: raw‑path routing, middleware‑based error handling, BSON/Protobuf adaptive responses, and custom binding.

func main() {
    r := gin.New()
    r.UseRawPath = true // support special characters
    r.Use(AuthMiddleware(), gin.Logger())

    r.GET("/user/:id", getUser)          // BSON/Protobuf adaptive
    r.GET("/files/:path", getFile)       // escaped path support
    r.POST("/user", createUser)          // custom binding
    r.Run(":8080")
}

func getUser(c *gin.Context) {
    // 1. Check middleware error
    if err := c.GetError(); err != nil {
        c.BSON(401, gin.H{"error": err.Err.Error()})
        return
    }
    // 2. Content negotiation (JSON, Protobuf, BSON)
    user := fetchUser(c.Param("id"))
    c.Negotiate(200, gin.Negotiate{Offered: []string{gin.MIMEJSON, gin.MIMEProtoBuf, gin.MIMEBSON}, Data: user})
}

Upgrade Guidance

MongoDB microservices : adopt BSON support to remove the JSON conversion layer.

gRPC gateways : use Protobuf negotiation to unify HTTP and gRPC payloads.

File/path services : enable UseRawPath to handle encoded characters safely.

Standard CRUD applications : benefit from typed error propagation and colored latency logs.

Compatibility : 100% backward compatible; upgrade without breaking existing code.

Summary

Gin 1.12 follows a "small steps, fast iterations" philosophy, delivering concrete, real‑world solutions: native BSON responses, type‑safe context error handling, custom binding via UnmarshalText, raw‑path routing, latency‑aware colored logs, and HTTP + gRPC content negotiation, all while remaining fully backward compatible.