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/routing-params-and-wildcards.md

View on GitHub
# Routing — Path Parameters, Wildcards & NoRoute

See also: `routing-groups-and-versioning.md`, `routing-validators-and-limits.md`

## Path Parameter Patterns

> **Security note:** In production, never expose raw `err.Error()` to clients. Return generic messages and log the error server-side.

Use `ShouldBindURI` with a struct to bind multiple path parameters at once.

```go
// Single parameter
r.GET("/users/:id", func(c *gin.Context) {
    id := c.Param("id") // returns value without leading slash for :param
})

// Multiple parameters with struct binding
r.GET("/orgs/:orgID/users/:userID", func(c *gin.Context) {
    type params struct {
        OrgID  string `uri:"orgID"  binding:"required"`
        UserID string `uri:"userID" binding:"required"`
    }
    var p params
    if err := c.ShouldBindURI(&p); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    // p.OrgID, p.UserID are bound and validated
})
```

**Critical:** URI parameter names in the `uri:""` tag must match the `:name` in the route path exactly.

---

## Wildcard Routes & NoRoute Handler

### Wildcard Parameters

`*param` matches everything after the prefix, including slashes.

```go
// Matches: /files/docs/report.pdf, /files/images/logo.png
r.GET("/files/*filepath", func(c *gin.Context) {
    filepath := c.Param("filepath") // includes leading slash: "/docs/report.pdf"
})
```

### NoRoute Handler (Custom 404)

```go
r.NoRoute(func(c *gin.Context) {
    c.JSON(http.StatusNotFound, gin.H{
        "error": "route not found",
        "path":  c.Request.URL.Path,
    })
})

// Required — NoMethod handler only fires when this is true (default: false)
r.HandleMethodNotAllowed = true

r.NoMethod(func(c *gin.Context) {
    c.JSON(http.StatusMethodNotAllowed, gin.H{
        "error":  "method not allowed",
        "method": c.Request.Method,
    })
})
```

---

## Multipart File Upload (via Routing)

```go
// internal/handler/upload_handler.go
func (h *UploadHandler) UploadAvatar(c *gin.Context) {
    type uriParams struct {
        UserID string `uri:"id" binding:"required"`
    }
    var p uriParams
    if err := c.ShouldBindURI(&p); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    file, err := c.FormFile("avatar")
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "avatar file required"})
        return
    }

    ext := filepath.Ext(file.Filename)
    allowed := map[string]bool{".jpg": true, ".jpeg": true, ".png": true, ".webp": true}
    if !allowed[ext] {
        c.JSON(http.StatusBadRequest, gin.H{"error": "only jpg, png, webp files allowed"})
        return
    }

    if file.Size > 2<<20 {
        c.JSON(http.StatusBadRequest, gin.H{"error": "file must be under 2 MB"})
        return
    }

    // Sanitize path: strip directory components to prevent path traversal
    safeID := filepath.Base(p.UserID)
    dst := filepath.Join("uploads/avatars", safeID+ext)
    if err := c.SaveUploadedFile(file, dst); err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "upload failed"})
        return
    }

    c.JSON(http.StatusOK, gin.H{"path": dst})
}
```

Route registration:

```go
r.MaxMultipartMemory = 8 << 20

protected := r.Group("/api/v1")
protected.Use(middleware.Auth(tokenCfg, logger))
{
    protected.POST("/users/:id/avatar",    uploadHandler.UploadAvatar)
    protected.POST("/users/:id/documents", uploadHandler.UploadDocuments)
}
```
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