name: go-backend-microservices
description: Go backend development best practices for microservices with clean architecture, observability, and production-ready patterns

Go Backend Development for Microservices

Core Principles

• Apply Clean Architecture with clear separation into handlers, services, repositories, and domain models
• Prioritize interface-driven development with explicit dependency injection
• Write short, focused functions with a single responsibility
• Ensure safe use of goroutines, and guard shared state with channels or sync primitives

Project Structure

Maintain modular project structure with clear directories:

project/
├── cmd/           # Application entry points
├── internal/      # Private application code
├── pkg/           # Public library code
├── api/           # API definitions (OpenAPI, protobuf)
├── configs/       # Configuration files
└── test/          # Additional test utilities

Error Handling

• Always check and handle errors explicitly
• Use wrapped errors for traceability: fmt.Errorf("context: %w", err)
• Create custom error types for domain-specific errors
• Return errors up the call stack with appropriate context
• Log errors at the appropriate level with sufficient context

Context Propagation

• Use context propagation for request-scoped values, deadlines, and cancellations
• Pass context as the first parameter to functions
• Respect context cancellation in long-running operations
• Set appropriate timeouts for external calls

Observability

Implement OpenTelemetry for comprehensive observability:

Distributed Tracing

• Add spans for significant operations
• Propagate trace context across service boundaries
• Include relevant attributes in spans

Metrics

• Implement custom metrics for business operations
• Use standard metric types (counters, gauges, histograms)
• Export metrics in Prometheus format

Structured Logging

• Use structured logging with consistent field names
• Include trace IDs in log entries
• Log at appropriate levels (debug, info, warn, error)

Security

• Apply input validation rigorously on all external inputs
• Use secure defaults for JWT tokens and cookies
• Implement proper authentication and authorization
• Sanitize data before logging to avoid leaking sensitive information
• Use prepared statements for database queries

Testing

Unit Tests

• Write table-driven unit tests with adequate coverage
• Use parallel test execution where safe
• Mock external dependencies using interfaces
• Focus on testing business logic

Integration Tests

• Separate integration tests from unit tests
• Use test containers for database and service dependencies
• Test actual API endpoints and responses

Concurrency

• Use goroutines appropriately for concurrent operations
• Guard shared state with channels or sync primitives
• Implement proper graceful shutdown
• Use worker pools for bounded concurrency

Documentation

• Document with GoDoc-style comments
• Keep comments up to date with code changes
• Document public APIs thoroughly
• Include examples in documentation where helpful

CI/CD Integration

• Maintain CI integration for linting and testing
• Use golangci-lint for comprehensive linting
• Run tests on every pull request
• Include code coverage reporting