Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-api

golang-gin-api

Verified

Build REST APIs with Go Gin. Use when creating Go web servers, adding Gin routes, writing handlers, or asking about middleware, binding, error handling, or project structure.

FileKindSize
SKILL.mdskill md10.0 KB
metadata.jsonconfig482 B
references/background-jobs-goroutine-and-pool.mdmarkdown3.5 KB
references/background-jobs-queue-and-shutdown.mdmarkdown3.5 KB
references/defensive-handler-patterns.mdmarkdown3.7 KB
references/error-handling-apperror.mdmarkdown4.1 KB
references/error-handling-recovery.mdmarkdown1.8 KB
references/error-handling-validation.mdmarkdown3.0 KB
references/file-uploads-cloud.mdmarkdown2.4 KB
references/file-uploads-local.mdmarkdown4.0 KB
references/middleware-core.mdmarkdown4.2 KB
references/middleware-logging-and-recovery.mdmarkdown3.3 KB
references/middleware-timeout-and-custom.mdmarkdown3.2 KB
references/rate-limiting-algorithms.mdmarkdown3.5 KB
references/rate-limiting-fallback.mdmarkdown2.3 KB
references/rate-limiting-headers.mdmarkdown1.8 KB
references/rate-limiting-peruser.mdmarkdown2.4 KB
references/rate-limiting-redis-sliding.mdmarkdown2.2 KB
references/rate-limiting-redis.mdmarkdown2.9 KB
references/rate-limiting-sliding-window.mdmarkdown2.2 KB
references/rate-limiting-tiered.mdmarkdown3.0 KB
references/routing-groups-and-versioning.mdmarkdown3.8 KB
references/routing-params-and-wildcards.mdmarkdown3.4 KB
references/routing-validators-and-limits.mdmarkdown2.4 KB
references/safe-context-extraction.mdmarkdown4.3 KB
references/server-handlers-and-errors.mdmarkdown3.6 KB
references/server-setup-and-routes.mdmarkdown3.9 KB
references/websocket-auth-and-keepalive.mdmarkdown3.5 KB
references/websocket-chat-handler.mdmarkdown1.5 KB
references/websocket-hub-and-client.mdmarkdown3.9 KB
references/websocket-setup-and-echo.mdmarkdown3.4 KB
references/websocket-shutdown-and-messages.mdmarkdown3.8 KB
references/websocket-testing.mdmarkdown3.8 KB

references/error-handling-recovery.md

View on GitHub
# Error Handling — Panic Recovery Middleware

See also: `error-handling-apperror.md`, `error-handling-validation.md`

## Panic Recovery Middleware

Use custom recovery to return JSON instead of Gin's default plain-text 500.

```go
// pkg/middleware/recovery.go
package middleware

import (
    "log/slog"
    "net/http"

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

// Recovery returns a Gin middleware that recovers from panics and logs them.
// Register with r.Use(middleware.Recovery(logger)) instead of gin.Recovery().
func Recovery(logger *slog.Logger) gin.HandlerFunc {
    return func(c *gin.Context) {
        defer func() {
            if rec := recover(); rec != nil {
                logger.ErrorContext(c.Request.Context(), "panic recovered",
                    "panic", rec,
                    "path", c.FullPath(),
                    "method", c.Request.Method,
                )
                c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{
                    "error": "internal server error",
                })
            }
        }()
        c.Next()
    }
}
```

Register in main.go:

```go
r := gin.New()
r.Use(middleware.Logger(logger))
r.Use(middleware.Recovery(logger))
```

**Why custom recovery over `gin.Recovery()`:** `gin.Recovery()` writes a plain-text response. Custom recovery returns JSON, which API clients can parse consistently. It also integrates with your structured logger (`log/slog`) and request ID.

**What panics to expect:**
- Nil pointer dereferences in handlers (most common)
- Index out of range errors
- Type assertion failures without the two-value form

**Best practice:** Fix panics at their source — don't rely on recovery as a general error handler. Recovery is a last-resort safety net, not a substitute for proper error handling with `AppError` and `handleServiceError`.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall