Go Expert Skill

Overview

This skill provides expert guidance for Go development following industry best practices. It covers coding standards, project structure, observability requirements, and CI gates.

When to Use This Skill

• Bootstrapping new Go microservices
• Writing or reviewing Go code
• Implementing health endpoints, logging, metrics, or tracing
• Configuring linters and CI pipelines
• Troubleshooting Go applications
• Setting up table-driven tests or race detection
• Implementing graceful shutdown patterns

Project Layout

Follow a domain-driven folder structure, organizing code by business domain rather than technical layer:

project/
├── cmd/
│   └── myapp/
│       └── main.go           # Entry point (keep minimal, under 20 lines)
├── internal/
│   ├── domain/               # Business domains (the core)
│   │   ├── user/
│   │   │   ├── user.go       # Entity, value objects
│   │   │   ├── repository.go # Repository interface
│   │   │   ├── service.go    # Business logic
│   │   │   └── errors.go     # Domain-specific errors
│   │   ├── order/
│   │   │   ├── order.go
│   │   │   ├── repository.go
│   │   │   ├── service.go
│   │   │   └── errors.go
│   │   └── conversation/
│   │       ├── vcon.go
│   │       ├── repository.go
│   │       ├── service.go
│   │       └── errors.go
│   ├── infra/                # Infrastructure implementations
│   │   ├── postgres/         # Database adapters
│   │   ├── redis/            # Cache adapters
│   │   └── http/             # HTTP handlers
│   ├── app/                  # Application services (orchestration)
│   │   └── app.go
│   └── config/
│       └── config.go
├── pkg/                       # Public library code (if any)
├── api/                       # API definitions (OpenAPI, protobuf)
├── scripts/                   # Build/deployment scripts
├── testdata/                  # Test fixtures
├── go.mod
├── go.sum
└── Makefile

Key Principles:

• Organize by domain, not by layer — Group all user-related code together, not all handlers together
• Domain independence — Each domain package should be self-contained with its own entities, repository interfaces, and services
• Dependency inversion — Domain defines interfaces, infra implements them
• Keep

  cmd/

  minimal — Just wire dependencies and call

  internal/

• Use

  internal/

  — Enforces package boundaries at compile time
• Infra adapters — Database, cache, and HTTP handlers implement domain interfaces

Design Principles

SOLID Principles (Required)

All Go code MUST follow SOLID principles:

user/service.go

Repository

Service

Reader

Writer

ReadWriter

Repository

PostgresRepo

// ✅ SOLID example

// Single Responsibility: UserService only handles user business logic
// Dependency Inversion: Depends on Repository interface, not concrete implementation
// Interface Segregation: Small, focused interface
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*User, error)
    Save(ctx context.Context, user *User) error
}

type UserService struct {
    repo   UserRepository  // Depends on abstraction
    logger *slog.Logger
}

func NewUserService(repo UserRepository, logger *slog.Logger) *UserService {
    return &UserService{repo: repo, logger: logger}
}

// Open/Closed: New repository implementations don't require changing UserService
// Liskov Substitution: PostgresRepo, MockRepo, RedisRepo all work here

Gang of Four Design Patterns (Required)

Apply Gang of Four patterns where appropriate:

Creational Patterns:

• Factory — Use constructor functions (

  NewService

  ,

  NewRepository

  )
• Builder — For complex object construction with many optional parameters
• Singleton — Use sparingly; prefer dependency injection

Structural Patterns:

• Adapter — Wrap external APIs to match your domain interfaces
• Decorator — Add behavior (logging, metrics) without modifying core logic
• Facade — Simplify complex subsystems with a unified interface

Behavioral Patterns:

• Strategy — Inject different algorithms via interfaces
• Observer — Event-driven communication between components
• Repository — Abstract data access behind interfaces

// Factory pattern
func NewUserService(repo UserRepository, logger *slog.Logger) *UserService {
    return &UserService{repo: repo, logger: logger}
}

// Options/Builder pattern for complex configuration
type ServiceOption func(*Service)

func WithTimeout(d time.Duration) ServiceOption {
    return func(s *Service) { s.timeout = d }
}

