Functional Options Pattern in Go

In software development, flexibility in configuring objects is a common need, especially when dealing with functions and structures with multiple optional parameters.

In Go, as it doesn’t support function overloading, finding an elegant solution to this problem can be challenging. This is where the Functional Options Pattern comes in as an effective and idiomatic approach.

What is the Functional Options Pattern?

The Functional Options Pattern is a design pattern widely used in Go to facilitate the configuration of complex structures or functions, especially when there are multiple optional parameters. It allows you to build objects or configure functions flexibly by using functions that act as “options.”

Instead of directly passing all parameters to a constructor or function, you create separate functions that apply incremental and optional configurations. This approach helps to avoid functions with long lists of parameters or the need for multiple constructors for different use cases.

Applying it in Practice

Let’s consider a common problem in API development: creating a custom HTTP client, where some configurations (like timeout, headers, and retries) are optional. Without the Functional Options Pattern, you would need to pass all possible parameters to the creation function, resulting in less readable and harder-to-maintain code.

Creating an HTTP Client with Optional Settings

Suppose we want to create an HTTP client that allows us to set an optional timeout, custom header*, and the number of retries (reconnection attempts). The traditional solution without the Functional Options Pattern would look something like this:

type HttpClient struct {
    Timeout time.Duration
    Headers map[string]string
    Retries int
}

func NewHttpClient(timeout time.Duration, headers map[string]string, retries int) *HttpClient {
    return &HttpClient{
        Timeout: timeout,
        Headers: headers,
        Retries: retries,
    }
}

If you don’t want to set all parameters, you would still need to pass default or zero values, which could cause confusion and hinder readability.

Now, let’s look at how to apply the Functional Options Pattern to improve this approach.

Implementing the Functional Options Pattern

Here, we’ll use functions that encapsulate options, allowing you to configure only the parameters you really need.

type HttpClient struct {
    Timeout time.Duration
    Headers map[string]string
    Retries int
}

// Option defines the function type that will apply settings to HttpClient
type Option func(*HttpClient)

// NewHttpClient creates an HttpClient instance with functional options
func NewHttpClient(opts ...Option) *HttpClient {
    client := &HttpClient{
        Timeout: 30 * time.Second, // default value
        Headers: make(map[string]string),
        Retries: 3, // default value
    }

    // Apply the provided options
    for _, opt := range opts {
        opt(client)
    }

    return client
}

// WithTimeout allows you to set the client timeout
func WithTimeout(timeout time.Duration) Option {
    return func(c *HttpClient) {
        c.Timeout = timeout
    }
}

// WithHeaders allows you to add custom headers
func WithHeaders(headers map[string]string) Option {
    return func(c *HttpClient) {
        for k, v := range headers {
            c.Headers[k] = v
        }
    }
}

// WithRetries allows you to set the number of reconnection attempts
func WithRetries(retries int) Option {
    return func(c *HttpClient) {
        c.Retries = retries
    }
}

Now, when creating a new HTTP client, you can specify only the options you want:

func main() {
    client := NewHttpClient(
        WithTimeout(10*time.Second),
        WithHeaders(map[string]string{"Authorization": "Bearer token"}),
    )

    fmt.Printf("Timeout: %v, Headers: %v, Retries: %d\n", client.Timeout, client.Headers, client.Retries)
}

This allows flexibility and clarity in configuring the client without needing to pass all parameters every time.

Packages that Use this Pattern

Many popular packages in the Go ecosystem use the Functional Options Pattern. Notable examples include:

• grpc-go: Go’s package for gRPC uses functional options to configure gRPC servers and clients.

• zap: The popular high-performance logger uses this pattern to configure multiple logging options, such as log level, output format, and more.

Conclusion

The Functional Options Pattern is a powerful and idiomatic solution in Go for handling functions or structures that require flexible configuration. By adopting this pattern, you enhance code readability, provide flexibility for end-users, and avoid the proliferation of functions with extensive parameter lists.

Whether creating a custom HTTP client or configuring a complex library, the Functional Options Pattern is a valuable tool for designing APIs in Go.