🤲🏻 👬 👩🏼‍✈️ Opções funcionais em esteróides 📧 👠 🖐🏾

Olá Habr! Apresento a você a tradução do artigo Opções funcionais sobre esteróides de Márk Sági-Kazár .

imagem

As opções funcionais são o paradigma da Go para APIs limpas e extensíveis. Ela é popularizada por Dave Cheney e Rob Pike . Esta postagem é sobre práticas que existem em torno do modelo desde que foi introduzido pela primeira vez.

As opções funcionais surgiram como uma maneira de criar APIs boas e limpas com uma configuração que inclui parâmetros opcionais. Há muitas maneiras óbvias de fazer isso (construtor, estrutura de configuração, setters etc.), mas quando você precisa passar por dezenas de opções, elas são mal lidas e não fornecem APIs tão boas quanto as opções funcionais.

Introdução - o que são opções funcionais?

Geralmente, quando você cria um "objeto", chama o construtor com os argumentos necessários:

obj := New(arg1, arg2)

(Vamos ignorar o fato de que não há construtores tradicionais no Go.)

As opções funcionais permitem estender a API com parâmetros adicionais, transformando a linha acima no seguinte:

// I can still do this...
obj := New(arg1, arg2)

// ...but this works too
obj := New(arg1, arg2, myOption1, myOption2)

As opções funcionais são basicamente argumentos de uma função variável que assume como parâmetros um tipo de configuração composto ou intermediário. Devido à sua natureza variável, é perfeitamente aceitável chamar o construtor sem opções, mantendo-o limpo, mesmo se você quiser usar os valores padrão.

Para demonstrar melhor o padrão, vamos dar uma olhada em um exemplo realista (sem opções funcionais):

type Server struct {
    addr string
}

// NewServer initializes a new Server listening on addr.
func NewServer(addr string) *Server {
    return &Server {
        addr: addr,
    }
}

Depois de adicionar a opção de tempo limite, o código fica assim:

type Server struct {
    addr string

    // default: no timeout
    timeout time.Duration
}

// Timeout configures a maximum length of idle connection in Server.
func Timeout(timeout time.Duration) func(*Server) {
    return func(s *Server) {
        s.timeout = timeout
    }
}

// NewServer initializes a new Server listening on addr with optional configuration.
func NewServer(addr string, opts ...func(*Server)) *Server {
    server := &Server {
        addr: addr,
    }

    // apply the list of options to Server
    for _, opt := range opts {
        opt(server)
    }

    return server
}

A API resultante é fácil de usar e fácil de ler:

// no optional paramters, use defaults
server := NewServer(":8080")

// configure a timeout in addition to the address
server := NewServer(":8080", Timeout(10 * time.Second))

// configure a timeout and TLS in addition to the address
server := NewServer(":8080", Timeout(10 * time.Second), TLS(&TLSConfig{}))

Para comparação, eis a aparência da inicialização usando o construtor e a estrutura de configuração da configuração:

// constructor variants
server := NewServer(":8080")
server := NewServerWithTimeout(":8080", 10 * time.Second)
server := NewServerWithTimeoutAndTLS(":8080", 10 * time.Second, &TLSConfig{})


// config struct
server := NewServer(":8080", Config{})
server := NewServer(":8080", Config{ Timeout: 10 * time.Second })
server := NewServer(":8080", Config{ Timeout: 10 * time.Second, TLS: &TLSConfig{} })

A vantagem de usar opções funcionais sobre o construtor é provavelmente óbvia: elas são mais fáceis de manter e ler / gravar. Os parâmetros funcionais também excedem a estrutura de configuração quando os parâmetros não são passados para o construtor. Nas seções a seguir, mostrarei ainda mais exemplos em que a estrutura de configuração pode não corresponder às expectativas.

Leia o histórico completo das opções funcionais clicando nos links da introdução. (nota do tradutor - um blog com um artigo original de Dave Cheney nem sempre está disponível na Rússia e pode exigir uma conexão VPN para visualizá-la. Além disso, as informações do artigo estão disponíveis no vídeo de seu relatório no dotGo 2014 )

Práticas de Opções Funcionais

As opções funcionais em si nada mais são do que funções passadas ao construtor. A facilidade de uso de funções simples oferece flexibilidade e possui grande potencial. Portanto, não surpreende que, ao longo dos anos, muitas práticas tenham aparecido em torno do modelo. Abaixo, fornecerei uma lista do que considero as práticas mais populares e úteis.

Envie-me um e-mail se achar que algo está faltando.

Tipo de opções

A primeira coisa que você pode fazer ao aplicar o modelo de opções funcionais é determinar o tipo da função opcional:

// Option configures a Server.
type Option func(s *Server)

Embora isso possa não parecer uma grande melhoria, o código se torna mais legível usando um nome de tipo em vez de definir uma função:

