333-333-333/go-messaging

When to Use

• Publishing domain events after state changes
• Subscribing to events from other services
• Choosing a messaging backend for the project
• Implementing async workflows (notifications, emails, analytics)

Critical Patterns

| Pattern | Rule | |---------|------| | Interface in domain | EventPublisher is a domain port | | Implementation swappable | NATS, RabbitMQ, or Pub/Sub behind same interface | | Events are immutable facts | Past tense: BookingCreated, PaymentCompleted | | Events carry data | Include enough data so consumers don't need to call back | | Idempotent consumers | Subscribers MUST handle duplicate messages | | Cloud agnostic | Application layer never imports messaging SDK |

Event Definition (Domain)

Reference: assets/event.go

Domain Port

Reference: assets/port.go

NATS Implementation

Reference: assets/nats_publisher.go

Reference: assets/nats_subscriber.go

Topic Naming Convention

{service}.{domain}.{event}

Examples:
  booking.booking.created
  booking.booking.cancelled
  payment.transaction.completed
  caregiver.profile.verified
  notification.email.requested

Publishing from Application Layer

Reference: assets/publish_usage.go

In-Memory Implementation (Testing)

Reference: assets/memory_publisher.go

Commands

# NATS
brew install nats-server
nats-server  # Start locally

# Dependencies
go get github.com/nats-io/nats.go

# RabbitMQ alternative
docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:management
go get github.com/rabbitmq/amqp091-go

Anti-Patterns

| ❌ Don't | ✅ Do | |----------|-------| | Import NATS/RabbitMQ in domain | Define EventPublisher interface in domain | | Events named as commands (CreateBooking) | Events are past tense facts (BookingCreated) | | Consumer calls back to producer service | Include enough data in the event payload | | Assume exactly-once delivery | Design idempotent consumers | | Synchronous event publishing blocking the request | Use goroutines or accept best-effort for non-critical events |