Expert assistant for rabbitmq-kit-go - Production-ready RabbitMQ library for Go with DDD patterns, retries, circuit breaking, and batch publishing
Expert assistant for developing with rabbitmq-kit-go - a production-ready RabbitMQ library for Go providing high-level abstractions for event-driven architectures following Domain-Driven Design patterns.
This skill helps you work with rabbitmq-kit-go, a Go library that handles:
**Tech Stack:**
**Architecture:**
**Coverage:** 81.0% (threshold: 80%)
When setting up the development environment:
1. **Check Go version:**
```bash
go version # Must be 1.25+
```
2. **Start RabbitMQ container:**
```bash
docker run -d --name rabbitmq -p 5672:5672 rabbitmq:3.13-management-alpine
```
3. **Set environment variable:**
```bash
export RABBITMQ_URI="amqp://guest:guest@localhost:5672/"
```
4. **Install dependencies:**
```bash
go mod download
```
5. **Install pre-commit hooks:**
```bash
make setup
```
Follow this testing hierarchy:
1. **Unit tests (fast, no Docker):**
```bash
make test-unit
```
2. **Integration tests (requires Docker):**
```bash
make test
```
3. **Coverage report:**
```bash
make test-coverage
make test-coverage-html # Opens browser
```
4. **Race detector:**
```bash
make test-race
```
When adding a new configuration option:
1. **Add field to Config struct** (`config/config.go`):
```go
type Config struct {
NewFeature bool
}
```
2. **Update DefaultConfig():**
```go
func DefaultConfig() Config {
return Config{NewFeature: false}
}
```
3. **Create functional option:**
```go
func WithNewFeature(enabled bool) Option {
return func(c *Config) { c.NewFeature = enabled }
}
```
4. **Add validation if needed**
5. **Write unit tests** for the new option
6. **Update documentation** in `docs/CONFIGURATION.md`
When defining new event types:
1. **Embed BaseEvent:**
```go
type OrderCompletedEvent struct {
*rabbitmq.BaseEvent
OrderID string
Amount float64
}
```
2. **Implement ToMap() method:**
```go
func (e *OrderCompletedEvent) ToMap() map[string]any {
m := e.BaseEvent.ToMap()
m["order_id"] = e.OrderID
m["amount"] = e.Amount
return m
}
```
3. **Ensure type field is set** for routing
4. **Add tests** for serialization/deserialization
When creating message handlers:
1. **Register handler with event type:**
```go
eventBus.RegisterHandler("order.completed", func(ctx *MessageContext) error {
// Handler logic
return nil
})
```
2. **ALWAYS use context** for timeouts/cancellation
3. **Return errors, don't panic:**
```go
if err := validate(ctx.Event); err != nil {
return fmt.Errorf("validation failed: %w", err)
}
```
4. **Keep handlers fast** (< 100ms) or use async processing:
```go
go processAsync(ctx)
return nil // ACK immediately
```
5. **Use structured logging:**
```go
logger.Error(ctx, "Handler error", map[string]any{
"event_type": ctx.Event.Type(),
"error": err,
})
```
When publishing events:
1. **Single event with timeout:**
```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
err := eventBus.Publish(ctx, event)
```
2. **Batch publishing (pipelined):**
```go
err := eventBus.PublishBatch(ctx, events, config.WithPipelining(true))
```
3. **Async batch (for 1000+ events):**
```go
err := eventBus.PublishBatchAsync(ctx, events, config.WithMaxConcurrency(50))
```
4. **Always check errors:**
```go
if err := eventBus.Publish(ctx, event); err != nil {
var pubErr *errors.PublishError
if errors.As(err, &pubErr) {
// Handle publish-specific error
}
return err
}
```
When handling errors:
1. **Use errors.Is for sentinel errors:**
```go
if errors.Is(err, errors.ErrPublishNotConfirmed) {
// Handle confirmation failure
}
```
2. **Use errors.As for typed errors:**
```go
var connErr *errors.ConnectionError
if errors.As(err, &connErr) {
// Handle connection error
}
```
3. **Create typed errors for new error types:**
```go
return errors.NewPublishError(exchange, routingKey, err)
```
4. **Log errors with context:**
```go
logger.Error(ctx, "Operation failed", map[string]any{
"operation": "publish",
"error": err,
})
```
Before committing:
1. **Run all checks:**
```bash
make pre-commit
```
2. **Format code:**
```bash
gofmt -w .
go mod tidy
```
3. **Run linter:**
```bash
golangci-lint run --fix
```
4. **Verify tests pass:**
```bash
make test
```
5. **Check coverage:**
```bash
make test-coverage # Must be ≥ 80%
```
When optimizing performance:
1. **Set prefetch count based on processing time:**
- Fast (<100ms): 50-100
- Medium (100ms-1s): 10-20
- Slow (>1s): 1-5
2. **Set worker count based on workload:**
- CPU-bound: `runtime.NumCPU()`
- I/O-bound: `runtime.NumCPU() * 2-4`
3. **Use batch publishing for bulk operations:**
- Pipelined: 5-10x faster
- Async: Best for 1000+ events
4. **Enable publisher confirms** for reliability
Checklist for new public API:
**❌ Creating EventBus per request:**
```go
// BAD - creates new connection each time
func HandleRequest(w http.ResponseWriter, r *http.Request) {
eb, _ := rabbitmq.NewEventBus(...)
defer eb.Close()
}
// GOOD - reuse EventBus
var globalEventBus *rabbitmq.EventBus
```
**❌ Blocking in handlers:**
```go
// BAD - blocks worker pool
eventBus.RegisterHandler("event", func(ctx *MessageContext) error {
time.Sleep(10 * time.Second) // ❌
return nil
})
// GOOD - async processing
eventBus.RegisterHandler("event", func(ctx *MessageContext) error {
go processAsync(ctx)
return nil // ACK immediately
})
```
**❌ Ignoring context:**
```go
// BAD - no timeout
eventBus.Publish(context.Background(), event)
// GOOD - with timeout
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
eventBus.Publish(ctx, event)
```
**❌ Panicking in handlers:**
```go
// BAD - crashes worker
panic("error")
// GOOD - return error
return fmt.Errorf("validation failed: %w", err)
```
1. ✅ Tests pass (`make test`)
2. ✅ Coverage ≥ 80%
3. ✅ Linter passes (`make pre-commit`)
4. ✅ No breaking API changes
5. ✅ Godoc for public types/methods
6. ✅ Integration test for RabbitMQ interactions
7. ✅ Context support for I/O operations
8. ✅ Structured error handling
Run examples to see features in action:
```bash
go run examples/basic/main.go
go run examples/circuit-breaker/main.go
go run examples/dlq/main.go
go run examples/batch/main.go
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/rabbitmq-kit-go-development-guide/raw