Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-36k/skillsmp/go-idioms-1/SKILL.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill go-idioms-1. Copyright stays with the author (MIT).

Go Idioms

Idiomatic Go patterns and best practices for writing clean, maintainable Go code.

When This Skill MUST Be Used

ALWAYS invoke this skill when the user's request involves ANY of these:

• Creating or editing .go files
• Working with go.mod or Go project setup
• Questions about interface design or composition
• Error handling patterns and wrapping
• Context usage and propagation
• Naming conventions (packages, interfaces, getters)
• Logging with log/slog
• Decorator pattern implementation
• Performance optimization in Go

If you're about to write Go code, STOP and use this skill first.

Critical Safety Rules

NEVER:

• Store context.Context in structs
• Ignore errors (_, _ := ...)
• Use panic for expected errors
• Create interfaces with 10+ methods
• Use Get prefix for getters (user.GetName())

ALWAYS:

• Pass context.Context as first parameter
• Handle errors immediately after the call
• Define interfaces where they're used, not implemented
• Use small, focused interfaces (1-3 methods)
• Wrap errors with context using %w

Quick Reference

Interface Design

Small, Focused Interfaces

// GOOD: Small interface (1-3 methods)
type UserGetter interface {
    GetUser(ctx context.Context, id UserID) (*User, error)
}

// GOOD: Compose interfaces
type ReadWriter interface {
    Reader
    Writer
}

// BAD: Interface pollution (too many methods)
type UserService interface {
    GetUser(...)
    CreateUser(...)
    UpdateUser(...)
    DeleteUser(...)
    ListUsers(...)
    // ... 10 more methods
}

Accept Interfaces, Return Structs

// GOOD: Accept interface at usage site
func NewHandler(users UserGetter) *Handler {
    return &Handler{users: users}
}

// GOOD: Return concrete type
func NewUserRepository(db *sql.DB) *UserRepository {
    return &UserRepository{db: db}
}

Define Interfaces Where Used

// In handler package (consumer)
type UserGetter interface {
    GetUser(ctx context.Context, id UserID) (*User, error)
}

// Handler depends on interface, not concrete type
type Handler struct {
    users UserGetter
}

Naming Conventions

Avoid Stuttering

// BAD: Stuttering
user.UserID
order.OrderStatus

// GOOD: No stutter
user.ID
order.Status

Error Handling

Sentinel Errors

Define in errors.go per package:

var (
    ErrInvalidOrderID = errors.New("invalid order ID")
    ErrOrderNotFound  = errors.New("order not found")
)

Wrap with Context

Always wrap errors with %w:

result, err := doSomething()
if err != nil {
    return fmt.Errorf("failed to do something: %w", err)
}

Add context at each layer:

• Repository: "query order by id: %w"
• Application: "complete order %d: %w"
• Handler: "handle complete request: %w"

Check Errors Properly

// Use errors.Is() for sentinel errors
if errors.Is(err, ErrOrderNotFound) {
    return nil, status.NotFound
}

// Use errors.As() for type assertions
var validationErr *ValidationError
if errors.As(err, &validationErr) {
    return nil, validationErr.Fields
}

Layer Patterns

Infrastructure Translation:

// MySQL repository
if errors.Is(err, sql.ErrNoRows) {
    return nil, domain.ErrOrderNotFound
}

// External API client
if resp.StatusCode == 404 {
    return nil, domain.ErrResourceNotFound
}

Context

Always First Parameter

func (s *Service) Process(ctx context.Context, req Request) (Result, error)

Never Store in Structs

// BAD: Context in struct
type Service struct {
    ctx context.Context  // NEVER do this
}

// GOOD: Pass through methods
func (s *Service) Do(ctx context.Context) error {
    return s.repo.Save(ctx, s.data)
}

Use for Cancellation, Timeouts, Request-Scoped Values

ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

resp, err := client.Do(req.WithContext(ctx))

Logging

Use log/slog

Always use standard library log/slog for structured logging.

logger.InfoContext(ctx, "Order completed", "order_id", orderID)

Log Levels

Field Naming

• Use snake_case: order_id, user_id, external_id
• Suffix with _id for identifiers
• Suffix with _ms for milliseconds

Anti-Patterns

• Don't log sensitive data (passwords, tokens)
• Don't log in domain layer (pure business logic)
• Don't use printf-style formatting
• Don't log expected errors at Error level

Decorator Pattern

Core Principle

Constructors accept interfaces, return concrete types.

type Service interface {
    Do(ctx context.Context, input Data) (Result, error)
}

// Decorator wraps interface, returns concrete
func NewLoggedService(svc Service, logger Logger) *LoggedService {
    return &LoggedService{service: svc, logger: logger}
}

Composition Chain

Build functionality by stacking decorators:

// Core implementation
core := NewCoreService(repo)

// Add cross-cutting concerns
logged := NewLoggedService(core, logger)
metered := NewMeteredService(logged, metrics)
cached := NewCachedService(metered, cache)

// Use the fully decorated service
handler := NewHandler(cached)

Order matters: Outermost decorator executes first.

Common Decorator Use Cases

Implementation Pattern

type LoggedService struct {
    next   Service  // The wrapped service
    logger Logger
}

func NewLoggedService(next Service, logger Logger) *LoggedService {
    return &LoggedService{next: next, logger: logger}
}

func (s *LoggedService) Do(ctx context.Context, input Data) (Result, error) {
    s.logger.Info("service.Do called", "input", input)
    
    result, err := s.next.Do(ctx, input)
    
    if err != nil {
        s.logger.Error("service.Do failed", "error", err)
    }
    return result, err
}

Zero Values

Design types so zero value is useful:

var buf bytes.Buffer  // Ready to use, no initialization needed
buf.WriteString("hello")

Use zero to indicate "use default":

type Config struct {
    Timeout time.Duration  // Zero means use default
}

func (c *Config) GetTimeout() time.Duration {
    if c.Timeout == 0 {
        return 30 * time.Second  // Default
    }
    return c.Timeout
}

Performance Patterns

// Preallocate slices when size is known
results := make([]Result, 0, len(items))

// Use strings.Builder for concatenation
var b strings.Builder
b.WriteString("hello")
b.WriteString(" world")

Composition Over Inheritance

Use embedding to share behavior:

type LoggedService struct {
    Service  // Embedded interface
    logger   Logger
}

Prefer composition for flexibility:

type Handler struct {
    users  UserRepository
    orders OrderRepository
    logger Logger
}

Concurrency

"Don't communicate by sharing memory; share memory by communicating."

• Use channels for coordination
• Use sync primitives only when channels don't fit

// GOOD: Channel for coordination
results := make(chan Result)
go func() {
    results <- doWork()
}()

// Use sync.Mutex when channels don't fit
type Counter struct {
    mu    sync.Mutex
    value int
}

Anti-Patterns

Troubleshooting

Example Requests