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-circuit-breaker-bulkhead.md

View on GitHub
# Resilience Patterns — Circuit Breaker and Bulkhead

Low-cost patterns for making Go Gin APIs resilient to external dependency failures.

**Default stance:** Add these to any service that calls external APIs. They cost little and prevent cascading failures.

---

## Circuit Breaker

### Gate — you need this when

- [ ] Your service calls an external API or service that can be slow or unavailable
- [ ] Timeouts alone would block goroutines too long under cascading failure

**Cost: LOW (2/5).** A 50-line wrapper on your HTTP client is worth it for any external dependency.

**Simpler alternative:** A generous `http.Client` timeout + retry with backoff. Add the circuit breaker once you observe that retries amplify load on the failing upstream.

### Implementation (`github.com/sony/gobreaker/v2`)

```go
// pkg/resilience/circuit_breaker.go
func NewCircuitBreaker(name string) *gobreaker.CircuitBreaker[[]byte] {
    return gobreaker.NewCircuitBreaker[[]byte](gobreaker.Settings{
        Name:        name,
        MaxRequests: 3,                // allow 3 requests in half-open state
        Interval:    60 * time.Second, // reset counts every 60s in closed state
        Timeout:     30 * time.Second, // wait 30s in open state before half-open
        ReadyToTrip: func(counts gobreaker.Counts) bool {
            return counts.ConsecutiveFailures > 5
        },
        OnStateChange: func(name string, from, to gobreaker.State) {
            slog.Warn("circuit breaker state changed",
                "name", name, "from", from.String(), "to", to.String())
        },
    })
}

func CallWithBreaker(ctx context.Context, cb *gobreaker.CircuitBreaker[[]byte], fn func() ([]byte, error)) ([]byte, error) {
    result, err := cb.Execute(func() ([]byte, error) {
        return fn()
    })
    if err != nil {
        return nil, fmt.Errorf("circuit breaker %s: %w", cb.Name(), err)
    }
    return result, nil
}
```

### Usage in a service

```go
type Client struct {
    http *http.Client
    cb   *gobreaker.CircuitBreaker[[]byte]
}

func NewClient() *Client {
    return &Client{
        http: &http.Client{Timeout: 5 * time.Second},
        cb:   resilience.NewCircuitBreaker("payment-api"),
    }
}

func (c *Client) Charge(ctx context.Context, orderID string) error {
    body, err := resilience.CallWithBreaker(ctx, c.cb, func() ([]byte, error) {
        req, _ := http.NewRequestWithContext(ctx, "POST", "https://payment.example.com/charge", nil)
        resp, err := c.http.Do(req)
        if err != nil {
            return nil, err
        }
        defer resp.Body.Close()
        if resp.StatusCode >= 500 {
            return nil, fmt.Errorf("upstream error: %d", resp.StatusCode)
        }
        return io.ReadAll(resp.Body)
    })
    _ = body
    return err
}
```

---

## Bulkhead Pattern

### Gate — you need this when

- [ ] One slow dependency is causing goroutine saturation affecting unrelated parts of your service
- [ ] You can identify 2+ distinct dependency groups with different SLA expectations

**Cost: LOW (2/5).** A semaphore is 5 lines of Go.

**Simpler alternative:** Set an aggressive `context.WithTimeout` on the slow call. Add bulkhead when you need concurrent capacity control, not just timeout protection.

### Implementation

```go
// pkg/resilience/bulkhead.go
type Bulkhead struct {
    name string
    sem  chan struct{}
}

func NewBulkhead(name string, maxConcurrent int) *Bulkhead {
    return &Bulkhead{name: name, sem: make(chan struct{}, maxConcurrent)}
}

func (b *Bulkhead) Execute(ctx context.Context, fn func() error) error {
    select {
    case b.sem <- struct{}{}:
        defer func() { <-b.sem }()
        return fn()
    case <-ctx.Done():
        return fmt.Errorf("bulkhead %s: %w", b.name, ctx.Err())
    }
}
```

### Usage — isolate database from external API calls

```go
var (
    dbBulkhead  = resilience.NewBulkhead("database", 50)
    apiBulkhead = resilience.NewBulkhead("payment-api", 10)
)

func (s *OrderService) CreateOrder(ctx context.Context, cmd order.CreateOrderCommand) (string, error) {
    var id string
    err := dbBulkhead.Execute(ctx, func() error {
        var e error
        id, e = s.repo.Create(ctx, cmd)
        return e
    })
    return id, err
}
```

---

## See Also

- `resilience-retry-rate-limiting.md` — retry with exponential backoff, rate limiting architecture, pattern comparison table
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