func WithRetries(n int) ServiceOption {
    return func(s *Service) { s.retries = n }
}

func NewService(repo Repository, opts ...ServiceOption) *Service {
    s := &Service{repo: repo, timeout: 30 * time.Second, retries: 3}
    for _, opt := range opts {
        opt(s)
    }
    return s
}

// Decorator pattern for adding logging
type LoggingRepository struct {
    next   UserRepository
    logger *slog.Logger
}

func (r *LoggingRepository) FindByID(ctx context.Context, id string) (*User, error) {
    r.logger.Info("finding user", "id", id)
    user, err := r.next.FindByID(ctx, id)
    if err != nil {
        r.logger.Error("failed to find user", "id", id, "error", err)
    }
    return user, err
}

// Strategy pattern via interfaces
type NotificationStrategy interface {
    Send(ctx context.Context, user *User, message string) error
}

type EmailNotifier struct{}
type SMSNotifier struct{}
type SlackNotifier struct{}

// All implement NotificationStrategy, injectable at runtime

File Organization

Guidelines:

• Functions under 50 lines — If longer, extract helper functions
• Files under 300 lines (soft limit) — If exceeded, check for multiple responsibilities
• One domain concept per file —

  user.go

  ,

  repository.go

  ,

  service.go

  ,

  errors.go

• Don't artificially split cohesive code — Keeping related code together trumps line limits

# Good: Each file has single responsibility
internal/domain/user/
├── user.go           # Entity and value objects (~50-100 lines)
├── repository.go     # Repository interface (~20-30 lines)
├── service.go        # Business logic (~100-200 lines)
├── errors.go         # Domain errors (~30-50 lines)
└── user_test.go      # Tests

# Bad: One massive file with everything
internal/domain/user/
└── user.go           # 800 lines with entity, repo, service, errors

When to split a file:

• Multiple structs with their own methods
• Mixed concerns (e.g., entity + HTTP handler)
• File exceeds 300 lines AND has multiple responsibilities

When NOT to split:

• Code is cohesive and related
• Splitting would require excessive cross-file navigation
• The file is long but has single responsibility

Application Bootstrap Pattern

Main Function

The

main()

Application

func main() {
    app, err := NewApplication()
    if err != nil {
        slog.Error("failed to initialize application", "error", err)
        os.Exit(1)
    }
    if err := app.Run(); err != nil {
        slog.Error("application error", "error", err)
        os.Exit(1)
    }
}

Application Struct

type Application struct {
    config   *config.Config
    log      *slog.Logger
    db       *sql.DB
    server   *http.Server
    services *Services
    tracer   trace.Tracer
}

func NewApplication() (*Application, error) {
    // Build dependencies in order
}

func (a *Application) Run() error {
    // Start server + graceful shutdown
}

func (a *Application) Shutdown(ctx context.Context) error {
    // Cleanup in reverse order
}

Tooling Gates

All Go code MUST pass these checks before merge:

gofmt -l .

go vet ./...

golangci-lint run

go test ./...

go test -race ./...

govulncheck ./...

golangci-lint Configuration

# .golangci.yml
run:
  timeout: 5m

linters:
  enable:
    - errcheck
    - gosimple
    - govet
    - ineffassign
    - staticcheck
    - unused
    - gofmt
    - goimports
    - misspell
    - unconvert
    - unparam
    - gosec
    - bodyclose
    - noctx

linters-settings:
  errcheck:
    check-type-assertions: true
  govet:
    check-shadowing: true

Linter Compliance

NEVER use

//nolint

gocyclo

gocognit

// ❌ Never do this
//nolint:gocyclo
func main() { /* 200 lines */ }

// ✅ Refactor instead
func main() {
    app, err := NewApplication()
    // ...
}

Health Endpoints

Every service MUST expose Kubernetes-compatible health checks:

• GET /healthz

  — Liveness probe (is the process alive?)

• GET /readyz

  — Readiness probe (can it accept traffic?)

