Go函数式选项模式详解：Uber风格指南、实现示例与最佳实践

go-functional-options by cxuu/golang-skills

234 周安装量

56 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/cxuu/golang-skills --skill go-functional-options

函数式编程 Go 代码规范

🇨🇳中文介绍

函数式选项模式

来源 : Uber Go 风格指南

函数式选项是一种模式，您声明一个不透明的 Option 类型，该类型在内部结构体中记录信息。构造函数接受可变数量的这些选项，并应用它们来配置结果。

何时使用

在以下情况使用函数式选项：

构造函数或公共 API 有 3 个或更多可选参数
可扩展的 API，可能随着时间的推移增加新的选项
简洁的调用者体验 很重要（无需传递默认值）

模式

核心组件

未导出的 options 结构体 - 保存所有配置
导出的 Option 接口 - 带有未导出的 apply 方法
选项类型 - 实现该接口
With* 构造函数 - 创建选项

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

不使用函数式选项（不佳）

// 调用者必须始终提供所有参数，即使是默认值
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)

使用函数式选项（良好）

// 仅在需要时提供选项
db.Open(addr)
db.Open(addr, db.WithLogger(log))
db.Open(addr, db.WithCache(false))
db.Open(
    addr,
    db.WithCache(false),
    db.WithLogger(log),
)

比较：函数式选项 vs 配置结构体

方面	函数式选项	配置结构体
可扩展性	添加新的 `With*` 函数	添加新字段（可能破坏兼容性）
默认值	内置在构造函数中	零值或单独的默认值
调用者体验	仅指定不同的部分	必须构造整个结构体
可测试性	选项可比较	结构体比较
复杂性	更多样板代码	设置更简单

在以下情况首选配置结构体：少于 3 个选项，选项很少更改，所有选项通常一起指定，或者仅用于内部 API。

为什么不使用闭包？

来源 : Uber Go 风格指南

另一种实现使用闭包：

// 闭包方法（不推荐）
type Option func(*options)

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

首选接口方法，因为：

可测试性 - 选项可以在测试和模拟中进行比较
可调试性 - 选项可以实现 fmt.Stringer
灵活性 - 选项可以实现额外的接口
可见性 - 选项类型在文档中是可见的

// 1. 带有默认值的未导出 options 结构体
type options struct {
    field1 Type1
    field2 Type2
}

// 2. 导出的 Option 接口，未导出的方法
type Option interface {
    apply(*options)
}

// 3. 选项类型 + 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 分开

go-style-core - 核心 Go 风格原则
go-naming - Go 命名约定
go-defensive - 防御性编程模式
自引用函数与选项设计 - Rob Pike
友好 API 的函数式选项 - Dave Cheney

🇺🇸English

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

Unexportedoptions struct - holds all configuration
ExportedOption interface - with unexported apply method
Option types - implement the interface
With* constructors - create options

Option Interface

type Option interface {
    apply(*options)
}

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

Complete Implementation

Source : Uber Go Style Guide

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
}

Usage Examples

Source : Uber Go Style Guide

Without Functional Options (Bad)

// Caller must always provide all parameters, even defaults
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)

With Functional Options (Good)

// Only provide options when needed
db.Open(addr)
db.Open(addr, db.WithLogger(log))
db.Open(addr, db.WithCache(false))
db.Open(
    addr,
    db.WithCache(false),
    db.WithLogger(log),
)

Comparison: Functional Options vs Config Struct

Aspect	Functional Options	Config Struct
Extensibility	Add new `With*` functions	Add new fields (may break)
Defaults	Built into constructor	Zero values or separate defaults
Caller experience	Only specify what differs	Must construct entire struct
Testability	Options are comparable	Struct comparison
Complexity	More boilerplate	Simpler setup

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:

// Closure approach (not recommended)
type Option func(*options)

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

The interface approach is preferred because:

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

Quick Reference

// 1. Unexported options struct with defaults
type options struct {
    field1 Type1
    field2 Type2
}

// 2. Exported Option interface, unexported method
type Option interface {
    apply(*options)
}

// 3. Option type + apply + With* constructor
type field1Option Type1

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

// 4. Constructor applies options over defaults
func New(required string, opts ...Option) (*Thing, error) {
    o := options{field1: defaultField1, field2: defaultField2}
    for _, opt := range opts {
        opt.apply(&o)
    }
    // ...
}

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

Go函数式选项模式详解：Uber风格指南、实现示例与最佳实践

🇨🇳中文介绍

函数式选项模式

何时使用

模式

核心组件

相关 Skills

选项接口

完整实现

使用示例

不使用函数式选项（不佳）

使用函数式选项（良好）

比较：函数式选项 vs 配置结构体

为什么不使用闭包？

快速参考

检查清单

另请参阅

🇺🇸English

Functional Options Pattern

When to Use

The Pattern

Core Components

Option Interface

Complete Implementation

Usage Examples

Without Functional Options (Bad)

With Functional Options (Good)

Comparison: Functional Options vs Config Struct

Why Not Closures?

Quick Reference

Checklist

See Also

最新 Skills