Go Patterns Skill

Idiomatic Go for production systems. Focuses on simplicity, explicitness, and composition.

When to Activate

Activate when:

• Writing new Go packages or services
• Reviewing Go code for idiom and correctness
• Designing concurrent processing pipelines
• Debugging goroutine leaks or race conditions
• Setting up module structure or build configuration

Error Handling

Go errors are values. Handle them at the point where you have enough context to act.

Wrapping and Unwrapping

import "errors"
import "fmt"

// Wrap with %w to preserve the chain
func loadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("loadConfig %q: %w", path, err)
    }
    // ...
}

// Inspect with errors.Is (sentinel) and errors.As (type)
var ErrNotFound = errors.New("not found")

if err := loadConfig("app.yaml"); err != nil {
    if errors.Is(err, os.ErrNotExist) {
        // file missing
    }
    var pathErr *os.PathError
    if errors.As(err, &pathErr) {
        log.Printf("path problem: %s", pathErr.Path)
    }
}

Sentinel Errors

// Define at package level, exported when callers need to check
var (
    ErrNotFound   = errors.New("not found")
    ErrPermission = errors.New("permission denied")
)

// Prefer typed errors when you need to attach data
type ValidationError struct {
    Field   string
    Message string
}

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

Error String Conventions

// ✅ lowercase, no trailing punctuation
errors.New("connection refused")
fmt.Errorf("user %d not found", id)

// ❌ uppercase or punctuation
errors.New("Connection refused.")

Interface Design

Keep interfaces small. A one-method interface is a feature, not a limitation.

The io.Reader / io.Writer Pattern

// Standard library interfaces — use them where they fit
type Reader interface {
    Read(p []byte) (n int, err error)
}

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

// Compose for more complex contracts
type ReadWriter interface {
    Reader
    Writer
}

// Accept interfaces, return concrete types
func Process(r io.Reader) ([]byte, error) {
    return io.ReadAll(r)
}

// os.File, bytes.Buffer, http.Response.Body all satisfy io.Reader

Define Interfaces at the Consumer

// ❌ Defining in the producer package forces coupling
package store
type Repository interface { ... }  // in the store package

// ✅ Define in the consumer package
package service
type userStore interface {
    FindByID(ctx context.Context, id int64) (*User, error)
    Save(ctx context.Context, u *User) error
}

type UserService struct {
    store userStore
}

Single-Method Naming

// Verb + "er" for single-method interfaces
type Reader interface { Read(...) }
type Writer interface { Write(...) }
type Stringer interface { String() string }
type Closer interface { Close() error }
type Handler interface { ServeHTTP(...) }

Goroutines and Channels

Worker Pool Pattern

func workerPool(ctx context.Context, jobs <-chan Job, workers int) <-chan Result {
    results := make(chan Result)

    var wg sync.WaitGroup
    wg.Add(workers)
    for range workers {
        go func() {
            defer wg.Done()
            for job := range jobs {
                select {
                case results <- process(job):
                case <-ctx.Done():
                    return
                }
            }
        }()
    }

    go func() {
        wg.Wait()
        close(results)
    }()

    return results
}

Fan-Out / Fan-In

// Fan-out: send work to N goroutines
func fanOut(in <-chan int, n int) []<-chan int {
    outs := make([]<-chan int, n)
    for i := range n {
        ch := make(chan int)
        outs[i] = ch
        go func() {
            defer close(ch)
            for v := range in {
                ch <- v * 2
            }
        }()
    }
    return outs
}

// Fan-in: merge N channels into one
func merge(channels ...<-chan int) <-chan int {
    out := make(chan int)
    var wg sync.WaitGroup
    wg.Add(len(channels))
    for _, ch := range channels {
        go func(c <-chan int) {
            defer wg.Done()
            for v := range c {
                out <- v
            }
        }(ch)
    }
    go func() {
        wg.Wait()
        close(out)
    }()
    return out
}

Select and Context Cancellation

func doWork(ctx context.Context) error {
    ticker := time.NewTicker(500 * time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        case t := <-ticker.C:
            if err := tick(t); err != nil {
                return fmt.Errorf("tick: %w", err)
            }
        }
    }
}

Channel Ownership Rule

The goroutine that creates a channel is responsible for closing it. Closing a channel from a reader or having multiple goroutines close the same channel causes panics.

Struct Embedding vs Composition

Embedding for Behaviour Promotion

type Logger struct {
    level string
}

func (l *Logger) Log(msg string) {
    fmt.Printf("[%s] %s\n", l.level, msg)
}

type Server struct {
    Logger           // promotes Log method
    addr   string
}

