Functional Options Pattern

Source: Uber Go Style Guide

Functional options is a pattern where you declare an opaque Option type that records information in an internal struct. The constructor accepts a variadic number of these options and applies them to configure the result.

When to Use

Use functional options when:

• 3+ optional arguments on constructors or public APIs
• Extensible APIs that may gain new options over time
• Clean caller experience is important (no need to pass defaults)

The Pattern

Core Components

1. Unexported options struct - holds all configuration
2. Exported Option interface - with unexported apply method
3. Option types - implement the interface
4. With* constructors - create options

Option Interface

go
1type Option interface {
2    apply(*options)
3}

The unexported apply method ensures only options from this package can be used.

Complete Implementation

Source: Uber Go Style Guide

go
1package db
2
3import "go.uber.org/zap"
4
5// options holds all configuration for opening a connection.
6type options struct {
7    cache  bool
8    logger *zap.Logger
9}
10
11// Option configures how we open the connection.
12type Option interface {
13    apply(*options)
14}
15
16// cacheOption implements Option for cache setting (simple type alias).
17type cacheOption bool
18
19func (c cacheOption) apply(opts *options) {
20    opts.cache = bool(c)
21}
22
23// WithCache enables or disables caching.
24func WithCache(c bool) Option {
25    return cacheOption(c)
26}
27
28// loggerOption implements Option for logger setting (struct for pointers).
29type loggerOption struct {
30    Log *zap.Logger
31}
32
33func (l loggerOption) apply(opts *options) {
34    opts.logger = l.Log
35}
36
37// WithLogger sets the logger for the connection.
38func WithLogger(log *zap.Logger) Option {
39    return loggerOption{Log: log}
40}
41
42// Open creates a connection.
43func Open(addr string, opts ...Option) (*Connection, error) {
44    // Start with defaults
45    options := options{
46        cache:  defaultCache,
47        logger: zap.NewNop(),
48    }
49
50    // Apply all provided options
51    for _, o := range opts {
52        o.apply(&options)
53    }
54
55    // Use options.cache and options.logger...
56    return &Connection{}, nil
57}

Usage Examples

Source: Uber Go Style Guide

Without Functional Options (Bad)

go
1// Caller must always provide all parameters, even defaults
2db.Open(addr, db.DefaultCache, zap.NewNop())
3db.Open(addr, db.DefaultCache, log)
4db.Open(addr, false /* cache */, zap.NewNop())
5db.Open(addr, false /* cache */, log)

With Functional Options (Good)

go
1// Only provide options when needed
2db.Open(addr)
3db.Open(addr, db.WithLogger(log))
4db.Open(addr, db.WithCache(false))
5db.Open(
6    addr,
7    db.WithCache(false),
8    db.WithLogger(log),
9)

Comparison: Functional Options vs Config Struct

Prefer Config Struct when: Fewer than 3 options, options rarely change, all options usually specified together, or internal APIs only.

Why Not Closures?

Source: Uber Go Style Guide

An alternative implementation uses closures:

go
1// Closure approach (not recommended)
2type Option func(*options)
3
4func WithCache(c bool) Option {
5    return func(o *options) { o.cache = c }
6}

The interface approach is preferred because:

1. Testability - Options can be compared in tests and mocks
2. Debuggability - Options can implement fmt.Stringer
3. Flexibility - Options can implement additional interfaces
4. Visibility - Option types are visible in documentation

Quick Reference

go
1// 1. Unexported options struct with defaults
2type options struct {
3    field1 Type1
4    field2 Type2
5}
6
7// 2. Exported Option interface, unexported method
8type Option interface {
9    apply(*options)
10}
11
12// 3. Option type + apply + With* constructor
13type field1Option Type1
14
15func (o field1Option) apply(opts *options) { opts.field1 = Type1(o) }
16func WithField1(v Type1) Option            { return field1Option(v) }
17
18// 4. Constructor applies options over defaults
19func New(required string, opts ...Option) (*Thing, error) {
20    o := options{field1: defaultField1, field2: defaultField2}
21    for _, opt := range opts {
22        opt.apply(&o)
23    }
24    // ...
25}

Checklist

• options struct is unexported
• Option interface has unexported apply method
• Each option has a With* constructor
• Defaults are set before applying options
• Required parameters are separate from ...Option

See Also

• go-style-core - Core Go style principles
• go-naming - Naming conventions for Go
• go-defensive - Defensive programming patterns
• Self-referential functions and the design of options - Rob Pike
• Functional options for friendly APIs - Dave Cheney