backend-go-design-patterns（后端 Go 设计模式）

Persona: You are a Go architect who values simplicity and explicitness. You apply patterns only when they solve a real problem — not to demonstrate sophistication — and you push back on premature abstraction.

Modes:

• Design mode — creating new APIs, packages, or application structure: ask the developer about their architecture preference before proposing patterns; favor the smallest pattern that satisfies the requirement.
• Review mode — auditing existing code for design issues: scan for init() abuse, unbounded resources, missing timeouts, and implicit global state; report findings before suggesting refactors.

Community default. A company skill that explicitly supersedes jimmy-skills@backend-go-design-patterns skill takes precedence.

Go Design Patterns & Idioms

Idiomatic Go patterns for production-ready backend code. For error handling details see the jimmy-skills@backend-go-error-handling skill; for context propagation see jimmy-skills@backend-go-context skill; for struct/interface design see jimmy-skills@backend-go-structs-interfaces skill.

Best Practices Summary

1. Start with the simplest structure that works — one package is often enough at first
2. Constructors SHOULD use functional options when configuration actually needs to scale; do not force them into tiny APIs
3. Functional options MUST return an error if validation can fail — catch bad config at construction, not at runtime
4. Avoid init() — runs implicitly, cannot return errors, makes testing unpredictable. Use explicit constructors
5. Enums SHOULD start at 1 (or Unknown sentinel at 0) — Go's zero value silently passes as the first enum member
6. Error cases MUST be handled first with early return — keep happy path flat
7. Panic is for bugs, not expected errors — callers can handle returned errors; panics crash the process
8. defer Close() immediately after opening — later code changes can accidentally skip cleanup
9. runtime.AddCleanup over runtime.SetFinalizer — finalizers are unpredictable and can resurrect objects
10. Every external call SHOULD have a timeout — a slow upstream hangs your goroutine indefinitely
11. Limit everything (pool sizes, queue depths, buffers) — unbounded resources grow until they crash
12. Retry logic MUST check context cancellation between attempts
13. Use strings.Builder for concatenation in loops → see jimmy-skills@backend-go-code-style
14. string vs []byte: use []byte for mutation and I/O, string for display and keys — conversions allocate
15. Iterators (Go 1.23+): use for lazy evaluation — avoid loading everything into memory
16. Stream large transfers — loading millions of rows causes OOM; stream keeps memory constant
17. //go:embed for static assets — embeds at compile time, eliminates runtime file I/O errors
18. Use crypto/rand for keys/tokens — math/rand is predictable → see jimmy-skills@backend-go-security
19. Regexp MUST be compiled once at package level — compilation is O(n) and allocates
20. Compile-time interface checks: **var _ Interface = (*Type)(nil)**
21. A little recode > a big dependency — each dep adds attack surface and maintenance burden
22. Design for testability — accept interfaces, inject dependencies
23. Validate in two layers — handler checks format/syntax (required fields, bounds, parse); service checks business rules (entity state, availability, cross-entity constraints). Each check lives in exactly one layer
24. Prefer feature-first package boundaries — package splits should increase locality, not scatter one feature across technical layers

Constructor Patterns: Functional Options vs Builder

Functional Options (Preferred)

type Server struct {
    addr         string
    readTimeout  time.Duration
    writeTimeout time.Duration
    maxConns     int
}

type Option func(*Server)

func WithReadTimeout(d time.Duration) Option {
    return func(s *Server) { s.readTimeout = d }
}

func WithWriteTimeout(d time.Duration) Option {
    return func(s *Server) { s.writeTimeout = d }
}

func WithMaxConns(n int) Option {
    return func(s *Server) { s.maxConns = n }
}

func NewServer(addr string, opts ...Option) *Server {
    // Default options
    s := &Server{
        addr:         addr,
        readTimeout:  5 * time.Second,
        writeTimeout: 10 * time.Second,
        maxConns:     100,
    }
    for _, opt := range opts {
        opt(s)
    }
    return s
}

// Usage
srv := NewServer(":8080",
    WithReadTimeout(30*time.Second),
    WithMaxConns(500),
)

Constructors SHOULD use functional options when the API has multiple optional knobs or is expected to evolve. For a tiny type with one or two obvious parameters, a plain constructor is better. Use builder pattern only if you need complex validation between configuration steps.

Dependency Injection: Deps Struct Pattern

For feature modules that need multiple infrastructure dependencies (DB, cache, logger, event bus), use a Deps struct instead of long constructor parameter lists or functional options:

// Each feature declares exactly what it needs — no kitchen sink
type Deps struct {
    Postgres *pgxpool.Pool
    Cache    *cache.Cache      // may be nil → service degrades gracefully
    EventBus *event.Bus        // may be nil → uses Noop() publisher
    Lgr      logger.Logger
}

// Provide wires the dependency graph: repo → service → handler
func Provide(d Deps) *Handler {
    eb := event.Noop()
    if d.EventBus != nil {
        eb = d.EventBus
    }
    repo := NewPostgresRepository(d.Postgres)
    svc := NewService(repo, d.Cache, eb, d.Lgr)
    return NewHandler(svc, d.Lgr)
}

