Skip to content

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

golang-gin-architect

Verified

Software architect for Go Gin APIs. Use when making architecture decisions, evaluating complexity, designing systems, choosing patterns, or coordinating across gin skills.

FileKindSize
SKILL.mdskill md10.7 KB
metadata.jsonconfig466 B
references/adr-format-and-templates.mdmarkdown4.1 KB
references/adr-service-extraction-and-example.mdmarkdown4.0 KB
references/api-design-error-contract-docs.mdmarkdown1.8 KB
references/api-design-filtering-bulk-evolution.mdmarkdown3.8 KB
references/api-design-versioning-pagination.mdmarkdown4.3 KB
references/clean-architecture-feature-module.mdmarkdown4.5 KB
references/clean-architecture-layers-di.mdmarkdown5.2 KB
references/complexity-assessment-budget.mdmarkdown5.6 KB
references/complexity-assessment-gates.mdmarkdown4.2 KB
references/complexity-assessment-patterns.mdmarkdown5.0 KB
references/cross-cutting-health-checks.mdmarkdown1.7 KB
references/cross-cutting-observability.mdmarkdown3.9 KB
references/cross-cutting-security-config.mdmarkdown4.4 KB
references/data-ownership-boundaries.mdmarkdown4.5 KB
references/data-ownership-sync-migration.mdmarkdown4.3 KB
references/data-patterns-cqrs.mdmarkdown3.8 KB
references/data-patterns-event-sourcing-aggregate.mdmarkdown2.2 KB
references/data-patterns-event-store.mdmarkdown3.7 KB
references/data-patterns-outbox.mdmarkdown3.7 KB
references/data-patterns-read-replicas.mdmarkdown2.6 KB
references/data-patterns-saga.mdmarkdown3.6 KB
references/error-flow-domain-layers.mdmarkdown5.3 KB
references/error-flow-handler-chain.mdmarkdown4.7 KB
references/golden-main-medium-project.mdmarkdown3.0 KB
references/golden-main-medium-startup.mdmarkdown2.8 KB
references/golden-main-small-project.mdmarkdown4.0 KB
references/grpc-interop-gateway-docker.mdmarkdown2.1 KB
references/grpc-interop-server-client.mdmarkdown2.7 KB
references/grpc-interop-setup.mdmarkdown3.6 KB
references/messaging-consumer-docker.mdmarkdown1.6 KB
references/messaging-consumer-workqueues.mdmarkdown3.6 KB
references/messaging-dlq-idempotency.mdmarkdown3.1 KB
references/messaging-dlq-setup.mdmarkdown2.4 KB
references/messaging-pubsub-exchanges.mdmarkdown3.6 KB
references/messaging-rabbitmq-connection.mdmarkdown3.2 KB
references/messaging-rabbitmq-producer.mdmarkdown2.4 KB
references/object-storage-download-presign.mdmarkdown3.5 KB
references/object-storage-multipart-minio.mdmarkdown2.2 KB
references/object-storage-setup-upload.mdmarkdown4.2 KB
references/redis-cache-warming-pubsub.mdmarkdown3.2 KB
references/redis-caching-patterns.mdmarkdown4.3 KB
references/redis-session-distributed-lock.mdmarkdown3.9 KB
references/resilience-circuit-breaker-bulkhead.mdmarkdown4.3 KB
references/resilience-retry-rate-limiting.mdmarkdown4.0 KB
references/skill-orchestration-overview.mdmarkdown3.2 KB
references/skill-orchestration-workflows.mdmarkdown5.4 KB
references/system-design-bounded-contexts.mdmarkdown4.1 KB
references/system-design-c4-model.mdmarkdown4.6 KB
references/system-design-dependency-graphs.mdmarkdown2.6 KB
references/system-design-domain-modeling.mdmarkdown3.5 KB
references/system-design-project-structure.mdmarkdown4.2 KB
references/tech-debt-identification-prioritization.mdmarkdown5.1 KB
references/tech-debt-refactoring-communication.mdmarkdown4.0 KB

references/error-flow-handler-chain.md

View on GitHub
# Error Flow Architecture — Handler Mapping and Complete Chain

Companion to `error-flow-domain-layers.md` (domain errors, repository, service layer rules).

---

## Handler Layer — Map to HTTP

Handlers map domain errors to HTTP responses. This is the ONLY layer that knows about HTTP status codes.

