@sun-asterisk/sunlint 1.3.47 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/go-gin/AGENTS.md

@@ -0,0 +1,149 @@
+# Go Gin Framework — SunLint Agent Guide
+
+> Priority directives for AI agents working on Go + Gin projects.
+> Rule files: `.agent/skills/sunlint-code-quality/rules/`
+
+---
+
+## Critical Patterns — Apply Every Time
+
+### Middleware Chain Termination
+- After sending a response that should stop the chain → `c.AbortWithStatusJSON(code, body)` then `return`
+- `c.AbortWithStatusJSON` calls `c.Abort()` internally — don't call both
+- Plain `return` from a handler does NOT stop downstream handlers
+- See: `GN001-abort-after-response.md`
+
+### Request Binding + Validation
+- Every `c.ShouldBindJSON(&req)` → must be followed by `if err != nil { c.AbortWithStatusJSON(400, ...); return }`
+- Declare all validation rules as struct `binding:` tags: `binding:"required,email"`, `binding:"min=1,max=255"`
+- **Never** skip the error check from `ShouldBind*`
+- See: `GN003-bind-error-handling.md`, `GN008-struct-validation-tags.md`
+
+### Context Usage
+- Inside handlers: `ctx := c.Request.Context()` — pass to all downstream calls
+- **Never** `context.Background()` inside a handler
+- **Never** pass `*gin.Context` to a goroutine — copy scalar values first, pass `c.Request.Context()`
+- See: `GN002-request-context.md`, `GN010-context-scope.md`
+
+### Do Not Log Sensitive DataTesting commands rõ ràng trong package.json/Makefile
+Standard conventions (eslint, prettier, gofmt đã config sẵn)
+4. Test với agents trước khi commit
+Quy trình recommended:
+
+Bước 1: Tạo baseline
+
+# Chạy agent KHÔNG có AGENTS.md trên vài tasks nhỏ
+# Đo success rate, cost
+
+Bước 2: Thêm AGENTS.md, measure lại
+
+# So sánh với baseline
+# Nếu không improve hoặc cost tăng quá nhiều → bỏ AGENTS.md
+
+Bước 3: Iterate
+
+# Nếu quyết định giữ AGENTS.md, hãy giữ nó concise
+# Monitor agent behavior qua time
+
+5. Monitor Context Length
+Context files nên dưới 500 tokens (t
+- Logging middleware logs only: method, path, status, duration, request_id, client IP
+- **Never** log request bodies, `Authorization` header values, or any field named password/token/card
+- See: `GN012-no-log-sensitive.md`
+
+---
+
+## Architecture Patterns
+
+### Handler struct — dependency injection
+Handlers are structs with injected service interfaces. No globals. No `new(Service)` inside handlers.
+```go
+type OrderHandler struct {
+    service OrderService     // interface — mockable
+    logger  *slog.Logger
+}
+func NewOrderHandler(svc OrderService, logger *slog.Logger) *OrderHandler {
+    return &OrderHandler{service: svc, logger: logger}
+}
+```
+See: `GN004-dependency-injection.md`
+
+### Route organisation
+```go
+r := gin.New()
+r.Use(gin.Recovery(), RequestID(), RequestLogger(logger))   // global
+
+public := r.Group("/api/v1")
+{ /* unauthenticated routes */ }
+
+private := r.Group("/api/v1")
+private.Use(JWTAuth(validator))
+{ /* authenticated routes */ }
+```
+See: `GN005-route-groups-middleware.md`, `GN011-middleware-concerns.md`
+
+### Production setup checklist
+```go
+gin.SetMode(os.Getenv("GIN_MODE"))    // "release" in prod — GN007
+r := gin.New()
+r.Use(CustomRecovery(logger))          // GN009
+r.Use(RequestID())                     // GN011
+r.Use(RequestLogger(logger))           // GN012
+// ... register groups (GN005)
+```
+
+### HTTP Status Codes
+- `POST` success → `c.JSON(http.StatusCreated, obj)` (201)
+- `DELETE` no body → `c.Status(http.StatusNoContent)` (204)
+- Not found → `c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "not found"})` (404)
+- Validation error → `c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})` (400)
+- **Always** use `net/http` constants — never magic integers
+- See: `GN006-http-status-codes.md`
+
+### Cross-cutting concerns
+Auth, rate limiting, CORS, request ID, structured logging → **always middleware**, never inside handlers.
+See: `GN011-middleware-concerns.md`
+
+---
+
+## Run Commands
+
+```bash
+# Development
+go run ./cmd/api/main.go
+GIN_MODE=debug go run ./cmd/api/main.go
+
+# Build
+go build -o bin/api ./cmd/api/
+
+# Test (always with race detector)
+go test -race ./...
+go test -race -run TestOrderHandler ./internal/handlers/
+go test -cover ./...
+
+# Linting
+golangci-lint run ./...
+staticcheck ./...
+
+# Env for production
+GIN_MODE=release
+PORT=8080
+```
+
+---
+
+## What NOT to do (quick reference)
+
+| ❌ Wrong | ✅ Correct |
+|---|---|
+| `return` after `c.JSON` in middleware | `c.AbortWithStatusJSON(...)` then `return` |
+| `context.Background()` in handler | `c.Request.Context()` |
+| `go func() { use c.Get(...) }()` | Copy value before goroutine: `val := c.GetString(...)` |
+| `c.ShouldBindJSON(&req)` without err check | `if err := c.ShouldBindJSON(&req); err != nil { abort }` |
+| Manual `if req.Email == ""` validation | `binding:"required,email"` struct tag |
+| `var db *gorm.DB` package global | Inject `db *gorm.DB` as struct field |
+| Auth check inside handler | `JWTAuth()` middleware on route group |
+| `log.Printf("body: %s", body)` | Log method+path+status+duration only |
+| `gin.Default()` in production | `gin.New()` + explicit `Recovery()` + structured logger |
+| `c.JSON(200, gin.H{"error": ...})` | `c.AbortWithStatusJSON(http.StatusBadRequest, ...)` |
+| `GIN_MODE` not set (debug default) | `GIN_MODE=release` in production environment |

package/skill-assets/sunlint-code-quality/rules/go-gin/GN001-abort-after-response.md

@@ -0,0 +1,75 @@
+---
+title: "GN001 – Call c.Abort() After Terminating in Middleware"
+impact: high
+impactDescription: "Missing c.Abort() causes subsequent middleware handlers and the final route handler to still execute after an early response has been sent, causing duplicate writes and data leaks."
+tags: [go, gin, middleware, correctness]
+---
+
+# GN001 – Call `c.Abort()` After Terminating in Middleware
+
+## Rule
+
+Any middleware that sends a response and intends to stop the chain **must** call `c.Abort()` (or `c.AbortWithStatus()` / `c.AbortWithStatusJSON()`) immediately after writing. Never rely on `return` alone.
+
+## Why
+
+`c.Next()` executes subsequent handlers in sequence. A plain `return` exits the current handler but Gin still runs the remaining handlers in the chain. `c.Abort()` sets the index past all remaining handlers so the chain stops cleanly.
+
+## Wrong
+
+```go
+func AuthMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        token := c.GetHeader("Authorization")
+        if token == "" {
+            c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+            return   // ❌ returns from this func but downstream handlers still run
+        }
+        c.Next()
+    }
+}
+
+func RateLimitMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        if isRateLimited(c.ClientIP()) {
+            c.JSON(http.StatusTooManyRequests, gin.H{"error": "rate limit exceeded"})
+            // ❌ forgot both return and Abort — next handler fires and writes again
+        }
+        c.Next()
+    }
+}
+```
+
+## Correct
+
+```go
+func AuthMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        token := c.GetHeader("Authorization")
+        if token == "" {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+            // c.Abort() is called inside AbortWithStatusJSON — no c.Next() needed
+            return
+        }
+        // validation passes — continue chain
+        c.Set("user_id", parsedUserID)
+        c.Next()
+    }
+}
+
+func RateLimitMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        if isRateLimited(c.ClientIP()) {
+            c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{"error": "rate limit exceeded"})
+            return
+        }
+        c.Next()
+    }
+}
+```
+
+## Notes
+
+- `c.AbortWithStatus(code)` and `c.AbortWithStatusJSON(code, obj)` both call `c.Abort()` internally — you don't need to call `c.Abort()` separately when using these.
+- After `c.Abort()`, code after the call in the same function still runs — use `return` to exit the function body.
+- Verify with unit tests: register middleware + handler, send a bad request, assert the handler body was NOT executed.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN002-request-context.md

@@ -0,0 +1,64 @@
+---
+title: "GN002 – Use c.Request.Context(), Not context.Background()"
+impact: medium
+impactDescription: "context.Background() ignores client disconnects and request deadlines; c.Request.Context() propagates cancellation automatically."
+tags: [go, gin, context, correctness]
+---
+
+# GN002 – Use `c.Request.Context()` Not `context.Background()`
+
+## Rule
+
+When passing a context to database calls, external HTTP requests, or any `ctx context.Context` parameter inside a Gin handler, always use `c.Request.Context()`. Never create a fresh `context.Background()` inside a handler.
+
+## Why
+
+`c.Request.Context()` is derived from the HTTP request and carries the client's cancellation signal. If the client disconnects mid-request, the context is cancelled and all downstream work (DB queries, gRPC calls) is cancelled too — preventing wasted compute. `context.Background()` is never cancelled and leaks work after the client is gone.
+
+## Wrong
+
+```go
+func (h *OrderHandler) Create(c *gin.Context) {
+    var req CreateOrderRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+
+    // ❌ context.Background() — ignores client disconnect and server deadlines
+    order, err := h.service.CreateOrder(context.Background(), req)
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(http.StatusCreated, order)
+}
+```
+
+## Correct
+
+```go
+func (h *OrderHandler) Create(c *gin.Context) {
+    var req CreateOrderRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+
+    // ✅ propagates request lifetime, deadline, and cancellation
+    ctx := c.Request.Context()
+    order, err := h.service.CreateOrder(ctx, req)
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(http.StatusCreated, order)
+}
+```
+
+## Notes
+
+- Extract the context once: `ctx := c.Request.Context()` at the top of the handler body.
+- Do **not** store this context in a struct field — contexts must flow through function arguments.
+- If you need a timeout shorter than the request's own deadline: `ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Second); defer cancel()`.
+- See GN010 for the rule about not storing Gin context in goroutines.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN003-bind-error-handling.md

@@ -0,0 +1,70 @@
+---
+title: "GN003 – Always Handle ShouldBindJSON / ShouldBind Errors"
+impact: high
+impactDescription: "Ignoring ShouldBindJSON errors means malformed or missing fields are silently treated as zero values, causing corrupted data writes and bypassed validation."
+tags: [go, gin, validation, correctness]
+---
+
+# GN003 – Always Handle `ShouldBindJSON` / `ShouldBind` Errors
+
+## Rule
+
+Every call to `c.ShouldBindJSON`, `c.ShouldBind`, `c.ShouldBindQuery`, or `c.ShouldBindUri` must be followed by an error check. If the error is non-nil, abort immediately with a `400 Bad Request` response.
+
+## Why
+
+`ShouldBind*` populates the target struct but returns an error for malformed JSON, missing required fields (enforced by `binding:"required"` tags), or type mismatches. Ignoring the error means the handler continues with a partially or incorrectly populated struct, silently writing bad data.
+
+## Wrong
+
+```go
+func (h *UserHandler) Create(c *gin.Context) {
+    var req CreateUserRequest
+    c.ShouldBindJSON(&req)   // ❌ error ignored — continues with zero-value struct fields
+
+    user, err := h.service.CreateUser(c.Request.Context(), req)
+    // ...
+}
+
+// Worse: using BindJSON (panics on error in some versions, logs but doesn't stop)
+func (h *UserHandler) Update(c *gin.Context) {
+    var req UpdateUserRequest
+    c.BindJSON(&req)   // ❌ BindJSON writes 400 header but handler still continues
+    h.service.UpdateUser(c.Request.Context(), req)
+}
+```
+
+## Correct
+
+```go
+type CreateUserRequest struct {
+    Name  string `json:"name"  binding:"required,min=2,max=100"`
+    Email string `json:"email" binding:"required,email"`
+    Age   int    `json:"age"   binding:"required,min=18"`
+}
+
+func (h *UserHandler) Create(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{
+            "error":   "invalid request",
+            "details": err.Error(),
+        })
+        return
+    }
+
+    user, err := h.service.CreateUser(c.Request.Context(), req)
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "creation failed"})
+        return
+    }
+    c.JSON(http.StatusCreated, user)
+}
+```
+
+## Notes
+
+- Prefer `ShouldBind*` over `Bind*` — the `Bind*` family writes a `400` header but doesn't abort the handler, making code flow confusing.
+- Use struct tags: `binding:"required"`, `binding:"email"`, `binding:"min=1,max=255"` to shift validation into the binding layer.
+- For detailed error messages, type-assert the error to `validator.ValidationErrors` and format field names cleanly.
+- See GN008 for struct validation tag conventions.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN004-dependency-injection.md

@@ -0,0 +1,78 @@
+---
+title: "GN004 – Use Dependency Injection, Not Global Variables"
+impact: high
+impactDescription: "Global database connections and service instances in package-level vars are untestable, race-prone, and make initialization order fragile."
+tags: [go, gin, architecture, testing]
+---
+
+# GN004 – Use Dependency Injection, Not Global Variables
+
+## Rule
+
+Database connections, service instances, configuration objects, and HTTP clients must be injected as struct fields into handlers. Never declare them as `var db *gorm.DB` at package level and access them from handler functions.
+
+## Why
+
+Global state:
+- Cannot be replaced with a mock in unit tests.
+- Initialization order is implicit — the global may be `nil` if setup hasn't run.
+- Race conditions when tests share globals.
+
+Dependency injection via struct fields makes dependencies explicit, swappable, and testable.
+
+## Wrong
+
+```go
+// db/db.go — package-level global
+var DB *gorm.DB
+
+func Init() {
+    DB, _ = gorm.Open(...)
+}
+
+// handlers/user.go — accesses global directly
+func GetUser(c *gin.Context) {
+    var user User
+    db.DB.First(&user, c.Param("id"))   // ❌ depends on global initialization order
+    c.JSON(200, user)
+}
+```
+
+## Correct
+
+```go
+// handlers/user_handler.go
+type UserHandler struct {
+    db      *gorm.DB         // injected
+    service UserService      // interface — swappable in tests
+    logger  *slog.Logger
+}
+
+func NewUserHandler(db *gorm.DB, svc UserService, logger *slog.Logger) *UserHandler {
+    return &UserHandler{db: db, service: svc, logger: logger}
+}
+
+func (h *UserHandler) GetUser(c *gin.Context) {
+    ctx := c.Request.Context()
+    user, err := h.service.FindUserByID(ctx, c.Param("id"))
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "not found"})
+        return
+    }
+    c.JSON(http.StatusOK, user)
+}
+
+// main.go — wiring
+db := database.Connect(cfg.DSN)
+userSvc := services.NewUserService(db)
+userHandler := handlers.NewUserHandler(db, userSvc, logger)
+
+r := gin.New()
+r.GET("/users/:id", userHandler.GetUser)
+```
+
+## Notes
+
+- Define service dependencies as Go interfaces so handlers can be unit-tested with mocks without a real DB.
+- Use a DI framework (e.g., `google/wire`, `samber/do`) for large projects to automate wiring.
+- Configuration (`Config` structs) should be loaded once in `main` and injected — never read from `os.Getenv` directly inside handlers.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN005-route-groups-middleware.md

@@ -0,0 +1,71 @@
+---
+title: "GN005 – Group Routes and Apply Middleware at Group Level"
+impact: medium
+impactDescription: "Registering middleware per-route duplicates code and makes it easy to miss a route; group-level middleware is exhaustive by design."
+tags: [go, gin, routing, middleware]
+---
+
+# GN005 – Group Routes and Apply Middleware at Group Level
+
+## Rule
+
+Use `router.Group()` to organise routes by prefix and protection level. Apply authentication, logging, and rate-limiting middleware to the group — not individual routes.
+
+## Why
+
+Per-route middleware registration (`r.GET("/users", authMiddleware, handler)`) requires the developer to remember to add middleware to every new route. A missed route is a security hole. Group-level middleware is applied to all current and future routes in the group automatically.
+
+## Wrong
+
+```go
+r := gin.Default()
+
+// ❌ Auth repeated on every route — easy to miss
+r.GET("/users",         authMiddleware, userHandler.List)
+r.POST("/users",        authMiddleware, userHandler.Create)
+r.PUT("/users/:id",     authMiddleware, userHandler.Update)
+r.DELETE("/users/:id",  authMiddleware, userHandler.Delete)   // ❌ forgot auth on DELETE
+
+// ❌ Mixed public and protected routes without groups — hard to audit
+r.GET("/products", productHandler.List)
+r.POST("/products", authMiddleware, adminMiddleware, productHandler.Create)
+```
+
+## Correct
+
+```go
+r := gin.New()
+r.Use(gin.Recovery(), requestLogger())   // global middleware
+
+// Public routes — no auth
+public := r.Group("/api/v1")
+{
+    public.POST("/auth/login", authHandler.Login)
+    public.POST("/auth/register", authHandler.Register)
+    public.GET("/products", productHandler.List)
+}
+
+// Authenticated routes
+authenticated := r.Group("/api/v1")
+authenticated.Use(authMiddleware())
+{
+    authenticated.GET("/users/me", userHandler.Profile)
+    authenticated.PUT("/users/me", userHandler.Update)
+    authenticated.GET("/orders", orderHandler.List)
+    authenticated.POST("/orders", orderHandler.Create)
+}
+
+// Admin-only routes
+admin := r.Group("/api/v1/admin")
+admin.Use(authMiddleware(), adminMiddleware())
+{
+    admin.GET("/users", adminUserHandler.List)
+    admin.DELETE("/users/:id", adminUserHandler.Delete)
+}
+```
+
+## Notes
+
+- Use curly braces `{}` inside `Group()` to make the scope visually clear (they're just Go blocks, not syntactically required).
+- Apply rate limiting at the group level for public endpoints to prevent brute force on `/auth/login`.
+- Version your API with a group: `r.Group("/api/v1")` makes future versioning (`/api/v2`) straightforward.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN006-http-status-codes.md

@@ -0,0 +1,91 @@
+---
+title: "GN006 – Return Correct HTTP Status Codes"
+impact: medium
+impactDescription: "Returning 200 for all responses breaks API clients, hides errors in monitoring, and makes retry logic impossible."
+tags: [go, gin, api, http]
+---
+
+# GN006 – Return Correct HTTP Status Codes
+
+## Rule
+
+Always pass the correct HTTP status code to `c.JSON()`, `c.AbortWithStatusJSON()`, and `c.Status()`. Never return `200 OK` for errors, resource creation, or empty responses.
+
+## Why
+
+HTTP semantics are the contract between your API and its clients. A `200` with `{"error": "not found"}` is invisible to load balancers, monitoring tools, and client SDKs. Correct status codes enable automatic retry logic, circuit breakers, and accurate error dashboards.
+
+## Wrong
+
+```go
+func (h *UserHandler) Create(c *gin.Context) {
+    // ...
+    user, err := h.service.CreateUser(ctx, req)
+    if err != nil {
+        c.JSON(200, gin.H{"error": err.Error()})   // ❌ success code + error body
+        return
+    }
+    c.JSON(200, user)   // ❌ should be 201 for newly created resource
+}
+
+func (h *UserHandler) Delete(c *gin.Context) {
+    h.service.DeleteUser(ctx, id)
+    c.JSON(200, gin.H{"message": "deleted"})   // ❌ should be 204 with no body
+}
+```
+
+## Correct
+
+```go
+import "net/http"
+
+func (h *UserHandler) Create(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})  // 400
+        return
+    }
+    user, err := h.service.CreateUser(c.Request.Context(), req)
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "creation failed"})  // 500
+        return
+    }
+    c.JSON(http.StatusCreated, user)   // 201 ✅
+}
+
+func (h *UserHandler) GetUser(c *gin.Context) {
+    user, err := h.service.FindUserByID(c.Request.Context(), c.Param("id"))
+    if errors.Is(err, ErrNotFound) {
+        c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "user not found"})  // 404
+        return
+    }
+    c.JSON(http.StatusOK, user)   // 200
+}
+
+func (h *UserHandler) Delete(c *gin.Context) {
+    if err := h.service.DeleteUser(c.Request.Context(), c.Param("id")); err != nil {
+        c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "not found"})  // 404
+        return
+    }
+    c.Status(http.StatusNoContent)   // 204, no body ✅
+}
+```
+
+## Status code reference
+
+| Scenario | Code | Constant |
+|---|---|---|
+| Read success | 200 | `http.StatusOK` |
+| Create success | 201 | `http.StatusCreated` |
+| Delete / no body | 204 | `http.StatusNoContent` |
+| Validation failed | 400 | `http.StatusBadRequest` |
+| Not authenticated | 401 | `http.StatusUnauthorized` |
+| Not authorized | 403 | `http.StatusForbidden` |
+| Not found | 404 | `http.StatusNotFound` |
+| Business rule violation | 422 | `http.StatusUnprocessableEntity` |
+| Rate limited | 429 | `http.StatusTooManyRequests` |
+
+## Notes
+
+- Use `net/http` constants — never magic numbers like `c.JSON(201, ...)`.
+- Map service-layer sentinel errors (e.g. `ErrNotFound`, `ErrConflict`) to status codes in a central error-mapping function.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN007-release-mode.md

@@ -0,0 +1,64 @@
+---
+title: "GN007 – Set gin.ReleaseMode in Production"
+impact: medium
+impactDescription: "The default gin.DebugMode prints every registered route and request detail to stdout, leaking your API surface and increasing log noise in production."
+tags: [go, gin, security, configuration]
+---
+
+# GN007 – Set `gin.ReleaseMode` in Production
+
+## Rule
+
+Set `gin.SetMode(gin.ReleaseMode)` before calling `gin.New()` or `gin.Default()` in production builds. Read the mode from an environment variable so it can differ between environments.
+
+## Why
+
+Debug mode outputs all routes on startup and logs detailed request info. In production this:
+- Leaks your API surface to anyone with log access.
+- Adds unnecessary CPU cost for string formatting.
+- Makes it harder to find meaningful log entries.
+
+## Wrong
+
+```go
+// main.go — mode not set, defaults to DebugMode
+func main() {
+    r := gin.Default()          // ❌ runs in debug mode, dumps all routes to stdout
+    r.GET("/internal/admin", adminHandler)  // ❌ exposed in startup log
+    r.Run(":8080")
+}
+
+// Hardcoded mode
+gin.SetMode(gin.DebugMode)     // ❌ always debug, regardless of environment
+```
+
+## Correct
+
+```go
+func main() {
+    // Read from environment — "release", "debug", or "test"
+    ginMode := os.Getenv("GIN_MODE")
+    if ginMode == "" {
+        ginMode = gin.ReleaseMode  // safe default
+    }
+    gin.SetMode(ginMode)
+
+    r := gin.New()
+    r.Use(gin.Recovery())   // see GN009 for Recovery middleware
+    // ... register routes
+    r.Run(":" + os.Getenv("PORT"))
+}
+```
+
+Or rely on Gin's built-in env var support: Gin automatically reads `GIN_MODE` — set it to `release` in your container/systemd environment and `gin.SetMode` is not even needed explicitly.
+
+```bash
+# Production container / systemd
+GIN_MODE=release
+```
+
+## Notes
+
+- `gin.Default()` adds `gin.Logger()` and `gin.Recovery()` automatically in debug mode — in production, use `gin.New()` and add your structured logger and Recovery explicitly (see GN009).
+- Never call `gin.SetMode` after `gin.New()` — the mode must be set before the engine is created.
+- In tests, set `gin.SetMode(gin.TestMode)` in `TestMain` to silence route debug output.