func (s *Server) registerHealthRoutes(mux *http.ServeMux) {
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        w.Write([]byte(`{"status":"healthy"}`))
    })

    mux.HandleFunc("/readyz", func(w http.ResponseWriter, r *http.Request) {
        if err := s.db.Ping(r.Context()); err != nil {
            w.WriteHeader(http.StatusServiceUnavailable)
            w.Write([]byte(`{"status":"not ready"}`))
            return
        }
        w.WriteHeader(http.StatusOK)
        w.Write([]byte(`{"status":"ready"}`))
    })
}

Structured Logging

Use structured JSON logging for production services. A well-designed log entry includes:

{
    "timestamp": "2025-01-15T10:30:45.123Z",
    "level": "INFO",
    "service": {
        "name": "my-service",
        "version": "1.2.3",
        "environment": "prod"
    },
    "message": "Request processed",
    "traceId": "abc123def456789012345678901234",
    "requestId": "req-789"
}

Key Fields:

• timestamp

  : ISO 8601, UTC

• level

  : Uppercase (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)

• service

  : Name, version, environment

• message

  : Human-readable, NO PII

• traceId

  : For distributed tracing (32-char hex)

PII Redaction (Required)

NEVER log PII. Implement redaction before logging:

// ❌ Never log raw PII
logger.Info("user registered", "email", user.Email)

// ✅ Redact PII
logger.Info("user registered",
    "userId", user.ID,
    "email", redactEmail(user.Email),
    "clientIp", redactIP(request.RemoteAddr),
)

func redactEmail(email string) string {
    parts := strings.Split(email, "@")
    if len(parts) == 2 {
        return "[REDACTED]@" + parts[1]
    }
    return "[EMAIL_REDACTED]"
}

Never log: passwords, API keys, tokens, credit card numbers, SSN, phone numbers, full addresses, dates of birth.

Metrics

Every service MUST expose Prometheus metrics at

/metrics

var (
    httpRequestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total HTTP requests",
        },
        []string{"method", "path", "status"},
    )
    httpRequestDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "http_request_duration_seconds",
            Help:    "HTTP request latency",
            Buckets: prometheus.DefBuckets,
        },
        []string{"method", "path"},
    )
)

Tracing

OpenTelemetry with W3C Trace Context propagation:

func (s *Service) Process(ctx context.Context, id string) error {
    tracer := otel.Tracer("my-service")
    ctx, span := tracer.Start(ctx, "Process")
    defer span.End()

    span.SetAttributes(attribute.String("entity.id", id))
    return s.repo.Get(ctx, id)
}

Error Handling

Error Wrapping

Always wrap errors with context using

%w

if err := database.Connect(cfg); err != nil {
    return fmt.Errorf("connecting to database: %w", err)
}

All initialization errors bubble up to

main()

os.Exit()

Sentinel Errors

Define sentinel errors for expected conditions:

var (
    ErrNotFound     = errors.New("not found")
    ErrUnauthorized = errors.New("unauthorized")
    ErrRateLimited  = errors.New("rate limited")
)

Error Checking

Use

errors.Is()

errors.As()

if errors.Is(err, ErrNotFound) {
    // Handle not found
}

var validationErr *ValidationError
if errors.As(err, &validationErr) {
    log.Printf("Invalid field: %s", validationErr.Field)
}

Return Early

Use guard clauses to avoid deep nesting:

// ❌ Deep nesting
func process(data []byte) error {
    if data != nil {
        if len(data) > 0 {
            if isValid(data) {
                // work
            }
        }
    }
    return nil
}

// ✅ Return early
func process(data []byte) error {
    if data == nil {
        return ErrNilData
    }
    if len(data) == 0 {
        return ErrEmptyData
    }
    if !isValid(data) {
        return ErrInvalidData
    }
    // work
    return nil
}

Context & Concurrency

Context as First Parameter

func (s *Service) GetUser(ctx context.Context, id string) (*User, error) {
    select {
    case <-ctx.Done():
        return nil, ctx.Err()
    default:
    }
    return s.repo.FindByID(ctx, id)
}

Always Defer Cancel

func processWithTimeout(parent context.Context) error {
    ctx, cancel := context.WithTimeout(parent, 30*time.Second)
    defer cancel()
    return doWork(ctx)
}

Guard Shared State

type Counter struct {
    mu    sync.Mutex
    value int64
}

func (c *Counter) Increment() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.value++
}

