henriqueatila/golang-gin-best-practices / skills/golang-gin-architect
golang-gin-architect
VerifiedSoftware architect for Go Gin APIs. Use when making architecture decisions, evaluating complexity, designing systems, choosing patterns, or coordinating across gin skills.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |