Exploring Gin 1.12: BSON Support, Enhanced Context, Flexible Binding, and Protobuf Negotiation

Introduction

This guide reviews the major additions in Gin 1.12, focusing on features that simplify microservice development and improve performance.

1️⃣ BSON Protocol Support

Gin can now return MongoDB documents directly as BSON, eliminating the need for JSON conversion.

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": "用户不存在"})
            return
        }
        c.BSON(200, user) // automatically sets Content‑Type: application/bson
    })
    r.Run(":8080")
}

2️⃣ Context Enhancements

New methods SetError and GetError provide type‑safe error propagation.

func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        if c.GetHeader("Authorization") == "" {
            c.SetError(gin.Error{Err: fmt.Errorf("缺少 Authorization 头"), Type: gin.ErrorTypePublic})
            c.AbortWithStatus(401)
            return
        }
        c.Next()
    }
}

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

3️⃣ Flexible Binding

Custom types can implement UnmarshalText to be bound automatically from query parameters.

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 p QueryParams
    if err := c.ShouldBindQuery(&p); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, p)
})

4️⃣ Raw‑Path Routing

Enabling UseRawPath = true and disabling automatic unescaping allows routes to accept encoded characters such as /user/:id where id may contain slashes.

r.UseRawPath = true
r.UnescapePathValues = false
r.GET("/user/:id", func(c *gin.Context) {
    c.JSON(200, gin.H{"user_id": c.Param("id")})
})

5️⃣ Colored Delayed Logs

The logger now colors output based on request latency: green for < 100 ms, yellow for 100‑500 ms, red for > 500 ms, making slow requests easy to spot.

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

6️⃣ Protobuf Content Negotiation

Handlers can automatically respond with JSON or Protobuf based on the Accept header using c.Negotiate.

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: gin.H{"name": "Alice", "age": 28}, MIMEJSON: gin.H{"name": "Alice", "age": 28}, "application/x-protobuf": protoData})
})

7️⃣ Comprehensive Microservice Example

A full example combines the above features: raw‑path routing, auth middleware, BSON/Protobuf negotiation, and custom binding for a user service.

func main() {
    r := gin.New()
    r.UseRawPath = true
    r.Use(AuthMiddleware, gin.Logger())
    r.GET("/user/:id", getUser)
    r.POST("/user", createUser)
    r.Run(":8080")
}

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

8️⃣ Upgrade Recommendations

A quick reference table suggests which project types benefit most from the new features (e.g., MongoDB microservices gain BSON support, gRPC gateways gain Protobuf negotiation, file services benefit from raw‑path handling).

9️⃣ Compatibility Note

Gin 1.12 maintains 100 % backward compatibility, allowing a drop‑in upgrade without breaking existing code.