Padrão de Opções Funcionais

O padrão de opções funcionais configura tipos complexos através de uma lista variádica de funções Option passadas a um construtor.

Ele substitui sobrecargas New telescópicas e structs de builder mutáveis por configurações compostas e independentes de ordem.

Resumo

Opções funcionais modelam cada configuração como func(*T) aplicado dentro de New.

Os chamadores passam apenas as configurações que lhes interessam; o construtor aplica os padrões primeiro e, em seguida, executa cada opção.

O padrão é idiomático para bibliotecas e clientes de infraestrutura onde existem muitas configurações ortogonais e a compatibilidade binária é importante.

Ele troca uma pequena quantidade de boilerplate por APIs que permanecem legíveis à medida que crescem.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

type Option func(*Client) error
 
func WithTimeout(d time.Duration) Option {
    return func(c *Client) error {
        if d <= 0 { return errors.New("timeout must be positive") }
        c.timeout = d
        return nil
    }
}
 
func NewClient(opts ...Option) (*Client, error) {
    c := &Client{timeout: 30 * time.Second}
    for _, opt := range opts {
        if err := opt(c); err != nil { return nil, err }
    }
    return c, nil
}

Quando usar isso:

• Tipos exportados com várias configurações opcionais
• APIs de biblioteca onde novas opções não devem quebrar os sites de chamada existentes
• Construtores que precisam de padrões sensatos, mas permitem substituições
• Configurações que são independentes (timeout, retries, TLS, logging)

Exemplo de Trabalho

package weather
 
import (
    "context"
    "errors"
    "fmt"
    "net/http"
    "time"
)
 
type Client struct {
    base    string
    http    *http.Client
    apiKey  string
}
 
type Option func(*Client) error
 
func WithBaseURL(url string) Option {
    return func(c *Client) error {
        if url == "" { return errors.New("weather: base URL required") }
        c.base = url
        return nil
    }
}
 
func WithAPIKey(key string) Option {
    return func(c *Client) error {
        if key == "" { return errors.New("weather: API key required") }
        c.apiKey = key
        return nil
    }
}
 
func WithHTTPClient(hc *http.Client) Option {
    return func(c *Client) error {
        if hc == nil { return errors.New("weather: http client required") }
        c.http = hc
        return nil
    }
}
 
func New(opts ...Option) (*Client, error) {
    c := &Client{
        base: "https://api.weather.example",
        http: &http.Client{Timeout: 10 * time.Second},
    }
    for _, opt := range opts {
        if err := opt(c); err != nil {
            return nil, err
        }
    }
    if c.apiKey == "" {
        return nil, errors.New("weather: API key required")
    }
    return c, nil
}
 
func (c *Client) Forecast(ctx context.Context, city string) (string, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet,
        fmt.Sprintf("%s/v1/forecast?city=%s", c.base, city), nil)
    if err != nil { return "", err }
    req.Header.Set("Authorization", "Bearer "+c.apiKey)
    resp, err := c.http.Do(req)
    if err != nil { return "", err }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK {
        return "", fmt.Errorf("weather: status %d", resp.StatusCode)
    }
    return "sunny", nil
}
 
func main() {
    client, err := New(
        WithAPIKey("dev-key"),
        WithHTTPClient(&http.Client{Timeout: 5 * time.Second}),
    )
    if err != nil { panic(err) }
    fmt.Println(client.Forecast(context.Background(), "Austin"))
}

O que isso demonstra:

• Padrões (base, timeout do http.Client) vivem dentro de New
• Cada função With* valida sua própria entrada
• New aplica regras entre campos (chave de API necessária)
• Chamadores compõem opções sem conhecer o layout dos campos

Mergulho Profundo

Como Funciona

• Option é um tipo de função fechado sobre valores de configuração
• New aloca o alvo, define os padrões e, em seguida, aplica opts em ordem
• As opções modificam campos não exportados no tipo construído
• Exporte helpers With*; mantenha Option não exportado quando possível

Ordem e Conflitos de Opções

Variantes

Notas Go

// Prefira o tipo Option não exportado no escopo do pacote.
type option func(*Server)
 
// Exporte construtores para descoberta.
func WithAddr(addr string) option { /* ... */ }

• Não exporte os campos da struct que você está protegendo com opções
• Retorne ( *T, error) de New quando a validação puder falhar
• Use nomes de opções significativos: WithTimeout, não SetTimeout (mutação implícita)

Armadilhas

• Campos exportados ignoram opções - Se os campos da struct forem exportados, os chamadores modificarão o estado após New e os invariantes serão quebrados. Correção: mantenha os campos de configuração não exportados.
• Opções sensíveis à ordem sem documentação - Duas opções que tocam no mesmo campo confundem os chamadores. Correção: documente "o último vence" ou retorne um erro em caso de conflito.
• Opções para tipos de dois campos - New(a, b) é mais claro do que New(WithA(a), WithB(b)) para tipos triviais. Correção: reserve opções para 3+ configurações ortogonais.
• Opções de ponteiro nulo - WithHTTPClient(nil) causa pânico no uso. Correção: valide não nulo na função de opção.
• Semântica de opção quebrada - Renomear WithTTL para significar um campo diferente quebra os chamadores silenciosamente. Correção: adicione novas funções With*; deprecie nomes antigos ao longo das versões.
• Testando todas as combinações - O produto cartesiano das opções explode. Correção: teste em tabela combinações representativas e falhas de validação.

Alternativas

FAQs

Relacionado

• Noções Básicas de Padrões Go - snippet introdutório de opção
• Funções Construtoras e APIs de Pacote - emparelhamento New/Open
• Idiomas Go: Composição Sobre Herança - contexto de design de API
• Antipadrões Comuns em Bases de Código Go - construtores excessivamente projetados

Versões da Pilha: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique na compilação).