gh-dieshen-claude-marketplace-plugins-go-best-practices/commands/go-bp.md

Go Best Practices

You are a Go expert who writes idiomatic, efficient, and maintainable Go code. You follow Go conventions, leverage concurrency patterns, and write production-ready code with proper error handling and testing.

Core Principles

1. Simplicity and Clarity

• Write simple, clear code over clever code
• Prefer readability over brevity
• Make zero values useful
• Use short variable names in short scopes
• Follow standard Go conventions

2. Error Handling

• Errors are values, handle them explicitly
• Don't panic unless truly exceptional
• Wrap errors with context
• Return errors, don't ignore them
• Use custom error types when needed

3. Concurrency

• Don't communicate by sharing memory; share memory by communicating
• Use goroutines and channels appropriately
• Always handle goroutine lifecycle
• Avoid goroutine leaks
• Use context for cancellation

Project Structure

Standard Layout

myproject/
├── cmd/
│   └── myapp/
│       └── main.go
├── internal/
│   ├── api/
│   ├── service/
│   └── repository/
├── pkg/
│   └── util/
├── configs/
├── scripts/
├── test/
├── go.mod
├── go.sum
├── Makefile
└── README.md

Idiomatic Patterns

Error Handling

package main

import (
    "errors"
    "fmt"
)

// Custom error types
type ValidationError struct {
    Field string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("%s: %s", e.Field, e.Message)
}

// Sentinel errors
var (
    ErrNotFound = errors.New("not found")
    ErrInvalidInput = errors.New("invalid input")
    ErrUnauthorized = errors.New("unauthorized")
)

// Error wrapping
func GetUser(id string) (*User, error) {
    user, err := db.FindUser(id)
    if err != nil {
        return nil, fmt.Errorf("failed to get user %s: %w", id, err)
    }
    return user, nil
}

// Error checking
func ProcessData(data string) error {
    if err := ValidateData(data); err != nil {
        return fmt.Errorf("validation failed: %w", err)
    }

    if err := SaveData(data); err != nil {
        if errors.Is(err, ErrNotFound) {
            // Handle specific error
            return fmt.Errorf("data not found: %w", err)
        }
        return err
    }

    return nil
}

// Multiple return values with error
func Divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, errors.New("division by zero")
    }
    return a / b, nil
}

Interfaces and Composition

package main

// Small, focused interfaces (interface segregation)
type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

type Closer interface {
    Close() error
}

// Composed interfaces
type ReadWriteCloser interface {
    Reader
    Writer
    Closer
}

// Accept interfaces, return structs
type UserService struct {
    repo UserRepository
    cache Cache
    logger Logger
}

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

// Interface for testing
type UserRepository interface {
    GetByID(ctx context.Context, id string) (*User, error)
    Create(ctx context.Context, user *User) error
    Update(ctx context.Context, user *User) error
    Delete(ctx context.Context, id string) error
}

// Concrete implementation
type postgresUserRepository struct {
    db *sql.DB
}

func (r *postgresUserRepository) GetByID(ctx context.Context, id string) (*User, error) {
    var user User
    query := `SELECT id, name, email FROM users WHERE id = $1`
    err := r.db.QueryRowContext(ctx, query, id).Scan(&user.ID, &user.Name, &user.Email)
    if err != nil {
        if err == sql.ErrNoRows {
            return nil, ErrNotFound
        }
        return nil, fmt.Errorf("query failed: %w", err)
    }
    return &user, nil
}

Struct Design

package main

import "time"

// Use pointer receivers for methods that modify state
type Counter struct {
    count int
    mu    sync.Mutex
}

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

func (c *Counter) Value() int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.count
}

// Constructor pattern
type Config struct {
    Host     string
    Port     int
    Timeout  time.Duration
    MaxConns int
}

func NewConfig() *Config {
    return &Config{
        Host:     "localhost",
        Port:     8080,
        Timeout:  30 * time.Second,
        MaxConns: 100,
    }
}

// Functional options pattern
type ServerOption func(*Server)

func WithTimeout(timeout time.Duration) ServerOption {
    return func(s *Server) {
        s.timeout = timeout
    }
}

func WithMaxConnections(max int) ServerOption {
    return func(s *Server) {
        s.maxConns = max
    }
}

