Golang Expert

Project Structure Guidelines

• Use a consistent project layout:
  • cmd/: application entrypoints
  • internal/: core application logic (not exposed externally)
  • pkg/: shared utilities and packages
  • api/: gRPC/REST transport definitions and handlers
  • configs/: configuration schemas and loading
  • test/: test utilities, mocks, and integration tests
• Group code by feature when it improves clarity and cohesion.
• Keep logic decoupled from framework-specific code.

Development Best Practices

• Write short, focused functions with a single responsibility.
• Always check and handle errors explicitly, using wrapped errors for traceability (fmt.Errorf("context: %w", err)).
• Avoid global state; use constructor functions to inject dependencies.
• Leverage Go's context propagation for request-scoped values, deadlines, and cancellations.
• Use goroutines safely; guard shared state with channels or sync primitives.
• Defer closing resources and handle them carefully to avoid leaks.
• Use Functional Options Pattern for configuration and dependency injection where structs have more than 2 fields and are part of a public api.
• Use sensible defaults when creating constructors (func NewThing() {}).

Security and Resilience

• Apply input validation and sanitization rigorously.
• Use secure defaults for JWT, cookies, and configuration settings.
• Implement retries, exponential backoff, and timeouts on all external calls.
• Use circuit breakers and rate limiting for service protection.

Testing

• Write unit tests using table-driven patterns and parallel execution.
• Mock external interfaces cleanly using generated or handwritten mocks.
• Separate fast unit tests from slower integration and E2E tests.
• Ensure test coverage for every exported function.

Observability

• Use OpenTelemetry for distributed tracing, metrics, and structured logging.
• Start and propagate tracing spans across all service boundaries.
• Use log correlation by injecting trace IDs into structured logs.
• Trace all incoming requests and propagate context through internal and external calls.

Design Patterns

Use an established design pattern to help maintainability and understanding of code.

Use the design-patterns-go mcp to access details and examples of any of the below patterns.

ALWAYS consider what design pattern(s) are currently in use to help with single responsibility.

Creational Patterns

These patterns provide various object creation mechanisms, which increase flexibility and reuse of existing code.

• Factory Method
• Abstract Factory
• Builder
• Prototype
• Singleton

Structural Patterns

These patterns explain how to assemble objects and classes into larger structures while keeping these structures flexible and efficient.

• Adapter
• Bridge
• Composite
• Decorator
• Facade
• Flyweight
• Proxy

Behavorial Patterns

• Chain of Responsibility
• Command
• Iterator
• Mediator
• Memento
• Observer
• State
• Strategy
• Template Method
• Visitor

Linting and Quality (golangci-lint)

Core Philosophy

Fix the code first, configure second. When golangci-lint reports issues, fix the code. Only adjust configuration if truly necessary.

Common Issues

• errcheck: Always check errors. if err := file.Close(); err != nil { ... }
• cyclop: Keep cyclomatic complexity ≤ 10. Refactor complex functions.
• gosec: Avoid hardcoded secrets. Use environment variables.

Configuration

The project uses .golangci.yml. Common settings:

linters-settings:
  cyclop:
    max-complexity: 10
  gocognit:
    min-complexity: 30
  funlen:
    lines: 60
    statements: 40
  lll:
    line-length: 120
    tab-width: 1