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/defensive-handler-patterns.md

View on GitHub
# Defensive Handler Patterns — Input Validation, Fail-Closed, Bounds

See also: `safe-context-extraction.md`, `routing-validators-and-limits.md`

## Validate Input Format Before DB Lookup

Always validate the format of path parameters before hitting the database. This prevents unnecessary DB queries and returns clearer error messages.

```go
import gouid "github.com/google/uuid"

func (h *Handler) CreateVenda(c *gin.Context) {
    uuid := c.Param("uuid")

    // ✅ Validate format first — returns 400, not 404
    if _, err := gouid.Parse(uuid); err != nil {
        apiError(c, http.StatusBadRequest, "VALIDATION_ERROR", "invalid uuid format")
        return
    }

    // Only hit DB after format is valid
    user, err := h.users.GetByUUID(uuid)
    if err != nil {
        apiError(c, http.StatusNotFound, "NOT_FOUND", "uuid not found")
        return
    }
    // ...
}
```

**Rule:** For every path parameter:
- UUID → validate with `uuid.Parse()`
- Numeric ID → validate with `strconv.ParseInt()` (already standard practice)
- Slug → validate with regex if format is constrained
- Return 400 for bad format, 404 for valid format but not found

## Fail-Closed Security Principle

When parsing security-related data (schedules, permissions, configs), **deny access on parse failure**. Never fail-open.

```go
// ❌ DANGEROUS — corrupt JSON = allow access
if err := json.Unmarshal([]byte(*scheduleJSON), &schedule); err != nil {
    return true // attacker can corrupt data to bypass restrictions
}

// ✅ SAFE — corrupt JSON = deny access + log warning
if err := json.Unmarshal([]byte(*scheduleJSON), &schedule); err != nil {
    slog.Warn("invalid access schedule JSON", "error", err)
    return false // fail-closed: deny on corruption
}
```

**Rule:** When in doubt, deny. It's easier to debug "why am I blocked" than "how did they get in."

## Pagination Bounds

Always cap pagination parameters to prevent:
- Integer overflow in offset calculation (theoretical on 32-bit)
- Excessive DB scans from absurdly large page numbers
- Memory exhaustion from large `per_page` values

```go
func ParsePaginationParams(c *gin.Context) PaginationParams {
    page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
    if page < 1 {
        page = 1
    }

    perPage, _ := strconv.Atoi(c.DefaultQuery("per_page", "15"))
    if perPage < 1 || perPage > 100 {
        perPage = 15
    }

    // ✅ Cap page to prevent excessive offset
    if page > 10000 {
        page = 10000
    }

    return PaginationParams{Page: page, PerPage: perPage}
}
```

**Rule:** Always enforce: `1 <= page <= 10000`, `1 <= per_page <= 100`.

## Background Goroutine Lifecycle

Any goroutine started in middleware or server setup MUST be cancellable via context or done channel. Otherwise it leaks on shutdown or in tests.

```go
// ❌ LEAKS — goroutine runs forever, even after server shuts down
go func() {
    for {
        time.Sleep(time.Minute)
        cleanup()
    }
}()

// ✅ SAFE — stops cleanly on context cancellation
go func() {
    ticker := time.NewTicker(time.Minute)
    defer ticker.Stop()
    for {
        select {
        case <-ctx.Done():
            return
        case <-ticker.C:
            cleanup()
        }
    }
}()
```

**Rule:** Never use bare `for { time.Sleep(...) }` in production code. Always use `ticker + select + ctx.Done()`.

## Summary Checklist

Before marking a handler "done," verify:

- [ ] All `c.Get()` values extracted via safe helpers (no raw type assertions)
- [ ] Path parameters validated for format before DB lookup
- [ ] Security-related parsing fails closed (deny on error)
- [ ] Pagination capped with upper bounds
- [ ] Any background goroutines are cancellable
- [ ] Sensitive data (passwords, tokens) never logged or returned in errors
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: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated 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: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall