Functional Options パターン

Functional options は、不透明な Option 型を宣言し、内部構造体に情報を記録するパターンです。コンストラクタは可変長個数のこれらのオプションを受け取り、結果を設定するために適用します。

使用する時機

以下の場合に functional options を使用してください:

• 3 個以上のオプション引数 がコンストラクタまたは公開 API にある
• 拡張可能な API が時間とともに新しいオプションを得る可能性がある
• 呼び出し側のエクスペリエンス が重要 (デフォルト値を渡す必要がない)

パターン

コア コンポーネント

1. エクスポートされていない options 構造体 - すべての設定を保持
2. エクスポートされた Option インターフェース - エクスポートされていない apply メソッド付き
3. Option 型 - インターフェースを実装
4. With* コンストラクタ - オプションを作成

Option インターフェース

type Option interface {
    apply(*options)
}

エクスポートされていない apply メソッドは、このパッケージからのオプションのみが使用できることを保証します。

完全な実装

package db

import "go.uber.org/zap"

// options holds all configuration for opening a connection.
type options struct {
    cache  bool
    logger *zap.Logger
}

// Option configures how we open the connection.
type Option interface {
    apply(*options)
}

// cacheOption implements Option for cache setting (simple type alias).
type cacheOption bool

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

// WithCache enables or disables caching.
func WithCache(c bool) Option {
    return cacheOption(c)
}

// loggerOption implements Option for logger setting (struct for pointers).
type loggerOption struct {
    Log *zap.Logger
}

func (l loggerOption) apply(opts *options) {
    opts.logger = l.Log
}

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

// Open creates a connection.
func Open(addr string, opts ...Option) (*Connection, error) {
    // Start with defaults
    options := options{
        cache:  defaultCache,
        logger: zap.NewNop(),
    }

    // Apply all provided options
    for _, o := range opts {
        o.apply(&options)
    }

    // Use options.cache and options.logger...
    return &Connection{}, nil
}

使用例

Functional Options なし (悪い例)

// 呼び出し側は常にすべてのパラメータを提供する必要があり、デフォルト値も含まれます
db.Open(addr, db.DefaultCache, zap.NewNop())
db.Open(addr, db.DefaultCache, log)
db.Open(addr, false /* cache */, zap.NewNop())
db.Open(addr, false /* cache */, log)

Functional Options 付き (良い例)

// 必要な場合のみオプションを指定
db.Open(addr)
db.Open(addr, db.WithLogger(log))
db.Open(addr, db.WithCache(false))
db.Open(
    addr,
    db.WithCache(false),
    db.WithLogger(log),
)

比較: Functional Options と設定構造体

側面	Functional Options	設定構造体
拡張性	新しい With* 関数を追加	新しいフィールドを追加 (破壊的変更の可能性)
デフォルト値	コンストラクタに組み込み	ゼロ値または別のデフォルト値
呼び出し側のエクスペリエンス	異なる部分のみを指定	構造体全体を構築する必要がある
テスト可能性	オプションは比較可能	構造体の比較
複雑性	より多くのボイラープレート	より単純なセットアップ

設定構造体を使用する方が好ましい場合: オプションが 3 個未満、オプションがめったに変わらない、すべてのオプションが通常一緒に指定される、または内部 API のみの場合。

関数型オプションと設定構造体の選択、適切なデフォルト値を持つ設定構造体 API の設計、または複雑なコンストラクタのハイブリッドアプローチの評価を決定する際は、references/OPTIONS-VS-STRUCTS.md をお読みください。

クロージャを使わない理由

別の実装方法はクロージャを使用します:

// クロージャアプローチ (推奨されません)
type Option func(*options)

func WithCache(c bool) Option {
    return func(o *options) { o.cache = c }
}

インターフェースアプローチが推奨される理由:

1. テスト可能性 - オプションはテストやモックで比較できます
2. デバッグ可能性 - オプションは fmt.Stringer を実装できます
3. 柔軟性 - オプションは追加のインターフェースを実装できます
4. 可視性 - Option 型はドキュメンテーションで可視化されます

クイックリファレンス

// 1. デフォルト値を持つエクスポートされていない options 構造体
type options struct {
    field1 Type1
    field2 Type2
}

// 2. エクスポートされた Option インターフェース、エクスポートされていないメソッド
type Option interface {
    apply(*options)
}

// 3. Option 型 + apply + With* コンストラクタ
type field1Option Type1

func (o field1Option) apply(opts *options) { opts.field1 = Type1(o) }
func WithField1(v Type1) Option            { return field1Option(v) }

// 4. コンストラクタはデフォルト値の上にオプションを適用
func New(required string, opts ...Option) (*Thing, error) {
    o := options{field1: defaultField1, field2: defaultField2}
    for _, opt := range opts {
        opt.apply(&o)
    }
    // ...
}

チェックリスト

• options 構造体はエクスポートされていない
• Option インターフェースはエクスポートされていない apply メソッドを持つ
• 各オプションは With* コンストラクタを持つ
• デフォルト値はオプションを適用する前に設定される
• 必須パラメータは ...Option から分離されている

関連スキル

• インターフェース設計: Option インターフェースを設計する場合、またはインターフェースとクロージャアプローチの間で選択する場合は、go-interfaces を参照してください
• 命名規則: With* コンストラクタ、オプション型、またはエクスポートされていない options 構造体に名前を付ける場合は、go-naming を参照してください
• 関数設計: ファイル内でコンストラクタを整理したり、可変長シグネチャをフォーマットしたりする場合は、go-functions を参照してください
• ドキュメンテーション: Option 型、With* 関数、またはコンストラクタの動作を文書化する場合は、go-documentation を参照してください

外部リソース

• Self-referential functions and the design of options - Rob Pike
• Functional options for friendly APIs - Dave Cheney