Gerenciamento de Configuração: Env, Flags & Viper

Carregue a configuração do serviço a partir de variáveis de ambiente e flags para implantações 12-factor, com Viper opcional para padrões de arquivo e hot-reload quando a complexidade for justificada.

Resumo

Configuração é tudo o que muda entre os ambientes de implantação: portas, DSNs, flags de recursos, níveis de log.

O pacote flag analisa argumentos de CLI; os.Getenv lê variáveis de ambiente de contêiner injetadas pelo Kubernetes ou CI.

spf13/viper mescla arquivos, env e flags com regras de precedência e recarregamento opcional fsnotify.

A observabilidade melhora quando os logs de inicialização imprimem instantâneos de configuração seguros e a prontidão falha em valores obrigatórios ausentes.

Receita

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

port := flag.String("port", envOr("PORT", "8080"), "Porta de escuta HTTP")
logLevel := flag.String("log-level", envOr("LOG_LEVEL", "info"), "Nível do slog")
flag.Parse()

Quando usar isso:

• Serviços conteinerizados com staging vs produção orientados por env
• CLIs que aceitam substituições via flags para desenvolvimento local
• Equipes que precisam de padrões YAML verificados no git mais substituições de env em produção
• Flags de recursos e ajuste de tempo limite sem reconstruções
• Operadores que desejam recarregamento de observação de arquivos apenas para configurações não críticas

Exemplo de Trabalho

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("configuração inválida", "err", err)
        os.Exit(1)
    }
 
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: cfg.LogLevel}))
    slog.SetDefault(logger)
 
    slog.Info("configuração de inicialização",
        "port", cfg.Port,
        "log_level", cfg.LogLevel.String(),
        "tracing", cfg.EnableTracing,
        "read_timeout", cfg.ReadTimeout.String(),
    )
 
    slog.Info("pronto para servir", "addr", ":"+cfg.Port)
}
 
func loadConfig() (Config, error) {
    _ = flag.String("config", "", "caminho opcional do arquivo de configuração")
    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("ler configuração: %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 é obrigatório")
    }
 
    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("nível de log desconhecido %q", s)
    }
}

O que isso demonstra:

• Padrões do Viper mais variáveis de ambiente com prefixo APP_ (APP_PORT, APP_DB_URL)
• Arquivo de configuração opcional via flag -config
• Validação obrigatória de db_url antes do início do servidor
• Log seguro de inicialização de campos de configuração não secretos

Mergulho Profundo

Como Funciona

• flag.Parse é executado uma vez em main antes que outros pacotes leiam flags.
• Variáveis de ambiente substituem os padrões de arquivo em implantações 12-factor.
• Viper AutomaticEnv vincula chaves de env a chaves de configuração aninhadas com substituições.
• Hot reload observa arquivos e chama callbacks; nem todos os campos devem recarregar ao vivo.

Precedência (configuração típica do Viper)

Regras de Configuração 12-Factor

Notas de Go

// Pequenos serviços: pule o Viper
func envOr(key, fallback string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return fallback
}
 
// Valide uma vez, passe a struct - não leia env profundamente nos manipuladores
type Config struct { Port string }
func NewServer(cfg Config) *http.Server { /* ... */ }

Trade-offs do Hot-Reload

Armadilhas

• Ler env em todo manipulador - Oculta dependências e quebra testes; injete Config na inicialização.
• Registrar segredos em Info - DSNs e chaves de API em logs de inicialização vazam para agregadores; ofusque apenas hosts.
• Singleton global do Viper - Difícil de testar; use viper.New() por carregamento em bibliotecas e testes.
• Portas de escuta de hot-reloading - Não é possível reassociar sem reinício; não observe port para recarga ao vivo.
• Análise de flags em init - Conflitos de ordem entre pacotes; analise apenas em main.
• Validação de duração ausente - Tempos limite de 0s quebram silenciosamente servidores HTTP; valide durações positivas.
• Padrões implícitos para segredos de produção - Padrão vazio para segredos força env explícito em produção.

Alternativas

FAQs

Relacionados

• Noções Básicas de Observabilidade - exemplo de variável de ambiente
• Logging Estruturado com slog - nível de log da configuração
• Probes de Saúde, Prontidão e Liveness - falha na prontidão com configuração ruim
• Desligamento Gracioso e Manipulação de Sinais - tempo limite de desligamento da configuração
• Melhores Práticas de Observabilidade - logs de inicialização seguros

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