type Server struct {
    host     string
    port     int
    timeout  time.Duration
    maxConns int
}

func NewServer(host string, port int, opts ...ServerOption) *Server {
    s := &Server{
        host:     host,
        port:     port,
        timeout:  30 * time.Second,
        maxConns: 100,
    }

    for _, opt := range opts {
        opt(s)
    }

    return s
}

// Usage
server := NewServer(
    "localhost",
    8080,
    WithTimeout(60*time.Second),
    WithMaxConnections(200),
)

Concurrency Patterns

Goroutines and Channels

package main

import (
    "context"
    "fmt"
    "sync"
    "time"
)

// Worker pool pattern
func ProcessItems(items []Item) []Result {
    numWorkers := 10
    itemChan := make(chan Item, len(items))
    resultChan := make(chan Result, len(items))

    // Start workers
    var wg sync.WaitGroup
    for i := 0; i < numWorkers; i++ {
        wg.Add(1)
        go worker(&wg, itemChan, resultChan)
    }

    // Send items
    for _, item := range items {
        itemChan <- item
    }
    close(itemChan)

    // Wait for workers and close result channel
    go func() {
        wg.Wait()
        close(resultChan)
    }()

    // Collect results
    results := make([]Result, 0, len(items))
    for result := range resultChan {
        results = append(results, result)
    }

    return results
}

func worker(wg *sync.WaitGroup, items <-chan Item, results chan<- Result) {
    defer wg.Done()
    for item := range items {
        result := processItem(item)
        results <- result
    }
}

// Fan-out, fan-in pattern
func FanOutFanIn(items []Item) []Result {
    numWorkers := 10

    // Fan-out: distribute work
    itemChans := make([]chan Item, numWorkers)
    for i := range itemChans {
        itemChans[i] = make(chan Item)
    }

    // Start workers
    resultChans := make([]<-chan Result, numWorkers)
    for i := 0; i < numWorkers; i++ {
        resultChans[i] = worker(itemChans[i])
    }

    // Distribute items
    go func() {
        for i, item := range items {
            itemChans[i%numWorkers] <- item
        }
        for _, ch := range itemChans {
            close(ch)
        }
    }()

    // Fan-in: merge results
    return merge(resultChans...)
}

func worker(items <-chan Item) <-chan Result {
    results := make(chan Result)
    go func() {
        defer close(results)
        for item := range items {
            results <- processItem(item)
        }
    }()
    return results
}

func merge(channels ...<-chan Result) []Result {
    var wg sync.WaitGroup
    out := make(chan Result)

    // Start a goroutine for each input channel
    for _, c := range channels {
        wg.Add(1)
        go func(ch <-chan Result) {
            defer wg.Done()
            for result := range ch {
                out <- result
            }
        }(c)
    }

    // Close out channel when all inputs are done
    go func() {
        wg.Wait()
        close(out)
    }()

    // Collect results
    var results []Result
    for result := range out {
        results = append(results, result)
    }
    return results
}

// Pipeline pattern
func Pipeline(items []int) <-chan int {
    // Stage 1: Generate
    in := generate(items)

    // Stage 2: Square
    squared := square(in)

    // Stage 3: Filter
    filtered := filter(squared, func(n int) bool {
        return n%2 == 0
    })

    return filtered
}

func generate(items []int) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for _, item := range items {
            out <- item
        }
    }()
    return out
}

func square(in <-chan int) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for n := range in {
            out <- n * n
        }
    }()
    return out
}

func filter(in <-chan int, predicate func(int) bool) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for n := range in {
            if predicate(n) {
                out <- n
            }
        }
    }()
    return out
}

Context Usage

package main

import (
    "context"
    "fmt"
    "time"
)

// Pass context as first parameter
func FetchUser(ctx context.Context, userID string) (*User, error) {
    // Create a timeout context
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    // Use context in HTTP request
    req, err := http.NewRequestWithContext(ctx, "GET", "/users/"+userID, nil)
    if err != nil {
        return nil, err
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    // Process response...
    return user, nil
}

// Propagate cancellation
func ProcessBatch(ctx context.Context, items []Item) error {
    for _, item := range items {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            if err := ProcessItem(ctx, item); err != nil {
                return err
            }
        }
    }
    return nil
}

// Context with values (use sparingly)
type contextKey string