func Timeout(timeout time.Duration) func(*Server) { /*...*/ }

// reads: a new server accepts an address
//      and a set of functions that accepts the server itself
func NewServer(addr string, opts ...func(s *Server)) *Server

// VS

func Timeout(timeout time.Duration) Option { /*...*/ }

// reads: a new server accepts an address and a set of options
func NewServer(addr string, opts ...Option) *Server

Outra vantagem de ter um tipo de opção é que Godoc coloca as funções de opção sob o tipo:

imagem

Lista de tipos de opção

Normalmente, parâmetros funcionais são usados para criar uma única instância de algo, mas esse nem sempre é o caso. Reutilizar a lista de parâmetros padrão ao criar várias instâncias também não é incomum:

defaultOptions := []Option{Timeout(5 * time.Second)}

server1 := NewServer(":8080", append(defaultOptions, MaxConnections(10))...)

server2 := NewServer(":8080", append(defaultOptions, RateLimit(10, time.Minute))...)

server3 := NewServer(":8080", append(defaultOptions, Timeout(10 * time.Second))...)

Esse código não é muito legível, especialmente considerando que o objetivo do uso de opções funcionais é criar APIs amigáveis. Felizmente, há uma maneira de simplificar isso. Só precisamos dividir a opção [] diretamente com a opção:

// Options turns a list of Option instances into an Option.
func Options(opts ...Option) Option {
    return func(s *Server) {
        for _, opt := range opts {
            opt(s)
        }
    }
}

Depois de substituir a fatia pela função Opções, o código acima se torna:

defaultOptions := Options(Timeout(5 * time.Second))

server1 := NewServer(":8080", defaultOptions, MaxConnections(10))

server2 := NewServer(":8080", defaultOptions, RateLimit(10, time.Minute))

server3 := NewServer(":8080", defaultOptions, Timeout(10 * time.Second))

Prefixos das opções With / Set

As opções geralmente são tipos complexos, diferentemente de um tempo limite ou do número máximo de conexões. Por exemplo, no pacote do servidor, você pode definir a interface do Agente de Log como uma opção (e usá-la se não houver um agente de log padrão):

type Logger interface {
    Info(msg string)
    Error(msg string)
}

Obviamente, o nome do criador de logs não pode ser usado como o nome da opção, pois já é usado pela interface. Você pode chamar a opção LoggerOption, mas não é um nome muito amigável. Se você olhar para o construtor como uma frase, no nosso caso a palavra com: WithLogger vem à mente.

func WithLogger(logger Logger) Option {
    return func(s *Server) {
        s.logger = logger
    }
}

// reads: create a new server that listens on :8080 with a logger
NewServer(":8080", WithLogger(logger))

Outro exemplo comum de uma opção de tipo complexo é uma fatia de valores:

type Server struct {
    // ...

    whitelistIPs []string
}

func WithWhitelistedIP(ip string) Option {
    return func(s *Server) {
        s.whitelistIPs = append(s.whitelistIPs, ip)
    }
}

NewServer(":8080", WithWhitelistedIP("10.0.0.0/8"), WithWhitelistedIP("172.16.0.0/12"))

Nesse caso, a opção geralmente acrescenta os valores aos existentes, em vez de substituí-los. Se você precisar sobrescrever um conjunto de valores existente, poderá usar a palavra set no nome da opção:

func SetWhitelistedIP(ip string) Option {
    return func(s *Server) {
        s.whitelistIPs = []string{ip}
    }
}

NewServer(
    ":8080",
    WithWhitelistedIP("10.0.0.0/8"),
    WithWhitelistedIP("172.16.0.0/12"),
    SetWhitelistedIP("192.168.0.0/16"), // overwrites any previous values
)

Predefinição de modelo

Casos de uso especiais são geralmente universais o suficiente para apoiá-los na biblioteca. No caso de uma configuração, isso pode significar um conjunto de parâmetros agrupados e usados como uma predefinição para uso. Em nosso exemplo, o servidor pode ter cenários de uso aberto e interno que definem tempos limite, limites de velocidade, número de conexões etc. de diferentes maneiras.

// PublicPreset configures a Server for public usage.
func PublicPreset() Option {
    return Options(
        WithTimeout(10 * time.Second),
        MaxConnections(10),
    )
}

// InternalPreset configures a Server for internal usage.
func InternalPreset() Option {
    return Options(
        WithTimeout(20 * time.Second),
        WithWhitelistedIP("10.0.0.0/8"),
    )
}

Embora as predefinições possam ser úteis em alguns casos, elas provavelmente são de grande valor nas bibliotecas internas e, nas bibliotecas públicas, seu valor é menor.

Valores de tipo padrão x valores predefinidos padrão

