Patrón de Opciones Funcionales

El patrón de opciones funcionales configura tipos complejos a través de una lista variádica de funciones Option pasadas a un constructor.

Reemplaza las sobrecargas telescópicas de New y las estructuras de constructor mutables con configuraciones componibles e independientes del orden.

Resumen

Las opciones funcionales modelan cada perilla de configuración como func(*T) aplicado dentro de New.

Los llamadores pasan solo las configuraciones que les importan; el constructor aplica primero los valores predeterminados y luego ejecuta cada opción.

El patrón es idiomático para bibliotecas y clientes de infraestructura donde existen muchas configuraciones ortogonales y la compatibilidad binaria es importante.

Cambia una pequeña cantidad de código repetitivo por APIs que se mantienen legibles a medida que crecen.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

type Option func(*Client) error
 
func WithTimeout(d time.Duration) Option {
    return func(c *Client) error {
        if d <= 0 { return errors.New("el tiempo de espera debe ser positivo") }
        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
}

Cuándo usar esto:

• Tipos exportados con varias configuraciones opcionales
• APIs de bibliotecas donde las nuevas opciones no deben romper los sitios de llamada existentes
• Constructores que necesitan valores predeterminados sensatos pero permiten anulaciones
• Configuraciones que son independientes (tiempo de espera, reintentos, TLS, registro)

Ejemplo de Trabajo

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: se requiere URL base") }
        c.base = url
        return nil
    }
}
 
func WithAPIKey(key string) Option {
    return func(c *Client) error {
        if key == "" { return errors.New("weather: se requiere clave API") }
        c.apiKey = key
        return nil
    }
}
 
func WithHTTPClient(hc *http.Client) Option {
    return func(c *Client) error {
        if hc == nil { return errors.New("weather: se requiere cliente http") }
        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: se requiere clave API")
    }
    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: estado %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"))
}

Lo que esto demuestra:

• Los valores predeterminados (base, tiempo de espera de http.Client) residen dentro de New
• Cada función With* valida su propia entrada
• New aplica reglas entre campos (se requiere clave API)
• Los llamadores componen opciones sin conocer la disposición de los campos

Inmersión Profunda

Cómo Funciona

• Option es un tipo de función cerrado sobre valores de configuración
• New asigna el objetivo, establece valores predeterminados y luego aplica opts en orden
• Las opciones mutan campos no exportados en el tipo construido
• Exporta ayudantes With*; mantén Option sin exportar cuando sea posible

Orden de Opciones y Conflictos

Variantes

Notas de Go

// Prefiere el tipo Option no exportado en el ámbito del paquete.
type option func(*Server)
 
// Exporta constructores para facilitar el descubrimiento.
func WithAddr(addr string) option { /* ... */ }

• No exportes los campos de la estructura que estás protegiendo con opciones
• Devuelve ( *T, error) de New cuando la validación pueda fallar
• Usa nombres de opciones significativos: WithTimeout, no SetTimeout (mutación implícita)

Trampas

• Los campos exportados eluden las opciones - Si los campos de la estructura están exportados, los llamadores mutan el estado después de New y las invariantes se rompen. Solución: mantén los campos de configuración sin exportar.
• Opciones sensibles al orden sin documentación - Dos opciones que tocan el mismo campo confunden a los llamadores. Solución: documentar que gana el último o devolver un error en caso de conflicto.
• Opciones para tipos de dos campos - New(a, b) es más claro que New(WithA(a), WithB(b)) para tipos triviales. Solución: reserva las opciones para 3 o más configuraciones ortogonales.
• Opciones de puntero nulo - WithHTTPClient(nil) provoca un pánico en el uso. Solución: valida que no sea nulo en la función de opción.
• Semántica de opciones rota - Renombrar WithTTL para que signifique un campo diferente rompe silenciosamente a los llamadores. Solución: agrega nuevas funciones With*; descontinúa los nombres antiguos en las versiones.
• Probar todas las combinaciones - El producto cartesiano de opciones explota. Solución: prueba en tablas combinaciones representativas y fallos de validación.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Patrones de Go - fragmento introductorio de opciones
• Funciones Constructoras y APIs de Paquetes - emparejamiento New/Open
• Idiomas de Go: Composición Sobre Herencia - contexto de diseño de API
• Antipatrones Comunes en Bases de Código de Go - constructores sobre-ingenierizados

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de GC Green Tea, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica objetivos de placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica en la compilación).