Solizardking/clawd-bot / .agents/skills/golang-design-patterns
golang-design-patterns
VerifiedIdiomatic Golang design patterns — functional options, constructors, error flow and cascading, resource management and lifecycle, graceful shutdown, resilience, architecture, dependency injection, data handling, streaming, and more. Apply when explicitly choosing between architectural patterns, implementing functional options, designing constructor APIs, setting up graceful shutdown, applying resilience patterns, or asking which idiomatic Go pattern fits a specific problem.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
| evals/evals.json | config | 20.3 KB |
| references/architecture.md | markdown | 4.7 KB |
| references/clean-architecture.md | markdown | 5.0 KB |
| references/data-handling.md | markdown | 1.6 KB |
| references/ddd.md | markdown | 6.8 KB |
| references/hexagonal-architecture.md | markdown | 6.0 KB |
| references/resource-management.md | markdown | 4.0 KB |
references/resource-management.md
View on GitHub# Resource Management Patterns
## Defer Close Immediately
`defer Close()` MUST be called immediately after opening — NEVER delay. This prevents leaks when code is modified later and new return paths are added:
```go
// Good — defer is right next to open
f, err := os.Open(path)
if err != nil {
return err
}
defer f.Close()
// Bad — Close() is far from Open(), easy to forget when adding early returns
f, err := os.Open(path)
if err != nil {
return err
}
// ... 50 lines of code ...
f.Close() // might never run if a new return is added above
```
This applies to all closeable resources: files, SQL rows, HTTP response bodies, gzip readers, bufio scanners wrapping readers, etc.
```go
resp, err := http.Get(url)
if err != nil {
return err
}
defer resp.Body.Close()
rows, err := db.QueryContext(ctx, query)
if err != nil {
return err
}
defer rows.Close()
```
## `runtime.AddCleanup` over `runtime.SetFinalizer`
`runtime.AddCleanup` SHOULD be preferred over `runtime.SetFinalizer` (Go 1.24+):
```go
type Resource struct {
handle uintptr
}
func NewResource() *Resource {
r := &Resource{handle: acquireHandle()}
runtime.AddCleanup(r, func(handle uintptr) {
releaseHandle(handle)
}, r.handle)
return r
}
```
`AddCleanup` is preferred because:
- Multiple cleanups can be attached to the same object
- The cleanup function receives a copy of the value, not the object itself — no resurrection risk
- Cleanups run even if the object is part of a cycle
## Resource Pools
Resource pools SHOULD use channels with a fixed capacity for bounded allocation. Use channel-based pools or `sync.Pool` to manage limited resources between consumers. Always set a maximum size:
```go
type ConnPool struct {
conns chan *Conn
}
func NewConnPool(maxSize int, factory func() (*Conn, error)) (*ConnPool, error) {
pool := &ConnPool{
conns: make(chan *Conn, maxSize),
}
// Pre-fill with initial connections
for range maxSize {
conn, err := factory()
if err != nil {
return nil, fmt.Errorf("creating connection: %w", err)
}
pool.conns <- conn
}
return pool, nil
}
func (p *ConnPool) Get(ctx context.Context) (*Conn, error) {
select {
case conn := <-p.conns:
return conn, nil
case <-ctx.Done():
return nil, ctx.Err()
}
}
func (p *ConnPool) Put(conn *Conn) {
select {
case p.conns <- conn:
default:
conn.Close() // pool is full, discard
}
}
```
## Graceful Shutdown
Graceful shutdown MUST use `signal.NotifyContext` for clean termination. All resources (connections, files, channels) MUST be drained before process exit. Use `os/signal` and context cancellation:
```go
func main() {
ctx, stop := signal.NotifyContext(context.Background(),
syscall.SIGINT, syscall.SIGTERM,
)
defer stop()
srv := &http.Server{Addr: ":8080", Handler: router}
// Start server in background
go func() {
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
slog.Error("server error", "error", err)
}
}()
slog.Info("server started", "addr", ":8080")
// Wait for interrupt signal
<-ctx.Done()
slog.Info("shutting down...")
// Give outstanding requests time to complete
shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
slog.Error("shutdown error", "error", err)
}
// Close other resources: database connections, message queues, etc.
db.Close()
slog.Info("shutdown complete")
}
```
This pattern applies to any long-running service — gRPC servers, message consumers, background workers. The key elements are:
1. Capture OS signals with `signal.NotifyContext`
2. Start the server in a goroutine
3. Block on context cancellation
4. Shut down with a timeout to drain in-flight requests
5. Close all remaining resources in order
For goroutine shutdown patterns, see the `samber/cc-skills-golang@golang-concurrency` skill.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |