Configuração com viper & envconfig

Serviços e CLIs precisam de configuração que muda por ambiente sem recompilação.

spf13/viper mescla arquivos, flags e variáveis de ambiente com regras de precedência; kelseyhightower/envconfig mapeia variáveis de ambiente diretamente para structs tipados para binários menores.

Receita

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

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)

Quando usar isso:

• Serviços implantados em Kubernetes com ConfigMaps, Secrets e substituições de env
• CLIs que leem um arquivo de configuração localmente, mas aceitam flags para automação
• Equipes que documentam variáveis de ambiente necessárias no README e em Helm charts
• Migração gradual de os.Getenv ad hoc espalhado por pacotes

Exemplo de Trabalho

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("nenhum arquivo de configuração: %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 ou DATABASE_DSN é obrigatório")
    }
    fmt.Printf("port=%d level=%s\n", cfg.HTTPPort, cfg.LogLevel)
}

O que isso demonstra:

• Padrões YAML com substituição de env via AutomaticEnv e replacer de chaves
• Validação fail-fast para segredos em main
• Struct AppConfig tipado separado da API stringly do viper
• Registro seguro quando o arquivo de configuração é opcional em desenvolvimento

Mergulho Profundo

Como Funciona

• viper armazena um mapa chave-valor preenchido a partir de várias fontes; leituras posteriores usam precedência (flag > env > arquivo de config > padrão).
• envconfig reflete tags de struct na inicialização e gera erro para campos required ausentes.
• Ambos rodam uma vez no início do processo; hot reload precisa de fsnotify (viper) ou reinício do processo (modelo de operação mais simples).
• Mantenha o carregamento de configuração em main ou em um pacote config; pacotes de domínio recebem structs tipados, não chamadas globais do viper.

Precedência (viper)

Tags envconfig

Notas Go

// Prefira desmaterializar em um struct assim que as chaves do viper se estabilizarem
var cfg AppConfig
if err := viper.Unmarshal(&cfg); err != nil {
    log.Fatal(err)
}

• Tags Mapstructure em campos de struct alinham chaves do viper com YAML aninhado.
• Nunca registre DSNs completos ou chaves de API; imprima snapshots redigidos apenas no nível info.

Armadilhas

• Viper global em bibliotecas - pacotes que chamam viper.GetString escondem dependências. Correção: carregar em main, passar structs AppConfig.
• Desvio de nomenclatura de chaves - http.port vs HTTP_PORT falha silenciosamente sem SetEnvKeyReplacer. Correção: documentar nomes de env em tabelas Helm e README.
• Segredos obrigatórios ausentes - string vazia passa nas verificações GetString. Correção: validar com if cfg.DSN == "" explícito ou required do envconfig.
• Hot reload sem prontidão - viper.WatchConfig recarrega no meio da requisição. Correção: reiniciar pods ou controlar o reload com troca atômica de ponteiro mais drain.
• Segredos em ConfigMaps - arquivos YAML commitados no git vazam credenciais. Correção: montar Secrets como variáveis de ambiente; manter arquivos apenas para padrões não secretos.
• Ordem de análise de flags - ler viper antes de flag.Parse perde substituições de CLI. Correção: analisar flags primeiro, depois vincular com viper.BindPFlags.

Alternativas

FAQs

Relacionados

• Gerenciamento de Configuração: Env, Flags & Viper - Visão geral do 12-factor
• Noções Básicas de Bibliotecas Essenciais - Início rápido do viper
• Validação de Entrada e Tratamento Seguro de HTML/JSON - valide valores carregados
• Encerramento Gracioso e Tratamento de Sinais - tempos limite de drain controlados por configuração
• Regras de Módulo e Dependência - higiene mínima de dependência

Versões da Pilha: Esta página foi escrita para Go 1.26.x (padrão GC 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). 636f64656775696465732e696f7c6367696f3439337c323032363037