Testing

Table-Driven Tests

func TestCalculateDiscount(t *testing.T) {
    tests := []struct {
        name       string
        price      float64
        percentage float64
        want       float64
    }{
        {"10% off $100", 100, 10, 90},
        {"no discount", 100, 0, 100},
        {"full discount", 100, 100, 0},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := CalculateDiscount(tt.price, tt.percentage)
            if got != tt.want {
                t.Errorf("got %v, want %v", got, tt.want)
            }
        })
    }
}

Race Detection

Always run tests with race detection:

go test -race ./...

Integration Tests

Use build tags to separate integration tests:

//go:build integration

package integration

func TestDatabaseConnection(t *testing.T) {
    // Requires real database
}

go test -tags=integration ./...

Makefile Template

.PHONY: lint test build check

lint:
	gofmt -l .
	go vet ./...
	golangci-lint run

test:
	go test -race -coverprofile=coverage.out ./...
	go tool cover -func=coverage.out

build:
	go build -o bin/myapp ./cmd/myapp

check: lint test
	govulncheck ./...

New Service Checklist

• main()

  under 20 lines
• Project follows domain-driven folder structure
• SOLID principles applied throughout
• Gang of Four patterns used appropriately
• Functions under 50 lines
• Files under 300 lines (or single responsibility if longer)

• Application

  struct with

  NewApplication()

  ,

  Run()

  ,

  Shutdown()

• /healthz

  and

  /readyz

  endpoints
• Prometheus metrics at

  /metrics

• OpenTelemetry tracing configured
• TraceId propagation (W3C Trace Context, 32-char hex)
• JSON structured logging
• PII redaction implemented and tested
• No

  //nolint

  for complexity
• All errors wrapped with context
• Sentinel errors for expected conditions
• Graceful shutdown with configurable timeout
• Table-driven tests with

  t.Run()

  subtests
• Race detection passes (

  go test -race

  )

• govulncheck

  passes

• golangci-lint

  passes with standard config

Anti-Patterns to Avoid

❌ Organizing by technical layer instead of domain
   internal/handlers/, internal/models/, internal/services/
   → internal/domain/user/, internal/domain/order/

❌ Violating Single Responsibility
   UserService that also sends emails and logs metrics
   → Separate EmailService, MetricsService

❌ Depending on concretions instead of abstractions
   func NewService(repo *PostgresRepo) → func NewService(repo Repository)

❌ Large interfaces (violates Interface Segregation)
   type Repository interface { 20 methods... }
   → Split into Reader, Writer, Deleter interfaces

❌ Functions over 50 lines
   Refactor into smaller, focused helper functions

❌ Files over 300 lines with multiple responsibilities
   Split by domain concept: entity, repository, service, errors

❌ Using //nolint to suppress complexity warnings
   //nolint:gocyclo → Refactor into smaller functions

❌ Long main() functions
   func main() { /* 200 lines */ } → Extract to Application struct

❌ Panicking in library code
   panic(err) → return fmt.Errorf("context: %w", err)

❌ Deep nesting instead of guard clauses
   if x { if y { if z { } } } → Return early with guard clauses

❌ Ignoring context cancellation
   func Process(id string) → func Process(ctx context.Context, id string)

❌ Wrong health endpoint paths
   /health, /ready → /healthz, /readyz (Kubernetes convention)

❌ Logging PII
   logger.Info("user", "email", user.Email) → Redact before logging

❌ Missing traceId in logs
   slog.Info("message") → Include traceId on every log entry

❌ Using offset pagination
   ?page=3&per_page=25 → Use cursor-based pagination

❌ os.Exit() deep in call stack
   os.Exit(1) in helper → Bubble errors up to main()

❌ Not deferring cancel()
   ctx, cancel := context.WithTimeout(...) → defer cancel() immediately

❌ Interface pollution
   Large interfaces → Small, focused interfaces (1-3 methods)

❌ Not running race detector
   go test ./... → go test -race ./...

Related Resources

• Go DDD Example
• SOLID Go Design
• Effective Go
• Go Code Review Comments
• Uber Go Style Guide
• OpenTelemetry Go
• Prometheus Go Client