```go
func (h *UserHandler) GetUser(c *gin.Context) {
    id, err := strconv.ParseInt(c.Param("id"), 10, 64)
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
        return
    }

    user, err := h.svc.GetByID(c.Request.Context(), id)
    if err != nil {
        status, msg := mapDomainError(err)
        if status == http.StatusInternalServerError {
            slog.ErrorContext(c.Request.Context(), "unexpected error",
                "op", "GetUser", "id", id, "err", err)
        }
        c.JSON(status, gin.H{"error": msg})
        return
    }
    c.JSON(http.StatusOK, user)
}

// mapDomainError converts domain errors to HTTP status + message pairs.
func mapDomainError(err error) (int, string) {
    var valErr *domain.ValidationError
    if errors.As(err, &valErr) {
        return http.StatusBadRequest, valErr.Error()
    }
    var multiErr *domain.MultiValidationError
    if errors.As(err, &multiErr) {
        return http.StatusBadRequest, multiErr.Error()
    }
    switch {
    case errors.Is(err, domain.ErrNotFound):
        return http.StatusNotFound, "resource not found"
    case errors.Is(err, domain.ErrAlreadyExists):
        return http.StatusConflict, "resource already exists"
    case errors.Is(err, domain.ErrInvalidInput):
        return http.StatusBadRequest, "invalid input"
    case errors.Is(err, domain.ErrForbidden):
        return http.StatusForbidden, "access denied"
    case errors.Is(err, domain.ErrUnauthorized):
        return http.StatusUnauthorized, "unauthorized"
    default:
        return http.StatusInternalServerError, "internal error"
    }
}
```

**Handler rules:** NEVER wrap errors — only map them. Log only at handler level. Log only 5xx; 4xx are normal flow. `mapDomainError` is a pure function — easy to test independently.

---

## Error Wrapping Convention

| Layer      | Convention                                     | Purpose                   |
|------------|------------------------------------------------|---------------------------|
| Domain     | `errors.New("description")`                    | Define sentinel/root errors |
| Repository | `fmt.Errorf("Repo.Method(args): %w", err)`     | Translate + add call site |
| Service    | `fmt.Errorf("Service.Method(args): %w", err)`  | Add operation context     |
| Handler    | No wrapping — call `mapDomainError(err)`        | Translate to HTTP         |

**Always use `%w`, never `%v`.** `%v` stringifies — `errors.Is` and `errors.As` cannot unwrap it.

```go
// CORRECT — chain preserved
return fmt.Errorf("UserService.GetByID(%d): %w", id, err)

// WRONG — chain broken, errors.Is will not find domain.ErrNotFound
return fmt.Errorf("UserService.GetByID(%d): %v", id, err)
```

---

## errors.Is and errors.As Usage

```go
// errors.Is — checks identity/equality through the chain
errors.Is(err, domain.ErrNotFound) // true even if err is 3 levels deep

// errors.As — extracts the first matching type from the chain
var valErr *domain.ValidationError
if errors.As(err, &valErr) {
    slog.Warn("validation failed", "field", valErr.Field, "msg", valErr.Message)
}

// Check specific types before broad sentinels
var ve *domain.ValidationError
switch {
case errors.As(err, &ve):
    return http.StatusBadRequest, ve.Message
case errors.Is(err, domain.ErrNotFound):
    return http.StatusNotFound, "not found"
}
```

**Pitfall:** never unwrap manually with `.(type)` assertions — they do not traverse wrapped chains.

---

## Complete Error Chain Example

```go
// Step 1 — Database
err = sql.ErrNoRows

// Step 2 — Repository translates
return nil, fmt.Errorf("postgresRepo.GetByID(42): %w", domain.ErrNotFound)

// Step 3 — Service adds context
return nil, fmt.Errorf("UserService.GetByID(42): %w", err)
// domain.ErrNotFound still reachable via errors.Is

// Step 4 — Handler maps to HTTP
status, msg := mapDomainError(err)
// errors.Is(err, domain.ErrNotFound) → true → status=404
c.JSON(http.StatusNotFound, gin.H{"error": "resource not found"})
// 404 is expected — no log emitted
```

Full error string in logs (5xx path):
```
UserService.GetByID(42): postgresRepo.GetByID(42): not found
```

---

## Summary of Responsibilities

```
domain/errors.go     → define error types (no deps)
repository/*.go      → translate DB errors → domain errors, wrap with context
service/*.go         → wrap errors with operation context, propagate
handler/error_map.go → single mapDomainError function, log 5xx, call c.JSON
```
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall