golang-patterns

name	golang-patterns
description	Idiomatic Go patterns, modern best practices, and production-grade code standards Use when this capability is needed.
metadata	{"author":"atstaeff"}

Golang Patterns Skill

Instructions for AI

Apply idiomatic Go patterns, modern best practices, and production-grade code standards. Use this skill when writing, reviewing, or refactoring Go code. Follow Go's philosophy: simplicity, clarity, composition.

Reference: Effective Go, Go Code Review Comments, Uber Go Style Guide.

Core Patterns

1. Repository Pattern with Interfaces

Abstraction over data access, enabling testability and swappable backends.

type OrderRepository interface {
    Create(ctx context.Context, order *Order) error
    GetByID(ctx context.Context, id uuid.UUID) (*Order, error)
    List(ctx context.Context, filter OrderFilter) ([]Order, error)
    Update(ctx context.Context, order *Order) error
    Delete(ctx context.Context, id uuid.UUID) error
}

// PostgreSQL implementation
type postgresOrderRepo struct {
    db *sql.DB
}

func NewPostgresOrderRepo(db *sql.DB) OrderRepository {
    return &postgresOrderRepo{db: db}
}

func (r *postgresOrderRepo) GetByID(ctx context.Context, id uuid.UUID) (*Order, error) {
    var o Order
    err := r.db.QueryRowContext(ctx,
        `SELECT id, customer_id, total, status, created_at
         FROM orders WHERE id = $1`, id,
    ).Scan(&o.ID, &o.CustomerID, &o.Total, &o.Status, &o.CreatedAt)

    if errors.Is(err, sql.ErrNoRows) {
        return nil, fmt.Errorf("order %s: %w", id, ErrNotFound)
    }
    if err != nil {
        return nil, fmt.Errorf("querying order %s: %w", id, err)
    }
    return &o, nil
}

2. Service Layer with Dependency Injection

Business logic encapsulated in services with injected dependencies.

type OrderService struct {
    repo   OrderRepository
    events EventPublisher
    logger *slog.Logger
}

func NewOrderService(repo OrderRepository, events EventPublisher, logger *slog.Logger) *OrderService {
    return &OrderService{repo: repo, events: events, logger: logger}
}

func (s *OrderService) PlaceOrder(ctx context.Context, cmd PlaceOrderCommand) (*Order, error) {
    order, err := NewOrder(cmd.CustomerID, cmd.Items)
    if err != nil {
        return nil, fmt.Errorf("creating order: %w", err)
    }

    if err := s.repo.Create(ctx, order); err != nil {
        return nil, fmt.Errorf("saving order: %w", err)
    }

    if err := s.events.Publish(ctx, "orders.placed", OrderPlacedEvent{
        OrderID:    order.ID,
        CustomerID: order.CustomerID,
        Total:      order.Total,
    }); err != nil {
        s.logger.WarnContext(ctx, "event publish failed", slog.String("error", err.Error()))
    }

    return order, nil
}

3. Domain Errors — Sentinel + Wrapping

// Sentinel errors for domain-level error classification
var (
    ErrNotFound      = errors.New("not found")
    ErrAlreadyExists = errors.New("already exists")
    ErrUnauthorized  = errors.New("unauthorized")
    ErrForbidden     = errors.New("forbidden")
    ErrValidation    = errors.New("validation error")
    ErrConflict      = errors.New("conflict")
)

// Structured validation error
type FieldError struct {
    Field   string `json:"field"`
    Message string `json:"message"`
}

type ValidationErrors struct {
    Errors []FieldError `json:"errors"`
}

func (e *ValidationErrors) Error() string {
    return fmt.Sprintf("validation failed: %d errors", len(e.Errors))
}

func (e *ValidationErrors) Unwrap() error {
    return ErrValidation
}

