go-functional-options

Functional Options

The functional options pattern lets a constructor stay backward compatible while accepting an open-ended set of optional settings. Callers pass only what differs from the defaults; new options never break old call sites.

Core Rules

1. Reach for functional options at 3+ optional parameters or whenever the API will grow.
2. The options struct is unexported. Only the package owns its shape.
3. The Option interface has an unexported apply method. No external package can forge an option.
4. Defaults go inside the constructor, before options are applied.
5. Required parameters stay positional; only the optional ones go through ...Option.
6. Prefer the interface form over closures — it composes better with testing, debugging, and fmt.Stringer.

When to Use What

Situation	Pattern
0–2 optional params, stable API	Plain positional or named args
Config that callers usually pass whole	Config struct
3+ optional params, growing API	Functional options
Mix of "must set together" + "rare overrides"	Config struct + small Option set

Read references/options-vs-struct.md when choosing between options and a plain config struct, or designing a hybrid.

The Canonical Pattern

package db

import "go.uber.org/zap"

// options is the package's private bag of settings.
type options struct {
    cache  bool
    logger *zap.Logger
}

// Option configures Open.
type Option interface {
    apply(*options)
}

// --- cacheOption -----------------------------------------------------------

type cacheOption bool

func (c cacheOption) apply(o *options) { o.cache = bool(c) }

// WithCache enables or disables the in-memory cache.
func WithCache(enabled bool) Option { return cacheOption(enabled) }

// --- loggerOption ----------------------------------------------------------

type loggerOption struct{ log *zap.Logger }

func (l loggerOption) apply(o *options) { o.logger = l.log }

// WithLogger sets the logger used by the connection.
func WithLogger(log *zap.Logger) Option { return loggerOption{log: log} }

// --- constructor -----------------------------------------------------------

// Open dials addr using the given options.
func Open(addr string, opts ...Option) (*Connection, error) {
    o := options{
        cache:  true,
        logger: zap.NewNop(),
    }
    for _, opt := range opts {
        opt.apply(&o)
    }
    // ... build the connection from o
    return &Connection{}, nil
}