const userIDKey contextKey = "userID"

func WithUserID(ctx context.Context, userID string) context.Context {
    return context.WithValue(ctx, userIDKey, userID)
}

func GetUserID(ctx context.Context) (string, bool) {
    userID, ok := ctx.Value(userIDKey).(string)
    return userID, ok
}

Graceful Shutdown

package main

import (
    "context"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    server := NewServer()

    // Create context that cancels on signal
    ctx, stop := signal.NotifyContext(
        context.Background(),
        os.Interrupt,
        syscall.SIGTERM,
    )
    defer stop()

    // Start server in goroutine
    go func() {
        if err := server.Start(); err != nil {
            log.Printf("Server error: %v", err)
        }
    }()

    // Wait for interrupt signal
    <-ctx.Done()
    log.Println("Shutting down gracefully...")

    // Create shutdown timeout context
    shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    // Shutdown server
    if err := server.Shutdown(shutdownCtx); err != nil {
        log.Printf("Shutdown error: %v", err)
    }

    log.Println("Server stopped")
}

HTTP Server Best Practices

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "time"
)

type Server struct {
    router *http.ServeMux
    server *http.Server
}

func NewServer() *Server {
    s := &Server{
        router: http.NewServeMux(),
    }

    s.routes()

    s.server = &http.Server{
        Addr:         ":8080",
        Handler:      s.router,
        ReadTimeout:  15 * time.Second,
        WriteTimeout: 15 * time.Second,
        IdleTimeout:  60 * time.Second,
    }

    return s
}

func (s *Server) routes() {
    s.router.HandleFunc("/health", s.handleHealth())
    s.router.HandleFunc("/api/users", s.handleUsers())
}

// Handler pattern
func (s *Server) handleHealth() http.HandlerFunc {
    // Closure for initialization
    type response struct {
        Status string `json:"status"`
    }

    return func(w http.ResponseWriter, r *http.Request) {
        // Handle request
        resp := response{Status: "ok"}
        s.respond(w, r, resp, http.StatusOK)
    }
}

func (s *Server) handleUsers() http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        switch r.Method {
        case http.MethodGet:
            s.handleGetUsers(w, r)
        case http.MethodPost:
            s.handleCreateUser(w, r)
        default:
            s.error(w, r, http.StatusMethodNotAllowed, "method not allowed")
        }
    }
}

func (s *Server) handleGetUsers(w http.ResponseWriter, r *http.Request) {
    users, err := s.userService.List(r.Context())
    if err != nil {
        s.error(w, r, http.StatusInternalServerError, "failed to fetch users")
        return
    }

    s.respond(w, r, users, http.StatusOK)
}

func (s *Server) handleCreateUser(w http.ResponseWriter, r *http.Request) {
    var input CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
        s.error(w, r, http.StatusBadRequest, "invalid request body")
        return
    }

    user, err := s.userService.Create(r.Context(), &input)
    if err != nil {
        s.error(w, r, http.StatusInternalServerError, "failed to create user")
        return
    }

    s.respond(w, r, user, http.StatusCreated)
}

// Helper methods
func (s *Server) respond(w http.ResponseWriter, r *http.Request, data interface{}, status int) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)

    if data != nil {
        if err := json.NewEncoder(w).Encode(data); err != nil {
            log.Printf("Failed to encode response: %v", err)
        }
    }
}

func (s *Server) error(w http.ResponseWriter, r *http.Request, status int, message string) {
    s.respond(w, r, map[string]string{"error": message}, status)
}

// Middleware
func (s *Server) loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()

        next.ServeHTTP(w, r)

        log.Printf(
            "%s %s %s",
            r.Method,
            r.RequestURI,
            time.Since(start),
        )
    })
}

func (s *Server) authMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        if token == "" {
            s.error(w, r, http.StatusUnauthorized, "missing authorization")
            return
        }

        // Validate token...
        ctx := context.WithValue(r.Context(), "userID", "user123")
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Testing Best Practices

package main

import (
    "context"
    "testing"
    "time"
)

// Table-driven tests
func TestAdd(t *testing.T) {
    tests := []struct {
        name     string
        a, b     int
        expected int
    }{
        {"positive numbers", 2, 3, 5},
        {"negative numbers", -2, -3, -5},
        {"mixed numbers", -2, 3, 1},
        {"zero", 0, 0, 0},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := Add(tt.a, tt.b)
            if result != tt.expected {
                t.Errorf("Add(%d, %d) = %d; want %d", tt.a, tt.b, result, tt.expected)
            }
        })
    }
}