// Map domain errors to HTTP in handler
func mapError(err error) (int, string) {
    switch {
    case errors.Is(err, ErrNotFound):
        return http.StatusNotFound, "Resource not found"
    case errors.Is(err, ErrUnauthorized):
        return http.StatusUnauthorized, "Unauthorized"
    case errors.Is(err, ErrForbidden):
         http.StatusForbidden, 
     errors.Is(err, ErrValidation):
         http.StatusBadRequest, err.Error()
     errors.Is(err, ErrConflict):
         http.StatusConflict, 
    :
         http.StatusInternalServerError, 
    }
}

4. Functional Options Pattern

type ClientOption func(*Client)

func WithTimeout(d time.Duration) ClientOption {
    return func(c *Client) { c.timeout = d }
}

func WithRetries(n int) ClientOption {
    return func(c *Client) { c.maxRetries = n }
}

func WithBaseURL(url string) ClientOption {
    return func(c *Client) { c.baseURL = url }
}

func NewClient(opts ...ClientOption) *Client {
    c := &Client{
        timeout:    30 * time.Second,
        maxRetries: 3,
        baseURL:    "https://api.example.com",
        httpClient: http.DefaultClient,
    }
    for _, opt := range opts {
        opt(c)
    }
    return c
}

5. Worker Pool with errgroup

import "golang.org/x/sync/errgroup"

func ProcessBatch(ctx context.Context, items []Item, concurrency int) error {
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(concurrency)

    for _, item := range items {
        item := item // capture loop variable (Go < 1.22)
        g.Go(func() error {
            select {
            case <-ctx.Done():
                return ctx.Err()
            default:
                return processItem(ctx, item)
            }
        })
    }

    return g.Wait()
}

6. Middleware Chain (HTTP)

type Middleware func(http.Handler) http.Handler

func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
    for i := len(middlewares) - 1; i >= 0; i-- {
        handler = middlewares[i](handler)
    }
    return handler
}

func RequestIDMiddleware() Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            requestID := r.Header.Get("X-Request-ID")
            if requestID == "" {
                requestID = uuid.NewString()
            }
            ctx := context.WithValue(r.Context(), requestIDKey, requestID)
            w.Header().Set("X-Request-ID", requestID)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

func TimeoutMiddleware(d time.Duration) Middleware {
    return func(next http.Handler) http.Handler {
        return http.TimeoutHandler(next, d, "request timeout")
    }
}

7. Table-Driven Tests with Subtests

func TestParseAmount(t *testing.T) {
    tests := []struct {
        name    string
        input   string
        want    float64
        wantErr bool
    }{
        {name: "valid integer", input: "100", want: 100.0},
        {name: "valid decimal", input: "99.99", want: 99.99},
        {name: "negative", input: "-50", want: -50.0},
        {name: "empty string", input: "", wantErr: true},
        {name: "not a number", input: "abc", wantErr: true},
        {name: "overflow", input: "1e309", wantErr: true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := ParseAmount(tt.input)
            if tt.wantErr {
                if err == nil {
                    t.Fatal("expected error, got nil")
                }
                return
            }
            if err != nil {
                t.Fatalf("unexpected error: %v", err)
            }
            if got != tt.want {
                t.Errorf("ParseAmount(%q) = %v, want %v", tt.input, got, tt.want)
            }
        })
    }
}

8. Fake Implementations for Testing

// Fake repository for unit tests — no external dependencies
type FakeOrderRepo struct {
    mu     sync.Mutex
    orders map[uuid.UUID]*Order
}

func NewFakeOrderRepo() *FakeOrderRepo {
    return &FakeOrderRepo{orders: make(map[uuid.UUID]*Order)}
}

func (r *FakeOrderRepo) Create(_ context.Context, order *Order) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    if _, exists := r.orders[order.ID]; exists {
        return fmt.Errorf("order %s: %w", order.ID, ErrAlreadyExists)
    }
    r.orders[order.ID] = order
    return nil
}

func (r *FakeOrderRepo) GetByID(_ context.Context, id uuid.UUID) (*Order, error) {
    r.mu.Lock()
    defer r.mu.Unlock()
    order, ok := r.orders[id]
    if !ok {
        return nil, fmt.Errorf("order %s: %w", id, ErrNotFound)
    }
    return order, nil
}