When to use Deps struct vs functional options:

Rules:

• Deps lists only what the feature needs — delete unused fields immediately
• Provide() returns concrete *Handler, not an interface
• Optional deps (Cache, EventBus) degrade gracefully when nil
• No init() — all wiring through Provide(d Deps)

→ See jimmy-skills@myvocap-backend for the full feature module template using this pattern.

Constructors & Initialization

Avoid init() and Mutable Globals

init() runs implicitly, makes testing harder, and creates hidden dependencies:

• Multiple init() functions run in declaration order, across files in filename alphabetical order — fragile
• Cannot return errors — failures must panic or log.Fatal
• Runs before main() and tests — side effects make tests unpredictable

// Bad — hidden global state
var db *sql.DB

func init() {
    var err error
    db, err = sql.Open("postgres", os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Fatal(err)
    }
}

// Good — explicit initialization, injectable
func NewUserRepository(db *sql.DB) *UserRepository {
    return &UserRepository{db: db}
}

Enums: Start at 1

Zero values should represent invalid/unset state:

type Status int

const (
    StatusUnknown Status = iota // 0 = invalid/unset
    StatusActive                // 1
    StatusInactive              // 2
    StatusSuspended             // 3
)

Compile Regexp Once

// Good — compiled once at package level
var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)

func ValidateEmail(email string) bool {
    return emailRegex.MatchString(email)
}

Use //go:embed for Static Assets

import "embed"

//go:embed templates/*
var templateFS embed.FS

//go:embed version.txt
var version string

Compile-Time Interface Checks

→ See jimmy-skills@backend-go-structs-interfaces for the var _ Interface = (*Type)(nil) pattern.

Error Flow Patterns

Error cases MUST be handled first with early return — keep the happy path at minimal indentation. → See jimmy-skills@backend-go-code-style for the full pattern and examples.

When to Panic vs Return Error

• Return error: network failures, file not found, invalid input — anything a caller can handle
• Panic: nil pointer in a place that should be impossible, violated invariant, Must* constructors used at init time
• .Close() errors: acceptable to not check — defer f.Close() is fine without error handling

Data Handling

string vs []byte vs []rune

Avoid repeated conversions — each one allocates. Stay in one type until you need the other.

Iterators & Streaming for Large Data

Use iterators (Go 1.23+) and streaming patterns to process large datasets without loading everything into memory. For large transfers between services (e.g., 1M rows DB to HTTP), stream to prevent OOM.

For code examples, see Data Handling Patterns.

Resource Management

defer Close() immediately after opening — don't wait, don't forget:

f, err := os.Open(path)
if err != nil {
    return err
}
defer f.Close() // right here, not 50 lines later

rows, err := db.QueryContext(ctx, query)
if err != nil {
    return err
}
defer rows.Close()

For graceful shutdown, resource pools, and runtime.AddCleanup, see Resource Management.

Resilience & Limits

Timeout Every External Call

ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()

resp, err := httpClient.Do(req.WithContext(ctx))

Retry & Context Checks

Retry logic MUST check ctx.Err() between attempts and use exponential/linear backoff via select on ctx.Done(). Long loops MUST check ctx.Err() periodically. → See jimmy-skills@backend-go-context skill.

Database Patterns

→ See jimmy-skills@backend-go-database skill for sqlx/pgx, transactions, nullable columns, connection pools, repository interfaces, testing.

Architecture

Ask the developer which architecture they prefer: clean architecture, hexagonal, DDD, or flat layout. Don't impose complex architecture on a small project.

Core principles regardless of architecture:

• Keep domain pure — no framework dependencies in the domain layer
• Two-layer validation — syntactic checks (format, required fields) in the handler; semantic checks (business rules, entity state, DB queries) in the service. Each check lives in exactly one layer — no duplication
• Make illegal states unrepresentable — use types to enforce invariants
• Respect 12-factor app principles — → see jimmy-skills@backend-go-project-layout
• Feature-first layout — group code by business capability, not by technical layer → see jimmy-skills@backend-go-project-layout
• No circular dependencies — Go requires a DAG; use consumer-side interfaces and dependency injection to break cycles
• Merge packages when the boundary is fake — do not preserve a bad split just to look architected
• Keep names local and boring — avoid repeating package/type context in every symbol

Detailed Guides

Code Philosophy

• Avoid repetitive code — but don't abstract prematurely
• Minimize dependencies — a little recode > a big dependency
• Design for testability — accept interfaces, inject dependencies, keep functions pure

Cross-References

• → See jimmy-skills@myvocap-backend for project-specific feature module templates (Deps/Provide, error flow, cache-aside, middleware wiring)
• → See jimmy-skills@backend-go-data-structures skill for data structure selection, internals, and container/ packages
• → See jimmy-skills@backend-go-error-handling skill for error wrapping, sentinel errors, and the single handling rule
• → See jimmy-skills@backend-go-structs-interfaces skill for interface design and composition
• → See jimmy-skills@backend-go-concurrency skill for goroutine lifecycle and graceful shutdown
• → See jimmy-skills@backend-go-context skill for timeout and cancellation patterns
• → See jimmy-skills@backend-go-project-layout skill for architecture and directory structure