interface-embedding

Compose interfaces through embedding for flexible contracts

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025

When & Why to Use This Skill

This Claude skill provides comprehensive guidance on Go interface embedding patterns, enabling developers to compose flexible and maintainable software contracts. By emphasizing composition over inheritance, it helps engineers create modular, decoupled code through small, focused interfaces and progressive enhancement techniques, which are essential for scalable Go applications.

Use Cases

  • Refactoring monolithic interfaces: Breaking down 'kitchen sink' interfaces into smaller, reusable components like Reader and Closer to improve code maintainability.
  • Implementing Progressive Enhancement: Creating an ExpiringCache that embeds a BasicCache, allowing functions to accept basic versions while providing advanced TTL features where supported.
  • Optional Behavior Detection: Using type assertions with embedded interfaces to detect specialized capabilities, such as switching from individual processing to optimized batch processing at runtime.
  • Standard Library Integration: Composing custom interfaces with standard Go packages (e.g., io, net/http) to maintain idiomatic code structures and compatibility.
nameinterface-embedding
descriptionCompose interfaces through embedding for flexible contracts

Interface Embedding Patterns

Go interfaces can embed other interfaces to create larger contracts. Use this for composition, not inheritance.

Basic Embedding

CORRECT - Compose small interfaces

type Reader interface {
    Read(p []byte) (n int, err error)
}

type Closer interface {
    Close() error
}

type ReadCloser interface {
    Reader
    Closer
}

// Any type implementing both Reader and Closer satisfies ReadCloser

WRONG - Giant interface instead of composition

type FileHandler interface {
    Read(p []byte) (n int, err error)
    Write(p []byte) (n int, err error)
    Close() error
    Seek(offset int64, whence int) (int64, error)
    // Kitchen sink approach
}

Practical Patterns

Progressive enhancement:

type BasicCache interface {
    Get(key string) ([]byte, error)
    Set(key string, val []byte) error
}

type ExpiringCache interface {
    BasicCache
    SetWithTTL(key string, val []byte, ttl time.Duration) error
}

func UseCache(c BasicCache) { /* Works with any cache */ }
func UseAdvanced(c ExpiringCache) { /* Needs TTL support */ }

Optional behavior detection:

type Processor interface {
    Process(data []byte) error
}

type BatchProcessor interface {
    Processor
    ProcessBatch(items [][]byte) error
}

func Handle(p Processor, items [][]byte) error {
    if bp, ok := p.(BatchProcessor); ok {
        return bp.ProcessBatch(items) // Use batch if available
    }
    // Fallback to individual processing
    for _, item := range items {
        if err := p.Process(item); err != nil {
            return err
        }
    }
    return nil
}

Guidelines

  • Embed to compose small, focused interfaces
  • Keep embedded interfaces from stdlib or well-known packages
  • Use type assertions to detect optional capabilities
  • Avoid deep embedding hierarchies (2-3 levels max)