9. Configuration with Environment Variables

type Config struct {
    ServerAddr   string        `env:"SERVER_ADDR" default:":8080"`
    DatabaseURL  string        `env:"DATABASE_URL" required:"true"`
    RedisURL     string        `env:"REDIS_URL" default:"redis://localhost:6379"`
    LogLevel     string        `env:"LOG_LEVEL" default:"info"`
    ReadTimeout  time.Duration `env:"READ_TIMEOUT" default:"15s"`
    WriteTimeout time.Duration `env:"WRITE_TIMEOUT" default:"15s"`
}

func LoadConfig() (*Config, error) {
    cfg := &Config{}
    if err := envconfig.Process("", cfg); err != nil {
        return nil, fmt.Errorf("loading config: %w", err)
    }
    return cfg, nil
}

10. Graceful Shutdown

func Run(ctx context.Context, cfg *Config, logger *slog.Logger) error {
    srv := &http.Server{
        Addr:         cfg.ServerAddr,
        Handler:      setupRouter(cfg, logger),
        ReadTimeout:  cfg.ReadTimeout,
        WriteTimeout: cfg.WriteTimeout,
    }

    errCh := make(chan error, 1)
    go func() {
        logger.Info("server starting", slog.String("addr", cfg.ServerAddr))
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            errCh <- err
        }
    }()

    select {
    case err := <-errCh:
        return fmt.Errorf("server error: %w", err)
    case <-ctx.Done():
        logger.Info("shutting down...")
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
        defer cancel()
        return srv.Shutdown(shutdownCtx)
    }
}

func main() {
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()

    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    cfg, err := LoadConfig()
    if err != nil {
        logger.Error("config error", slog.String("error", err.Error()))
        os.Exit(1)
    }

    if err := Run(ctx, cfg, logger); err != nil {
        logger.Error("server failed", slog.String("error", err.Error()))
        os.Exit()
    }
}

Project Structure

cmd/
├── api/main.go              # API entrypoint
└── worker/main.go           # Worker entrypoint
internal/
├── domain/                  # Pure domain logic, no external deps
│   ├── order.go
│   ├── order_test.go
│   └── errors.go
├── service/                 # Application use cases
│   ├── order_service.go
│   └── order_service_test.go
├── repository/              # Interfaces + implementations
│   ├── interfaces.go
│   └── postgres/
├── handler/                 # HTTP/gRPC transport
│   └── order_handler.go
├── middleware/               # Cross-cutting concerns
└── config/                  # Configuration
pkg/                         # Public reusable code (optional)
├── httputil/
└── testutil/

Best Practices

✅ Accept interfaces, return structs ✅ Handle every error — wrap with fmt.Errorf("context: %w", err) ✅ Use context.Context as the first parameter ✅ Prefer composition over embedding for non-trivial types ✅ Use slog for structured logging ✅ Table-driven tests with t.Run subtests ✅ internal/ for private application code ✅ Functional options for configurable constructors ✅ errgroup for concurrent operations with error handling ✅ go vet, golangci-lint, -race in CI

Anti-Patterns

❌ init() with side effects ❌ context.Context stored in structs ❌ Ignoring errors with _ ❌ interface{} / any when generics or specific types work ❌ Global mutable state ❌ panic for expected errors ❌ Premature interfaces — wait until you need 2+ implementations ❌ Giant main() functions — extract into Run(ctx, cfg) functions ❌ Naked returns in complex functions

Example Prompts

• "Refactor this Go code to use interfaces and dependency injection"
• "Write table-driven tests for this Go function including edge cases"
• "Design a concurrent pipeline with worker pool and graceful shutdown"
• "Review this Go code for idiomatic patterns and error handling"

Related Skills

• Golang Expert Agent
• Clean Code
• Design Patterns
• Testing Strategies
• GCP Patterns
• Anti-Patterns

---

Source: atstaeff/ai-agents — distributed by TomeVault.