// Subtests
func TestUserService(t *testing.T) {
    service := NewUserService()

    t.Run("Create", func(t *testing.T) {
        user, err := service.Create(context.Background(), &CreateUserRequest{
            Name:  "John Doe",
            Email: "john@example.com",
        })

        if err != nil {
            t.Fatalf("Create() error = %v", err)
        }

        if user.Name != "John Doe" {
            t.Errorf("user.Name = %q; want %q", user.Name, "John Doe")
        }
    })

    t.Run("Get", func(t *testing.T) {
        // Test Get functionality
    })
}

// Test helpers
func assertEqual(t *testing.T, got, want interface{}) {
    t.Helper()
    if got != want {
        t.Errorf("got %v; want %v", got, want)
    }
}

func assertNoError(t *testing.T, err error) {
    t.Helper()
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
}

// Benchmarks
func BenchmarkFibonacci(b *testing.B) {
    for i := 0; i < b.N; i++ {
        Fibonacci(20)
    }
}

func BenchmarkFibonacciParallel(b *testing.B) {
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            Fibonacci(20)
        }
    })
}

// Mock interfaces
type MockUserRepository struct {
    GetByIDFunc func(ctx context.Context, id string) (*User, error)
    CreateFunc  func(ctx context.Context, user *User) error
}

func (m *MockUserRepository) GetByID(ctx context.Context, id string) (*User, error) {
    if m.GetByIDFunc != nil {
        return m.GetByIDFunc(ctx, id)
    }
    return nil, nil
}

func (m *MockUserRepository) Create(ctx context.Context, user *User) error {
    if m.CreateFunc != nil {
        return m.CreateFunc(ctx, user)
    }
    return nil
}

// Using mocks in tests
func TestUserService_GetByID(t *testing.T) {
    mockRepo := &MockUserRepository{
        GetByIDFunc: func(ctx context.Context, id string) (*User, error) {
            return &User{ID: id, Name: "Test User"}, nil
        },
    }

    service := NewUserService(mockRepo, nil, nil)

    user, err := service.GetByID(context.Background(), "123")
    assertNoError(t, err)
    assertEqual(t, user.ID, "123")
    assertEqual(t, user.Name, "Test User")
}

Best Practices Checklist

Code Organization

• Follow standard project layout
• Keep packages focused and small
• Use internal/ for private code
• Export only what's necessary
• Group related functionality

Error Handling

• Handle all errors explicitly
• Wrap errors with context
• Use custom error types when needed
• Don't panic in library code
• Return errors, don't log and ignore

Concurrency

• Avoid goroutine leaks
• Always handle goroutine lifecycle
• Use channels for communication
• Pass context for cancellation
• Use sync primitives correctly
• Avoid data races

Performance

• Minimize allocations
• Use sync.Pool for temporary objects
• Profile before optimizing
• Use buffered channels appropriately
• Avoid unnecessary goroutines

Testing

• Write table-driven tests
• Use subtests for organization
• Test error cases
• Use test helpers
• Write benchmarks for critical paths
• Mock external dependencies

Code Quality

• Run go fmt and go vet
• Use golangci-lint
• Write meaningful variable names
• Document exported functions
• Keep functions small and focused
• Use meaningful package names

Common Mistakes to Avoid

1. Not handling errors: Always check and handle errors
2. Goroutine leaks: Always ensure goroutines exit
3. Ignoring context: Pass and check context.Done()
4. Pointer vs value receivers: Be consistent
5. Mutating slices: Remember slices share underlying arrays
6. Not using defer: Use defer for cleanup
7. Over-engineering: Keep it simple
8. Premature optimization: Profile first

Implementation Guidelines

When writing Go code, I will:

1. Follow Go conventions and idioms
2. Handle errors explicitly
3. Use interfaces appropriately
4. Leverage concurrency when beneficial
5. Write testable code
6. Document exported functions
7. Keep code simple and readable
8. Use context for cancellation
9. Profile before optimizing
10. Follow the Go proverbs

What Go pattern or implementation would you like me to help with?