go-design-patterns

Files (4)

• SKILL.md
• behavioral-patterns.md · references/
• creation-patterns.md · references/
• resilience-and-types.md · references/

SKILL.md (first lines)

# Go Design Patterns

Go favors composition over inheritance and simplicity over abstraction.
These patterns are idiomatic Go — not Java patterns ported to Go.

> Community default. A project skill or agent-config rule that explicitly
> supersedes `go-design-patterns` takes precedence over this one.

Detailed reference material, loaded on demand:

- `references/creation-patterns.md` — functional options (full example),
  options vs config struct, constructors, factory.
- `references/behavioral-patterns.md` — strategy, middleware/decorator,
  result type, defer cleanup, sentinel vs zero values.
- `references/resilience-and-types.md` — retry with jitter, circuit
  breaker, bulkhead, parse-don't-validate types, status types.

Read a reference file only when the summary below is not enough.

## Pattern Selection

| Need | Pattern | Reference |
|---|---|---|
| Constructor with many optional settings | Functional options | creation-patterns.md |
| Config loaded from file/env, mostly required fields | Config struct | creation-patterns.md |
| Enforce invariants at creation | Constructor returning error | creation-patterns.md |
| Pick implementation from runtime config | Factory returning interface | creation-patterns.md |
| Swap simple behavior at runtime | Strategy via function type | behavioral-patterns.md |
| Swap complex behavior at runtime | Strategy via interface | behavioral-patterns.md |
| Wrap cross-cutting concerns (log, cache, metrics) | Middleware / decorator | behavioral-patterns.md |
| Value-or-error in concurrent pipelines | `Result[T]` struct | behavioral-patterns.md |
| Transient failures of a dependency | Retry with backoff and jitter | resilience-and-types.md |
| A dependency that is down | Circuit breaker, bulkhead | resilience-and-types.md |
| Validate once, trust afterwards | Parse into a type with unexported fields | resilience-and-types.md |
| Several booleans describing one lifecycle | A status type with explicit transitions | resilience-and-types.md |

## 1. Functional Options (essentials)

```go
type Option func(*Server)

func WithAddr(addr string) Option {
    return func(s *Server) { s.addr = addr }
}

func NewServer(opts ...Option) *Server {
    s := &Server{
        addr:        ":8080", // sensible defaults first
        readTimeout: 5 * time.Second,
        logger:      slog.Default(),
    }
    for _, opt := range opts {
        opt(s)
    }
    return s
}

srv := NewServer(WithAddr(":9090"))
```

Use when: many optional parameters with sensible defaults, API evolves over
time (new options don't break callers), options need validation.
Use a plain config struct instead when most fields are required or the
configuration is deserialized from file/env.

## 2. Constructor Rules

- Every exported type with invariants needs a constructor.
- Validate required dependencies; return an error, don't panic:

```go
// ✅ Good — constructor enforces invariants
func NewUserService(repo UserRepository, logger *slog.Logger) (*UserService, error) {
    if repo == nil {
        return nil, errors.New("user service: nil repository")
    }
    return &UserService{repo: repo, logger: logger}, nil
}

// ❌ Bad — struct literal with no validation
svc := &UserService{} // nil dependencies → panic at runtime
```

## 3. Factory

Return the interface, not a concrete type. The factory is the only place
that knows about concrete implementations:

```go
func NewStore(cfg Config) (Store, error) {
    switch cfg.StoreType {
    case "redis":
        return newRedisStore(cfg.RedisAddr)
    case "memory":
        return newMemoryStore(), nil
    default:
        return nil, fmt.Errorf("unknown store type: %s", cfg.StoreType)
    }
}
```

## 4. Middleware Chain

The standard HTTP composition pattern:

```go
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
}

handler := Chain(appHandler, Recoverer, RequestID, Logger, Auth)
```

The same shape works for any interface: stack decorators as

From eduardo-sl/go-agent-skills, MIT.

More from eduardo-sl/go-agent-skills