go-design-patterns
Idiomatic Golang design patterns — functional options, constructors, resource management, and architecture.
SKILL.mdskills/go/go-design-patterns/SKILL.md
GitHubCore Principles
- Simplicity over Sophistication — Apply patterns only when they solve a real problem.
- Explicit over Implicit — Avoid
init()functions and hidden global state. - Fail Fast — Validate at trust boundaries, trust internal code.
- Functional Options — The preferred way to design constructors for complex types.
- Resource Lifecycle — Every resource must have a clear owner and a guaranteed cleanup path (
defer Close()). - Graceful Shutdown — Ensure the process can finish in-flight work before exiting.
- Timeout Every External Call — Never hang indefinitely on an upstream service.
Functional Options Pattern
Use this for types with many optional configuration parameters.
type Server struct {
port int
timeout time.Duration
}
type Option func(*Server)
func WithPort(p int) Option {
return func(s *Server) { s.port = p }
}
func NewServer(opts ...Option) *Server {
s := &Server{port: 8080, timeout: 30 * time.Second} // Defaults
for _, opt := range opts {
opt(s)
}
return s
}
Resource Management
Always defer cleanup immediately after a successful resource acquisition.
f, err := os.Open(path)
if err != nil {
return err
}
defer f.Close()
Enums: Start at 1
Reserve the 0 value for "Unknown" or "Invalid" to catch uninitialized variables.
type Status int
const (
StatusUnknown Status = iota // 0
StatusActive // 1
StatusInactive // 2
)
Resilience Patterns
- Timeouts: Use
context.WithTimeout. - Retries: Always check for context cancellation between retries.
- Circuit Breakers: Use for unstable external dependencies.
- Rate Limiting: Protect your own resources from exhaustion.
Anti-patterns
- ❌
init()Abuse — Hard to test, hidden side effects, and can't return errors. - ❌ Mutable Globals — Make testing and concurrency hard. Use dependency injection instead.
- ❌ Panic for Control Flow — Panic is for truly unrecoverable bugs, not business errors.
- ❌ Unbounded Resources — Missing limits on connections, goroutines, or buffers.
- ❌ Premature Abstraction — Don't create interfaces until you have at least two implementations.