Functional Options

Functional options is a pattern in which you declare an opaque Option typethat records information in some internal struct. You accept a variadic numberof these options and act upon the full information recorded by the options onthe internal struct.

Use this pattern for optional arguments in constructors and other public APIsthat you foresee needing to expand, especially if you already have three ormore arguments on those functions.

BadGood
  1. // package db
  2.  
  3. func Connect(
  4.   addr string,
  5.   timeout time.Duration,
  6.   caching bool,
  7. ) (Connection, error) {
  8.   // …
  9. }
  11. // Timeout and caching must always be provided,
  12. // even if the user wants to use the default.
  14. db.Connect(addr, db.DefaultTimeout, db.DefaultCaching)
  15. db.Connect(addr, newTimeout, db.DefaultCaching)
  16. db.Connect(addr, db.DefaultTimeout, false / caching /)
  17. db.Connect(addr, newTimeout, false / caching /)
 
  1. type options struct {
  2.   timeout time.Duration
  3.   caching bool
  4. }
  5.  
  6. // Option overrides behavior of Connect.
  7. type Option interface {
  8.   apply(options)
  9. }
  10.  
  11. type optionFunc func(options)
  13. func (f optionFunc) apply(o options) {
  14.   f(o)
  15. }
  16.  
  17. func WithTimeout(t time.Duration) Option {
  18.   return optionFunc(func(o options) {
  19.     o.timeout = t
  20.   })
  21. }
  23. func WithCaching(cache bool) Option {
  24.   return optionFunc(func(o options) {
  25.     o.caching = cache
  26.   })
  27. }
  28.  
  29. // Connect creates a connection.
  30. func Connect(
  31.   addr string,
  32.   opts …Option,
  33. ) (*Connection, error) {
  34.   options := options{
  35.     timeout: defaultTimeout,
  36.     caching: defaultCaching,
  37.   }
  38.  
  39.   for _, o := range opts {
  40.     o.apply(&options)
  41.   }
  42.  
  43.   // …
  44. }
  45.  
  46. // Options must be provided only if needed.
  47.  
  48. db.Connect(addr)
  49. db.Connect(addr, db.WithTimeout(newTimeout))
  50. db.Connect(addr, db.WithCaching(false))
  51. db.Connect(
  52.   addr,
  53.   db.WithCaching(false),
  54.   db.WithTimeout(newTimeout),
  55. )

See also,