s := Server{Logger: Logger{level: "INFO"}, addr: ":8080"}
s.Log("starting")   // calls s.Logger.Log

Prefer Explicit Fields for Data

// ❌ Embedding for data models creates implicit API surface
type FullUser struct {
    User    // every User field/method becomes part of FullUser's API
    Profile
}

// ✅ Explicit fields make dependencies obvious
type FullUser struct {
    User    User
    Profile Profile
}

defer, panic, recover

defer — Always for Cleanup

func writeFile(path string, data []byte) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    defer f.Close()  // runs even if Write returns error

    _, err = f.Write(data)
    return err
}

// defer evaluates arguments immediately — useful for timing
func trace(name string) func() {
    start := time.Now()
    return func() { log.Printf("%s: %v", name, time.Since(start)) }
}
defer trace("expensiveOp")()

panic / recover — Only at Boundaries

// Use panic only for programmer errors (invariant violations)
func mustPositive(n int) int {
    if n <= 0 {
        panic(fmt.Sprintf("expected positive, got %d", n))
    }
    return n
}

// Recover at the top of a goroutine or HTTP handler to convert to error
func safeExec(fn func()) (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("panic: %v", r)
        }
    }()
    fn()
    return nil
}

Never use panic/recover as a substitute for regular error handling.

Table-Driven Tests

func TestParseDate(t *testing.T) {
    cases := []struct {
        name    string
        input   string
        want    time.Time
        wantErr bool
    }{
        {
            name:  "ISO format",
            input: "2024-01-15",
            want:  time.Date(2024, 1, 15, 0, 0, 0, 0, time.UTC),
        },
        {
            name:    "empty string",
            input:   "",
            wantErr: true,
        },
        {
            name:    "invalid format",
            input:   "15/01/2024",
            wantErr: true,
        },
    }

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            got, err := ParseDate(tc.input)
            if (err != nil) != tc.wantErr {
                t.Fatalf("ParseDate(%q) error = %v, wantErr %v", tc.input, err, tc.wantErr)
            }
            if !tc.wantErr && !got.Equal(tc.want) {
                t.Errorf("ParseDate(%q) = %v, want %v", tc.input, got, tc.want)
            }
        })
    }
}

Go Modules

go.mod Structure

module github.com/org/myservice

go 1.23

require (
    github.com/some/dep v1.2.3
)

Workspace Mode (go.work) for Multi-Module Repos

go 1.23

use (
    ./cmd/api
    ./internal/core
    ./pkg/client
)

go work init ./cmd/api ./internal/core
go work use ./pkg/client

Module Commands

go mod tidy          # add missing, remove unused
go mod vendor        # copy deps to vendor/
go get github.com/x@v1.2.3  # add or upgrade
go mod why github.com/x     # explain why dep is needed

sync Package

var mu sync.Mutex
mu.Lock()
defer mu.Unlock()

// RWMutex — many readers, one writer
var rw sync.RWMutex
rw.RLock()
defer rw.RUnlock()

// WaitGroup — wait for goroutines to finish
var wg sync.WaitGroup
wg.Add(1)
go func() {
    defer wg.Done()
    // ...
}()
wg.Wait()

// Once — run exactly once (e.g., lazy init)
var once sync.Once
var instance *DB
func getDB() *DB {
    once.Do(func() { instance = newDB() })
    return instance
}

// Atomic operations — simple counters without a mutex
var counter atomic.Int64
counter.Add(1)
n := counter.Load()

Build Tags

//go:build linux && amd64

package platform

// This file only compiles on 64-bit Linux.
func pageSize() int { return 4096 }

go build -tags integration ./...
go test -tags integration ./...

Common Pitfalls

Goroutine Leaks

// ❌ Nothing reads from results — goroutines block forever
func leak() {
    results := make(chan int)
    go func() { results <- compute() }()
    // forgot to read results
}

// ✅ Always ensure goroutines can exit — use buffered channels or context
func noLeak(ctx context.Context) {
    results := make(chan int, 1)
    go func() {
        select {
        case results <- compute():
        case <-ctx.Done():
        }
    }()
}

nil Interface vs nil Pointer

// ❌ Returning a typed nil as an interface is NOT nil
func getErr() error {
    var p *os.PathError = nil
    return p  // error interface is not nil!
}

// ✅ Return untyped nil
func getErr() error {
    return nil
}

Map Race Conditions

// ❌ Concurrent read/write on map causes data race
m := map[string]int{}
go func() { m["a"] = 1 }()
go func() { _ = m["a"] }()

// ✅ Use sync.Map or protect with a mutex
var mu sync.RWMutex
mu.Lock()
m["a"] = 1
mu.Unlock()