If you’ve spent much time writing code in Go, you’ve probably come across the functional options pattern. Go doesn’t have named/default arguments and this can sometimes make it difficult to wrap up initialisation logic in a clean way.

The functional options pattern works around this limitation by allowing the caller to pass in a series of functions that modify the object being initialised. This pattern is used commonly in many popular Go libraries such as GRPC and the GCP SDK. However, functional options can be quite a controversial topic in the Go community - Loved by some and hated by others. You’ll notice that the linked packages do not use the typical “function type” approach to functional options. Instead, they use interfaces. This post explains why this is a good idea and how you can use it in your own code.

Function types

Let’s start by briefly recapping the most commonly used approach for applying functional options in Go. First, we start we defining a type that we want to be able to configure using functional options. In this example, we’ll create a basic Server.

type Server struct {
	addr string
}

Next, we define a function type that takes a pointer to the Server as an argument. This means that any function of this type is able to modify the Server in some way.

type ServerOption func(*Server)

Now we can define a series of functions that take arbitrary values and return a ServerOption function that will apply those values to the Server.

func WithAddr(addr string) ServerOption {
	return func(s *Server) {
		s.addr = addr
	}
}

Finally, we can create a NewServer function that takes a series of ServerOption functions using the variadic operator (...) and applies them to a new Server.

func NewServer(opts ...ServerOption) *Server {
	// create a new server with default values
	s := &Server{
		addr: "0.0.0.0",
	}
	// apply the functional options
	for _, opt := range opts {
		opt(s)
	}
	return s
}

When should you use functional options?

This pattern has been written about at length in the Go community and is widely used, so we won’t spend any more time looking at the code. However, functional options aren’t necessarily the best choice for every situation, so it’s worth spending some time thinking about when you should use them.

Let’s start by looking at some of the positives:

• The use of variadic arguments means that you are able to add new options without changing your function signatures. This gives package authors a bit more flexibility when adding new features to their code.
• It’s easy to apply defaults to your structures and only override the values that you need to.
• It’s very readable from the caller’s perspective. The caller can see exactly what options are being applied to the object and in what order. You can even call an option multiple times if you need to (for example, to add multiple items to a collection type).

If these are things that you value in your API design, then functional options might be a good fit for you. However, you should also be aware of some of the drawbacks of this pattern:

• While widely used, the pattern can be a bit confusing to new programmers or those who are moving to Go from another language with optional arguments. The solution to this is simply good documentation and clear examples. Make sure your function options have good names and are documented using docstrings.
• Struct are a very commonly used primitive in Go and most of the time functional options are not needed. If you only have a few fields that need setting, it’s probably easier to just use a constructor function with named arguments or define the struct directly.
• If you have multiple structs that use the functional options pattern in the same package, you may run into naming conflicts.
• It can be hard to discover the available options for a given struct or once discovered to tell which functional options are intended for which struct as they are namespaces at the package level rather than per struct. More on this later.

Interface types

Interfaces are a core and powerful part of the Go language. They allow you to define a set of methods that a type must implement. So what if we used interface types to define our functional options instead of function types? Let’s start by rewriting the ServerOption type:

type ServerOption interface {
	applyToServer(*Server)
}

The interface type has a single method (applyToServer) that has the same function signature as our previous function type. This means that any functional options that we define must now be a type with a method matching this function signature rather than a plain function. For example, our WithAddr functional option can now be rewritten as:

type addrOption struct {
	addr string
}

func (o *addrOption) applyToServer(s *Server) {
	s.addr = o.addr
}

func WithAddr(addr string) ServerOption {
	return &addrOption{addr}
}

This approach is a little more verbose than the function type approach, but it has some distinct advantages. Firstly, it’s easier to discover the available options for a given struct. Most IDEs will allow you to discover implementations of an interface, so you can quickly see all the options that are available for a given struct.

Additionally, you can now define functional options that can be applied to multiple structs! This solves the problem of naming conflicts that we mentioned earlier. For this example, we can now define a second struct, Client that also has an addr field that needs setting via a functional option:

type Client struct {
	addr string
}

type ClientOption interface {
	applyToClient(*Client)
}

When using function types, we would have to define a new set of functional options for the Client struct and if they were in the same package, we would have to have unique names for each (e.g. WithServerAddr and WithClientAddr). This gets messy quickly.

However, with the interface types, we can define a functional option that implements both ServerOption and ClientOption:

type Option interface {
	ServerOption
	ClientOption
}

type addrOption struct {
	addr string
}

func (o *addrOption) applyToServer(s *Server) {
	s.addr = o.addr
}

func (o *addrOption) applyToClient(c *Client) {
	c.addr = o.addr
}

func WithAddr(addr string) Option {
	return &addrOption{addr}
}

Note that we had to create a new interface type Option that embeds both ServerOption and ClientOption. This allows us to define a single functional option that can be applied to both the Server and Client structs.

Now we can adjust our NewServer and NewClient functions to accept a these new interface types:

func NewServer(opts ...ServerOption) *Server {
	// create a new server with default values
	s := &Server{
		addr: "0.0.0.0",
	}
	// apply the functional options
	for _, opt := range opts {
		opt.applyToServer(s)
	}
	return s
}

func NewClient(opts ...ClientOption) *Client {
	// create a new client with default values
	c := &Client{
		addr: "0.0.0.0",
	}
	// apply the functional options
	for _, opt := range opts {
		opt.applyToClient(c)
	}
	return c
}

Summary

If you don’t mind the extra boilerplate, then functional options are much more flexible when using interfaces than function types. They help you to avoid naming conflict, allow you to define options that can be applied to multiple structs and make it easier to discover the available options for a given struct.

It surprises me that this approach isn’t more widely discussed in the community. Almost all articles and guides discussing functional options use function types rather than interfaces. Hopefully, someone reading this will find it useful and consider using interfaces in their own code next time they want to use the function options pattern.

You can find a complete example of the final code from this post below:

Complete example

This is also available to run on the Go playground.

package main

import "fmt"

type (
	Server struct {
		addr string
	}
	ServerOption interface {
		applyToServer(*Server)
	}
	Client struct {
		addr string
	}
	ClientOption interface {
		applyToClient(*Client)
	}
	Option interface {
		ServerOption
		ClientOption
	}
)

type addrOption struct {
	addr string
}

func (o *addrOption) applyToServer(s *Server) {
	s.addr = o.addr
}

func (o *addrOption) applyToClient(c *Client) {
	c.addr = o.addr
}

func WithAddr(addr string) Option {
	return &addrOption{addr}
}

func NewServer(opts ...ServerOption) *Server {
	// create a new server with default values
	s := &Server{
		addr: "0.0.0.0",
	}
	// apply the functional options
	for _, opt := range opts {
		opt.applyToServer(s)
	}
	return s
}

func (s *Server) Start() {
	fmt.Printf("Starting server on %s\n", s.addr)
}

func NewClient(opts ...ClientOption) *Client {
	// create a new client with default values
	c := &Client{
		addr: "0.0.0.0",
	}
	// apply the functional options
	for _, opt := range opts {
		opt.applyToClient(c)
	}
	return c
}

func (c *Client) Start() {
	fmt.Printf("Starting client with connection to %s\n", c.addr)
}

func main() {
	NewServer(WithAddr("127.0.0.1")).Start()
	NewClient(WithAddr("127.0.0.1")).Start()
}