Ir sempre tem valores padrão. Para números, geralmente é zero, para tipos booleanos, é falso e assim por diante. Em uma configuração opcional, é considerado uma boa prática confiar nos valores padrão. Por exemplo, um valor nulo deve significar um tempo limite ilimitado em vez de sua ausência (o que geralmente não faz sentido).

Em alguns casos, o valor do tipo padrão não é um bom valor padrão. Por exemplo, o valor padrão para o Agente de Log é nulo, o que pode levar ao pânico (se você não proteger as chamadas do agente com verificações condicionais).

Nesses casos, definir o valor no construtor (antes de aplicar os parâmetros) é uma boa maneira de determinar o fallback:

func NewServer(addr string, opts ...func(*Server)) *Server {
    server := &Server {
        addr:   addr,
        logger: noopLogger{},
    }

    // apply the list of options to Server
    for _, opt := range opts {
        opt(server)
    }

    return server
}

Vi exemplos com predefinições padrão (usando o modelo descrito na seção anterior). No entanto, não considero isso uma boa prática. Isso é muito menos expressivo do que apenas definir valores padrão no construtor:

func NewServer(addr string, opts ...func(*Server)) *Server {
    server := &Server {
        addr:   addr,
    }

    // what are the defaults?
    opts = append([]Option{DefaultPreset()}, opts...)

    // apply the list of options to Server
    for _, opt := range opts {
        opt(server)
    }

    return server
}

Opção de estrutura de configuração

Ter uma estrutura Config como uma opção funcional provavelmente não é tão comum, mas isso às vezes é encontrado. A ideia é que as opções funcionais se refiram à estrutura de configuração em vez de se referirem ao objeto real que está sendo criado:

type Config struct {
    Timeout time.Duration
}

type Option func(c *Config)

type Server struct {
    // ...

    config Config
}

Esse modelo é útil quando você tem muitas opções, e a criação de uma estrutura de configuração parece mais limpa do que listar todas as opções em uma chamada de função:

config := Config{
    Timeout: 10 * time.Second
    // ...
    // lots of other options
}

NewServer(":8080", WithConfig(config))

Outro caso de uso para este modelo é definir valores padrão:

config := Config{
    Timeout: 10 * time.Second
    // ...
    // lots of other options
}

NewServer(":8080", WithConfig(config), WithTimeout(20 * time.Second))

Modelos avançados

Depois de escrever dezenas de opções funcionais, você pode se perguntar se existe uma maneira melhor de fazer isso. Não em termos de uso, mas em termos de suporte a longo prazo.

Por exemplo, e se pudéssemos definir tipos e usá-los como parâmetros:

type Timeout time.Duration

NewServer(":8080", Timeout(time.Minute))

(Observe que o uso da API permanece o mesmo). Ao

alterar o tipo de opção, podemos fazer isso facilmente:

// Option configures a Server.
type Option interface {
    // apply is unexported,
    // so only the current package can implement this interface.
    apply(s *Server)
}

A substituição de uma função opcional como interface abre a porta para várias novas maneiras de implementar opções funcionais:

Vários tipos internos podem ser usados como parâmetros sem uma função de invólucro:

// Timeout configures a maximum length of idle connection in Server.
type Timeout time.Duration

func (t Timeout) apply(s *Server) {
    s.timeout = time.Duration(t)
}

As listas de opções e estruturas de configuração (consulte as seções anteriores) também podem ser redefinidas da seguinte maneira:

// Options turns a list of Option instances into an Option.
type Options []Option

func (o Options) apply(s *Server) {
    for _, opt := range o {
        o.apply(s)
    }
}

type Config struct {
    Timeout time.Duration
}

func (c Config) apply(s *Server) {
    s.config = c
}

Meu favorito pessoal é a capacidade de reutilizar a opção em vários construtores:

// ServerOption configures a Server.
type ServerOption interface {
    applyServer(s *Server)
}

// ClientOption configures a Client.
type ClientOption interface {
    applyClient(c *Client)
}

// Option configures a Server or a Client.
type Option interface {
    ServerOption
    ClientOption
}

func WithLogger(logger Logger) Option {
    return withLogger{logger}
}

type withLogger struct {
    logger Logger
}

func (o withLogger) applyServer(s *Server) {
    s.logger = o.logger
}

func (o withLogger) applyClient(c *Client) {
    c.logger = o.logger
}

NewServer(":8080", WithLogger(logger))
NewClient("http://localhost:8080", WithLogger(logger))

Sumário

Parâmetros funcionais é um modelo poderoso para criar APIs limpas e extensíveis com dezenas de parâmetros. Embora isso faça um pouco mais de trabalho do que o suporte a uma estrutura de configuração simples, ele oferece muito mais flexibilidade e APIs muito mais limpas do que as alternativas.

Opções funcionais em esteróides