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-domain-layers.md

View on GitHub
# Error Flow Architecture — Domain Errors and Layer Rules

How errors flow through clean architecture layers in Go Gin APIs. Covers domain error types, repository and service layer conventions.

**Companion to:** `error-flow-handler-chain.md` (handler mapping, wrapping conventions, complete chain example).

---

## Error Flow Diagram

```
┌──────────────────────────────────────────────────────────────┐
│                    Error Flow (outermost → DB)               │
│  HTTP Request                                                │
│       │                                                      │
│       ▼                                                      │
│  [Handler]  ─── errors.Is / errors.As ──► HTTP status+body  │
│       │  returns domain.ErrNotFound (wrapped)               │
│       ▼                                                      │
│  [Service]  ─── fmt.Errorf("Svc.Method: %w", err)           │
│       │  returns domain.ErrNotFound (wrapped)               │
│       ▼                                                      │
│  [Repository] ─── translates sql.ErrNoRows → domain.Err*    │
│       ▼                                                      │
│  [Database]   ─── sql.ErrNoRows, *pq.Error, etc.            │
│  chain: sql.ErrNoRows → domain.ErrNotFound → "Svc: %w" → 404│
└──────────────────────────────────────────────────────────────┘
```

**Key rule:** Only the handler maps errors to HTTP. Layers below NEVER call `c.JSON` or reference HTTP status codes.

---

## Domain Errors — Innermost Layer

The domain layer owns error definitions. No external dependencies — stdlib only.

```go
// internal/user/domain/errors.go
package domain

import "errors"

// Sentinel errors — checked with errors.Is
var (
    ErrNotFound      = errors.New("not found")
    ErrAlreadyExists = errors.New("already exists")
    ErrInvalidInput  = errors.New("invalid input")
    ErrForbidden     = errors.New("forbidden")
    ErrUnauthorized  = errors.New("unauthorized")
)

// ValidationError carries field-level detail — extracted with errors.As
type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string { return e.Field + ": " + e.Message }

// MultiValidationError aggregates field errors
type MultiValidationError struct {
    Errors []*ValidationError
}

func (e *MultiValidationError) Error() string {
    return "validation failed: " + strconv.Itoa(len(e.Errors)) + " error(s)"
}
```

Rules: defined once in domain package; pure stdlib; sentinel errors for simple checks; typed errors for structured data; no HTTP awareness.

---

## Repository Layer — Translate DB Errors

The repository is the ONLY layer that imports `database/sql`, `github.com/lib/pq`, or ORM packages.

```go
func (r *postgresRepo) GetByID(ctx context.Context, id int64) (*domain.User, error) {
    var u domain.User
    err := r.db.QueryRowContext(ctx,
        `SELECT id, email, name FROM users WHERE id = $1`, id,
    ).Scan(&u.ID, &u.Email, &u.Name)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, fmt.Errorf("postgresRepo.GetByID(%d): %w", id, domain.ErrNotFound)
        }
        return nil, fmt.Errorf("postgresRepo.GetByID(%d): %w", id, err)
    }
    return &u, nil
}

func (r *postgresRepo) Create(ctx context.Context, u *domain.User) error {
    _, err := r.db.ExecContext(ctx,
        `INSERT INTO users (email, name) VALUES ($1, $2)`, u.Email, u.Name,
    )
    if err != nil {
        var pqErr *pq.Error
        if errors.As(err, &pqErr) && pqErr.Code == "23505" {
            return fmt.Errorf("postgresRepo.Create: %w", domain.ErrAlreadyExists)
        }
        return fmt.Errorf("postgresRepo.Create: %w", err)
    }
    return nil
}
```

**Repository rules:** ALWAYS translate known DB errors to domain errors; wrap with `%w`; NEVER return raw `sql.ErrNoRows` or `*pq.Error`; NEVER log.

---

## Service Layer — Wrap with Context

Services implement business logic. They receive domain errors from repositories, add context, and propagate upward. NEVER handle HTTP.

```go
func (s *UserService) GetByID(ctx context.Context, id int64) (*domain.User, error) {
    user, err := s.repo.GetByID(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("UserService.GetByID(%d): %w", id, err)
    }
    return user, nil
}

func (s *UserService) Register(ctx context.Context, req domain.RegisterRequest) (*domain.User, error) {
    if req.Password != req.PasswordConfirm {
        return nil, fmt.Errorf("UserService.Register: %w",
            &domain.ValidationError{Field: "password_confirm", Message: "passwords do not match"},
        )
    }
    user := &domain.User{Email: req.Email, Name: req.Name}
    if err := s.repo.Create(ctx, user); err != nil {
        return nil, fmt.Errorf("UserService.Register: %w", err)
    }
    return user, nil
}
```

**Service rules:**
- ALWAYS use `%w` — never `%v` — so errors.Is/As work through the chain
- Add meaningful context: operation name, key parameter values
- NEVER call `c.JSON`, reference `net/http` status codes, or log
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