sync.Once & Padrões Singleton

sync.Once executa uma função exatamente uma vez, mesmo quando muitas goroutines a chamam concorrentemente.

Equipes o utilizam para inicialização preguiçosa de recursos caros, evitando problemas de ordem de init().

Resumo

Um singleton expõe uma instância compartilhada para todo o programa.

Go pode implementar isso com variáveis em nível de pacote, mas o código de produção idiomático prefere injeção explícita de dependência e reserva sync.Once para casos como registro de codecs ou carregamento de raízes TLS, onde uma única configuração preguiçosa é inevitável.

A biblioteca padrão usa sync.Once internamente para inicialização única; seu código de aplicação deve usá-lo com moderação e documentar por que os globais são justificados.

Receita

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

var (
    parser *regexp.Regexp
    once   sync.Once
)
 
func emailPattern() *regexp.Regexp {
    once.Do(func() {
        parser = regexp.MustCompile(`^[^@]+@[^@]+\.[^@]+$`)
    })
    return parser
}

Quando usar isso:

• Compilação/carregamento caro e único (regex, esquema, transporte HTTP padrão)
• Inicialização preguiçosa quando main não pode facilmente passar dependências para pilhas de chamadas profundas
• Caches internos de bibliotecas que devem ser para todo o processo

Exemplo de Trabalho

package metrics
 
import (
    "sync"
 
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promauto"
)
 
type Registry struct {
    requests *prometheus.CounterVec
}
 
var (
    defaultReg *Registry
    once       sync.Once
)
 
func Default() *Registry {
    once.Do(func() {
        defaultReg = &Registry{
            requests: promauto.NewCounterVec(
                prometheus.CounterOpts{Name: "http_requests_total", Help: "HTTP requests"},
                []string{"route", "code"},
            ),
        }
    })
    return defaultReg
}
 
func (r *Registry) Inc(route, code string) {
    r.requests.WithLabelValues(route, code).Inc()
}
 
func ExampleUsage() {
    Default().Inc("/health", "200")
}

O que isso demonstra:

• once.Do inicializa defaultReg na primeira chamada de Default()
• Chamadas subsequentes retornam o mesmo ponteiro sem bloqueio no caminho crítico
• Default() exportado documenta o ponto de acesso global

Análise Profunda

Como Funciona

• sync.Once armazena uma flag de conclusão e um mutex
• A primeira chamada a Do executa f; esperadores concorrentes bloqueiam até a conclusão
• Após a conclusão, Do se torna uma carga atômica rápida
• Se f entrar em pânico, Once fica travado - não entre em pânico dentro de Do

sync.Once versus init()

Trade-offs do Singleton

Notas Go

// Prefira isso em código de aplicação:
func NewAPI(reg *metrics.Registry) *API { return &API{reg: reg} }
 
// Em main:
reg := metrics.NewRegistry()
api := NewAPI(reg)

• Redefinir globais em testes requer tags de compilação ou injeção de dependência
• Não chame once.Do com funções diferentes - apenas a primeira é executada
• Para http.DefaultClient em todo o processo, prefira um cliente explícito com timeout

Armadilhas

• Pânicos dentro de once.Do - Once nunca tenta novamente; o pacote permanece quebrado. Correção: valide antes de Do ou entre em pânico apenas em erros de programador que você aceita como fatais.
• Pool de banco de dados Singleton - Testes competem por estado compartilhado; migrações se tornam globais. Correção: passe *sql.DB de main ou helper de teste.
• init() conecta serviços - Importar o pacote em testes atinge a produção. Correção: sync.Once preguiçoso ou sem rede em init.
• Default() oculto em todos os lugares - Assinaturas omitem dependências; fakes impossíveis. Correção: injete interface; mantenha Default() apenas para demonstrações.
• Bloqueio com dupla verificação manual - Fácil de errar antes das suposições do modelo de memória do Go 1.21. Correção: use sync.Once em vez de atômicos personalizados.
• Confusão de Once por instância - Once deve viver na struct se cada instância inicializa separadamente. Correção: Once em nível de pacote apenas para verdadeiros singletons.

Alternativas

FAQs

Relacionados

• Funções Construtoras & APIs de Pacote - injeção explícita de New
• Noções Básicas de Padrões Go - exemplo introdutório de sync.Once
• Antipadrões Comuns em Bases de Código Go - init() e estado global
• Idiomas Go: Composição Sobre Herança - viés de injeção de dependência

Versões de Stack: 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 (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique na compilação).