go-functional-options

The functional options pattern in Go replaces brittle positional parameters by using an unexported options struct, an Option interface with an unexported apply method, and With* constructors for each setting. This approach keeps required parameters positional while allowing optional settings to evolve safely.

Use functional options for Go API design when a constructor has three or more optional parameters or anticipates future growth. A config struct is simpler for fixed configurations, but functional options provide better extensibility and backward compatibility as your package interface evolves over time.

Maintain backward compatibility in Go constructors by setting default values in an unexported options struct before applying any functional options. This ensures existing calls remain valid when you introduce new With* helpers for optional settings like cache, logging, or metrics.

Prefer interface-based functional options over closures in Go for enhanced testability and introspection. While closures are common, using an Option interface with an unexported apply method allows you to validate and inspect the applied settings more effectively during testing.

Refactor a Go constructor with many toggles by extracting optional settings into an unexported options struct. Apply the functional options pattern by creating With* helpers for each toggle, keeping only required parameters positional, and ensuring defaults are set before options are applied.

The functional options pattern in Go is less suited for constructors with only one or two static parameters where a config struct would be simpler. It also requires strict adherence to setting defaults before applying options to avoid nil pointer issues or unexpected behavior when optional settings are omitted.