Configuración con viper y envconfig

Los servicios y las CLIs necesitan una configuración que cambie por entorno sin recompilar.

spf13/viper fusiona archivos, flags y variables de entorno con reglas de precedencia; kelseyhightower/envconfig mapea variables de entorno directamente a structs tipados para binarios más pequeños.

Receta

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

viper.SetConfigName("config")
viper.SetConfigType("yaml")
viper.AddConfigPath(".")
viper.AutomaticEnv()
viper.SetDefault("http.port", 8080)
_ = viper.ReadInConfig()
port := viper.GetInt("http.port")

type Config struct {
    Port int    `envconfig:"PORT" default:"8080"`
    DSN  string `envconfig:"DATABASE_URL" required:"true"`
}
var cfg Config
envconfig.Process("", &cfg)

Cuándo usar esto:

• Servicios desplegados en Kubernetes con ConfigMaps, Secrets y anulaciones de entorno
• CLIs que leen un archivo de configuración localmente pero aceptan flags para automatización
• Equipos que documentan variables de entorno requeridas en README y Helm charts
• Migración gradual de os.Getenv ad hoc disperso por los paquetes

Ejemplo de trabajo

package main
 
import (
    "fmt"
    "log"
    "strings"
 
    "github.com/spf13/viper"
)
 
type AppConfig struct {
    HTTPPort int
    LogLevel string
    DSN      string
}
 
func loadViper() AppConfig {
    viper.SetConfigName("config")
    viper.SetConfigType("yaml")
    viper.AddConfigPath(".")
    viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
    viper.AutomaticEnv()
 
    viper.SetDefault("http.port", 8080)
    viper.SetDefault("log.level", "info")
 
    if err := viper.ReadInConfig(); err != nil {
        log.Printf("no config file: %v", err)
    }
 
    return AppConfig{
        HTTPPort: viper.GetInt("http.port"),
        LogLevel: viper.GetString("log.level"),
        DSN:      viper.GetString("database.dsn"),
    }
}
 
func main() {
    cfg := loadViper()
    if cfg.DSN == "" {
        log.Fatal("database.dsn or DATABASE_DSN required")
    }
    fmt.Printf("port=%d level=%s\n", cfg.HTTPPort, cfg.LogLevel)
}

Lo que esto demuestra:

• Valores por defecto de YAML con anulación de entorno mediante AutomaticEnv y el reemplazador de claves
• Validación de fallo rápido para secretos en main
• Struct AppConfig tipado separado de la API de cadenas de viper
• Registro seguro cuando el archivo de configuración es opcional en desarrollo

Profundización

Cómo funciona

• viper almacena un mapa de clave-valor poblado desde múltiples fuentes; las lecturas posteriores usan precedencia (flag > env > archivo de configuración > valor por defecto).
• envconfig refleja las etiquetas de struct al inicio y falla si faltan campos required.
• Ambos se ejecutan una vez al inicio del proceso; la recarga en caliente necesita fsnotify (viper) o reiniciar el proceso (modelo de operaciones más simple).
• Mantenga la carga de configuración en main o en un paquete config; los paquetes de dominio reciben structs tipados, no llamadas globales a viper.

Precedencia (viper)

Etiquetas de envconfig

Notas de Go

// Prefiera desempaquetar en un struct una vez que las claves de viper se estabilicen
var cfg AppConfig
if err := viper.Unmarshal(&cfg); err != nil {
    log.Fatal(err)
}

• Las etiquetas de Mapstructure en los campos del struct alinean las claves de viper con el YAML anidado.
• Nunca registre DSN completos o claves API; imprima instantáneas redactadas solo a nivel info.

Errores comunes

• viper global en bibliotecas - los paquetes que llaman a viper.GetString ocultan dependencias. Solución: cargar en main, pasar structs AppConfig.
• Desviación en nombres de claves - http.port vs HTTP_PORT falla silenciosamente sin SetEnvKeyReplacer. Solución: documentar nombres de entorno en tablas de Helm y README.
• Secretos requeridos faltantes - la cadena vacía pasa las comprobaciones de GetString. Solución: validar con if cfg.DSN == "" explícito o required de envconfig.
• Recarga en caliente sin preparación - WatchConfig de viper recarga a mitad de la solicitud. Solución: reiniciar pods o habilitar la recarga detrás de un intercambio de punteros atómico más un vaciado.
• Secretos en ConfigMaps - los archivos YAML confirmados en git filtran credenciales. Solución: montar Secrets como variables de entorno; usar archivos solo para valores por defecto no secretos.
• Orden de análisis de flags - leer viper antes de flag.Parse omite las anulaciones de CLI. Solución: analizar primero los flags, luego enlazarlos con viper.BindPFlags.

Alternativas

Preguntas frecuentes

Relacionados

• Gestión de Configuración: Entorno, Flags y Viper - Resumen de 12-factor
• Conceptos básicos de bibliotecas esenciales - Inicio rápido de viper
• Validación de Entrada y Manejo Seguro de HTML/JSON - validar valores cargados
• Apagado Elegante y Manejo de Señales - tiempos de espera de vaciado controlados por configuración
• Reglas de Módulos y Dependencias - higiene mínima de dependencias

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