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/resilience-retry-rate-limiting.md

View on GitHub
# Resilience Patterns — Retry with Backoff and Rate Limiting

Companion to `resilience-circuit-breaker-bulkhead.md` (circuit breaker, bulkhead pattern).

---

## Retry with Exponential Backoff

**Cost: LOW (1/5).** Apply by default to any external HTTP or gRPC call. Not needed for local database calls (driver handles reconnects; adding retries can cause double-writes).

**Jitter** prevents retry storms when many goroutines fail simultaneously.

```go
// pkg/resilience/retry.go
type RetryConfig struct {
    MaxRetries  int           // number of retries (not total attempts)
    BaseBackoff time.Duration // base sleep before first retry (doubles each attempt)
    MaxBackoff  time.Duration // cap on sleep duration
}

var DefaultRetryConfig = RetryConfig{
    MaxRetries:  3,
    BaseBackoff: 100 * time.Millisecond,
    MaxBackoff:  2 * time.Second,
}

func Retry(ctx context.Context, cfg RetryConfig, fn func() error) error {
    var lastErr error
    for attempt := 0; attempt <= cfg.MaxRetries; attempt++ {
        if err := fn(); err != nil {
            lastErr = err
            if attempt == cfg.MaxRetries {
                break
            }
            backoff := cfg.BaseBackoff * (1 << uint(attempt))
            if backoff > cfg.MaxBackoff {
                backoff = cfg.MaxBackoff
            }
            jitter := time.Duration(rand.Int63n(int64(backoff / 2)))
            select {
            case <-time.After(backoff + jitter):
            case <-ctx.Done():
                return fmt.Errorf("retry cancelled: %w", ctx.Err())
            }
            continue
        }
        return nil
    }
    return fmt.Errorf("after %d retries: %w", cfg.MaxRetries, lastErr)
}
```

Usage:

```go
err := resilience.Retry(ctx, resilience.DefaultRetryConfig, func() error {
    return paymentClient.Charge(ctx, orderID)
})
```

**When NOT to retry:** database writes (risk double-insert), non-idempotent operations without idempotency keys, errors that are clearly permanent (4xx client errors).

---

## Rate Limiting at Architecture Level

Rate limiting in a single Gin instance (middleware) is covered in `golang-gin-api/references/rate-limiting.md`. This section covers architectural decisions.

### Decision Matrix

| Scenario | Approach |
|---|---|
| Single binary, simple protection | In-memory token bucket (no Redis) |
| Multiple instances, IP-based limits | Redis token bucket with Lua |
| Per-user billing accuracy | Redis sliding window, key = user ID |
| Global API quota across all routes | API gateway (Kong, Traefik, nginx) |
| Rate limiting for paid tiers | Redis + tier config loaded from env |

### Per-Service Limits

Each internal service should define its own limits independently. Do not use a shared rate limiter across services — failure domains must stay isolated.

```go
// Per-route group limits — different SLAs for different endpoints
public := r.Group("/api/v1")
public.Use(middleware.MemoryRateLimiter(middleware.MemoryRateLimiterConfig{
    Rate: 10, Burst: 20,
}, done))

authenticated := r.Group("/api/v1")
authenticated.Use(authMiddleware, middleware.TieredRateLimiter(rdb, tiers, "rl:auth:"))
```

**Key design choices:**
- Key by user ID (from JWT `sub` claim) over IP — survives NAT and mobile IP changes
- Fail open on Redis errors — blocking all traffic because a cache is down is worse than briefly allowing excess
- Set `X-RateLimit-Remaining` on every response, not only on 429

---

## Pattern Comparison Table

| Pattern | Complexity Cost | When to Use | Simple Alternative |
|---|---|---|---|
| Circuit Breaker | LOW (2/5) | Any external dependency that can be slow/down | Timeout + retry backoff |
| Bulkhead | LOW (2/5) | One slow dep saturating goroutines | `context.WithTimeout` on slow calls |
| Retry + Backoff | LOW (1/5) | Any external call (default: always use) | Single call with timeout |
| Rate Limiting (distributed) | MEDIUM (3/5) | Multiple instances + per-user accuracy | In-memory token bucket (single node) |

**Reading the cost scale:** 1 = one file, no new dependencies. 5 = new infrastructure, new failure modes, weeks of learning curve.
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: 323kUpdated 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