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/messaging-consumer-workqueues.md

View on GitHub
# Messaging — Consumer Pattern and Work Queues

How to run background consumers in Go Gin APIs using RabbitMQ.

Companion to `messaging-consumer-docker.md` (Docker Compose setup for RabbitMQ).

---

## Consumer Pattern

**Gate:** Run consumers as goroutines in a dedicated worker binary or in `main.go`. Never block the HTTP server. **Cost: MEDIUM** — each goroutine holds a channel; size your pool accordingly.

```go
// internal/worker/email_consumer.go
package worker

import (
	"context"
	"encoding/json"
	"fmt"
	"log/slog"

	amqp "github.com/rabbitmq/amqp091-go"
	"yourmodule/pkg/messaging"
)

type EmailConsumer struct {
	conn   *messaging.Connection
	mailer Mailer
	logger *slog.Logger
}

type EmailPayload struct {
	UserID string `json:"user_id"`
	Email  string `json:"email"`
	Type   string `json:"type"`
}

func (c *EmailConsumer) Run(ctx context.Context) error {
	ch, err := c.conn.Channel()
	if err != nil {
		return fmt.Errorf("EmailConsumer.Run channel: %w", err)
	}
	defer ch.Close()

	if err := ch.Qos(1, 0, false); err != nil { // one unacked message at a time
		return fmt.Errorf("EmailConsumer.Run qos: %w", err)
	}

	q, err := messaging.DeclareQueue(ch, messaging.QueueOpts{
		Name:    "email.send",
		Durable: true,
		DLX:     "dlx.email",
	})
	if err != nil {
		return fmt.Errorf("EmailConsumer.Run declare: %w", err)
	}

	deliveries, err := ch.Consume(q.Name, "", false, false, false, false, nil)
	if err != nil {
		return fmt.Errorf("EmailConsumer.Run consume: %w", err)
	}

	c.logger.Info("email consumer started", "queue", q.Name)
	for {
		select {
		case <-ctx.Done():
			c.logger.Info("email consumer shutting down")
			return nil
		case d, ok := <-deliveries:
			if !ok {
				return fmt.Errorf("EmailConsumer: delivery channel closed")
			}
			c.handle(ctx, d)
		}
	}
}

func (c *EmailConsumer) handle(ctx context.Context, d amqp.Delivery) {
	var payload EmailPayload
	if err := json.Unmarshal(d.Body, &payload); err != nil {
		c.logger.ErrorContext(ctx, "bad payload, dead-lettering",
			"message_id", d.MessageId, "error", err)
		_ = d.Nack(false, false) // permanent failure → DLQ
		return
	}
	if err := c.mailer.Send(ctx, payload.Email, payload.Type); err != nil {
		c.logger.WarnContext(ctx, "transient error, requeueing",
			"message_id", d.MessageId, "error", err)
		_ = d.Nack(false, true) // requeue for retry
		return
	}
	c.logger.InfoContext(ctx, "email sent", "message_id", d.MessageId, "to", payload.Email)
	_ = d.Ack(false)
}
```

---

## Work Queues — Competing Consumers

**Gate:** Use when a single consumer cannot keep up. **Cost: LOW** — same queue, multiple consumers; RabbitMQ round-robins by default.

```go
// cmd/worker/main.go
package main

import (
	"context"
	"log/slog"
	"os"
	"os/signal"
	"syscall"

	"yourmodule/internal/worker"
	"yourmodule/pkg/messaging"
)

func main() {
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

	conn, err := messaging.NewConnection(messaging.Config{
		URL: os.Getenv("RABBITMQ_URL"),
	}, logger)
	if err != nil {
		logger.Error("failed to connect to rabbitmq", "error", err)
		os.Exit(1)
	}
	defer conn.Close()

	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer cancel()

	// Run N=3 competing consumers on the same queue.
	for range 3 {
		consumer := worker.NewEmailConsumer(conn, logger)
		go func() {
			if err := consumer.Run(ctx); err != nil {
				logger.Error("email consumer error", "error", err)
			}
		}()
	}

	<-ctx.Done()
	logger.Info("worker shutting down")
}
```

**Key Rule:** Set `ch.Qos(1, 0, false)` so each consumer only prefetches one message. Without this, a busy consumer gets starved while another is overloaded.
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