1---
2name: golang-patterns
3description: >
4  Go-specific design patterns and best practices including functional options,
5  small interfaces, dependency injection, concurrency patterns, error handling,
6  and package organization. Use when working with Go code to apply idiomatic
7  Go patterns.
8metadata:
9  origin: ECC
10  globs: ["**/*.go", "**/go.mod", "**/go.sum"]
11---
12 
13# Go Patterns
14 
15> This skill provides comprehensive Go patterns extending common design principles with Go-specific idioms.
16 
17## Functional Options
18 
19Use the functional options pattern for flexible constructor configuration:
20 
21```go
22type Option func(*Server)
23 
24func WithPort(port int) Option {
25    return func(s *Server) { s.port = port }
26}
27 
28func NewServer(opts ...Option) *Server {
29    s := &Server{port: 8080}
30    for _, opt := range opts {
31        opt(s)
32    }
33    return s
34}
35```
36 
37**Benefits:**
38- Backward compatible API evolution
39- Optional parameters with defaults
40- Self-documenting configuration
41 
42## Small Interfaces
43 
44Define interfaces where they are used, not where they are implemented.
45 
46**Principle:** Accept interfaces, return structs
47 
48```go
49// Good: Small, focused interface defined at point of use
50type UserStore interface {
51    GetUser(id string) (*User, error)
52}
53 
54func ProcessUser(store UserStore, id string) error {
55    user, err := store.GetUser(id)
56    // ...
57}
58```
59 
60**Benefits:**
61- Easier testing and mocking
62- Loose coupling
63- Clear dependencies
64 
65## Dependency Injection
66 
67Use constructor functions to inject dependencies:
68 
69```go
70func NewUserService(repo UserRepository, logger Logger) *UserService {
71    return &UserService{
72        repo:   repo,
73        logger: logger,
74    }
75}
76```
77 
78**Pattern:**
79- Constructor functions (New* prefix)
80- Explicit dependencies as parameters
81- Return concrete types
82- Validate dependencies in constructor
83 
84## Concurrency Patterns
85 
86### Worker Pool
87 
88```go
89func workerPool(jobs <-chan Job, results chan<- Result, workers int) {
90    var wg sync.WaitGroup
91    for i := 0; i < workers; i++ {
92        wg.Add(1)
93        go func() {
94            defer wg.Done()
95            for job := range jobs {
96                results <- processJob(job)
97            }
98        }()
99    }
100    wg.Wait()
101    close(results)
102}
103```
104 
105### Context Propagation
106 
107Always pass context as first parameter:
108 
109```go
110func FetchUser(ctx context.Context, id string) (*User, error) {
111    // Check context cancellation
112    select {
113    case <-ctx.Done():
114        return nil, ctx.Err()
115    default:
116    }
117    // ... fetch logic
118}
119```
120 
121## Error Handling
122 
123### Error Wrapping
124 
125```go
126if err != nil {
127    return fmt.Errorf("failed to fetch user %s: %w", id, err)
128}
129```
130 
131### Custom Errors
132 
133```go
134type ValidationError struct {
135    Field string
136    Msg   string
137}
138 
139func (e *ValidationError) Error() string {
140    return fmt.Sprintf("%s: %s", e.Field, e.Msg)
141}
142```
143 
144### Sentinel Errors
145 
146```go
147var (
148    ErrNotFound = errors.New("not found")
149    ErrInvalid  = errors.New("invalid input")
150)
151 
152// Check with errors.Is
153if errors.Is(err, ErrNotFound) {
154    // handle not found
155}
156```
157 
158## Package Organization
159 
160### Structure
161 
162```
163project/
164├── cmd/              # Main applications
165│   └── server/
166│       └── main.go
167├── internal/         # Private application code
168│   ├── domain/       # Business logic
169│   ├── handler/      # HTTP handlers
170│   └── repository/   # Data access
171└── pkg/              # Public libraries
172```
173 
174### Naming Conventions
175 
176- Package names: lowercase, single word
177- Avoid stutter: `user.User` not `user.UserModel`
178- Use `internal/` for private code
179- Keep `main` package minimal
180 
181## Testing Patterns
182 
183### Table-Driven Tests
184 
185```go
186func TestValidate(t *testing.T) {
187    tests := []struct {
188        name    string
189        input   string
190        wantErr bool
191    }{
192        {"valid", "[email protected]", false},
193        {"invalid", "not-an-email", true},
194    }
195 
196    for _, tt := range tests {
197        t.Run(tt.name, func(t *testing.T) {
198            err := Validate(tt.input)
199            if (err != nil) != tt.wantErr {
200                t.Errorf("got error %v, wantErr %v", err, tt.wantErr)
201            }
202        })
203    }
204}
205```
206 
207### Test Helpers
208 
209```go
210func testDB(t *testing.T) *sql.DB {
211    t.Helper()
212    db, err := sql.Open("sqlite3", ":memory:")
213    if err != nil {
214        t.Fatalf("failed to open test db: %v", err)
215    }
216    t.Cleanup(func() { db.Close() })
217    return db
218}
219```
220 
221## When to Use This Skill
222 
223- Designing Go APIs and packages
224- Implementing concurrent systems
225- Structuring Go projects
226- Writing idiomatic Go code
227- Refactoring Go codebases
228