Gestión de Configuración: Env, Flags y Viper

Carga la configuración del servicio desde variables de entorno y flags para despliegues 12-factor, con Viper opcional para valores predeterminados de archivo y recarga en caliente cuando la complejidad lo justifique.

Resumen

La configuración es todo lo que cambia entre entornos de despliegue: puertos, DSNs, flags de funcionalidades, niveles de registro.

El paquete flag analiza los argumentos de la CLI; os.Getenv lee las variables de entorno del contenedor inyectadas por Kubernetes o CI.

spf13/viper fusiona archivos, entorno y flags con reglas de precedencia y recarga opcional con fsnotify.

La observabilidad mejora cuando los registros de inicio imprimen instantáneas de configuración seguras y la preparación falla ante valores requeridos faltantes.

Receta

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

port := flag.String("port", envOr("PORT", "8080"), "Puerto de escucha HTTP")
logLevel := flag.String("log-level", envOr("LOG_LEVEL", "info"), "Nivel de slog")
flag.Parse()

Cuándo usar esto:

• Servicios contenerizados con staging vs producción impulsados por entorno.
• CLIs que aceptan anulaciones a través de flags para desarrollo local.
• Equipos que necesitan valores predeterminados de YAML registrados en git más anulaciones de entorno en producción.
• Flags de funcionalidades y ajuste de tiempos de espera sin reconstrucciones.
• Operadores que desean recarga por observación de archivos solo para configuraciones no críticas.

Ejemplo de Trabajo

package main
 
import (
    "flag"
    "fmt"
    "log/slog"
    "os"
    "strings"
    "time"
 
    "github.com/spf13/viper"
)
 
type Config struct {
    Port         string
    LogLevel     slog.Level
    DBURL        string
    ReadTimeout  time.Duration
    EnableTracing bool
}
 
func main() {
    cfg, err := loadConfig()
    if err != nil {
        slog.Error("configuración inválida", "err", err)
        os.Exit(1)
    }
 
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: cfg.LogLevel}))
    slog.SetDefault(logger)
 
    slog.Info("configuración de inicio",
        "port", cfg.Port,
        "log_level", cfg.LogLevel.String(),
        "tracing", cfg.EnableTracing,
        "read_timeout", cfg.ReadTimeout.String(),
    )
 
    slog.Info("listo para servir", "addr", ":"+cfg.Port)
}
 
func loadConfig() (Config, error) {
    _ = flag.String("config", "", "ruta opcional del archivo de configuración")
    flag.Parse()
 
    v := viper.New()
    v.SetDefault("port", "8080")
    v.SetDefault("log_level", "info")
    v.SetDefault("read_timeout", "5s")
    v.SetDefault("enable_tracing", false)
 
    v.SetEnvPrefix("APP")
    v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
    v.AutomaticEnv()
 
    if p := flag.Lookup("config").Value.String(); p != "" {
        v.SetConfigFile(p)
        if err := v.ReadInConfig(); err != nil {
            return Config{}, fmt.Errorf("error al leer la configuración: %w", err)
        }
    }
 
    level, err := parseLevel(v.GetString("log_level"))
    if err != nil {
        return Config{}, err
    }
    timeout, err := time.ParseDuration(v.GetString("read_timeout"))
    if err != nil {
        return Config{}, fmt.Errorf("read_timeout: %w", err)
    }
 
    db := v.GetString("db_url")
    if db == "" {
        return Config{}, fmt.Errorf("APP_DB_URL es requerido")
    }
 
    return Config{
        Port:          v.GetString("port"),
        LogLevel:      level,
        DBURL:         db,
        ReadTimeout:   timeout,
        EnableTracing: v.GetBool("enable_tracing"),
    }, nil
}
 
func parseLevel(s string) (slog.Level, error) {
    switch strings.ToLower(s) {
    case "debug":
        return slog.LevelDebug, nil
    case "info":
        return slog.LevelInfo, nil
    case "warn", "warning":
        return slog.LevelWarn, nil
    case "error":
        return slog.LevelError, nil
    default:
        return slog.LevelInfo, fmt.Errorf("nivel de registro desconocido %q", s)
    }
}

Lo que esto demuestra:

• Valores predeterminados de Viper más variables de entorno prefijadas con APP_ (APP_PORT, APP_DB_URL)
• Archivo de configuración opcional a través del flag -config
• Validación requerida de db_url antes de iniciar el servidor
• Registro seguro de inicio de campos de configuración no secretos

Análisis Profundo

Cómo Funciona

• flag.Parse se ejecuta una vez en main antes de que otros paquetes lean los flags.
• Las variables de entorno anulan los valores predeterminados del archivo en despliegues 12-factor.
• AutomaticEnv de Viper enlaza claves de entorno a claves de configuración anidadas con reemplazadores.
• La recarga en caliente observa archivos y llama a callbacks; no todos los campos deben recargarse en vivo.

Precedencia (configuración típica de Viper)

Reglas de Configuración 12-Factor

Notas de Go

// Servicios pequeños: omitir Viper
func envOr(key, fallback string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return fallback
}
 
// Validar una vez, pasar struct - no leer entorno en manejadores profundos
type Config struct { Port string }
func NewServer(cfg Config) *http.Server { /* ... */ }

Compromisos de Recarga en Caliente

Trampas

• Leer entorno en cada manejador - Oculta dependencias y rompe pruebas; inyectar Config al inicio.
• Registrar secretos en Info - DSNs y claves API en los registros de inicio se filtran a los agregadores; solo redactar hosts.
• Singleton global de Viper - Difícil de probar; usar viper.New() por carga en bibliotecas y pruebas.
• Puertos de escucha de recarga en caliente - No se pueden reasignar sin reiniciar; no observar port para recarga en vivo.
• Análisis de flags en init - Conflictos de orden entre paquetes; analizar solo en main.
• Validación de duración faltante - Tiempos de espera de 0s rompen silenciosamente los servidores HTTP; validar duraciones positivas.
• Valores predeterminados implícitos para secretos de producción - El valor predeterminado vacío para secretos obliga a usar el entorno explícito en producción.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Observabilidad - ejemplo de variable de entorno
• Registro Estructurado con slog - nivel de registro desde la configuración
• Sondas de Salud, Preparación y Vivacidad - falla la preparación ante configuración incorrecta
• Apagado Elegante y Manejo de Señales - tiempo de espera de apagado desde la configuración
• Mejores Prácticas de Observabilidad - registro seguro al inicio

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