go-patterns

Files (1)

• SKILL.md

SKILL.md (first lines)

# Go Patterns & Best Practices

> **Detailed patterns:** See `rules/go/patterns.md` for comprehensive examples.

## Error Handling

- **Always** check returned errors -- never discard with `_`
- Wrap errors with context: `fmt.Errorf("doing X: %w", err)`
- Use `errors.Is` / `errors.As` for comparison (works through wrapping)
- Define sentinel errors for expected, recoverable cases

```go
var ErrNotFound = errors.New("not found")

func GetUser(ctx context.Context, id string) (*User, error) {
    if err := row.Scan(&u.ID, &u.Name); err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, fmt.Errorf("get user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("get user %s: %w", id, err)
    }
    return &u, nil
}

// Caller checks with errors.Is
if errors.Is(err, ErrNotFound) { http.Error(w, "Not found", 404) }
```

### Custom Error Types
```go
type ValidationError struct { Field, Message string }
func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation error on %s: %s", e.Field, e.Message)
}
// Check with errors.As
var valErr *ValidationError
if errors.As(err, &valErr) { /* handle */ }
```

## Interfaces

- Define interfaces **at the consumer site**, not the producer
- Keep interfaces small: 1-3 methods (single responsibility)
- **Accept interfaces, return structs**

```go
// WRONG - large interface at producer
type UserService interface {
    GetUser(ctx context.Context, id string) (*User, error)
    CreateUser(ctx context.Context, u *User) error
    // ... more methods
}

// CORRECT - small interface at consumer
type UserGetter interface {
    GetUser(ctx context.Context, id string) (*User, error)
}

func NewHandler(users UserGetter) *Handler { return &Handler{users: users} }
```

## Concurrency

### Goroutines + Channels
```go
func processItems(ctx context.Context, items []Item) error {
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(10) // limit concurrent goroutines
    for _, item := range items {
        g.Go(func() error { return processOne(ctx, item) })
    }
    return g.Wait()
}
```

### Context for Cancellation
```go
func longOperation(ctx context.Context) error {
    for i := range 1000 {
        select {
        case <-ctx.Done(): return ctx.Err()
        default: if err := doStep(i); err != nil { return fmt.Errorf("step %d: %w", i, err) }
        }
    }
    return nil
}
// Caller: ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
```

### Worker Pool
```go
func workerPool(ctx context.Context, jobs <-chan Job, results chan<- Result, workers int) {
    var wg sync.WaitGroup
    for range workers {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                select {
                case <-ctx.Done(): return
                case results <- process(job):
                }
            }
        }()
    }
    wg.Wait(); close(results)
}
```

## Struct Design

### Functional Options Pattern
```go
type Server struct { addr string; readTimeout time.Duration; logger *slog.Logger }
type Option func(*Server)

func WithReadTimeout(d time.Duration) Option { return func(s *Server) { s.readTimeout = d } }
func WithLogger(l *slog.Logger) Option { return func(s *Server) { s.logger = l } }

From eroslifestyle/Claude-Orchestrator-Plugin, MIT.

More from eroslifestyle/Claude-Orchestrator-Plugin