sync.Once y Patrones Singleton

sync.Once ejecuta una función exactamente una vez, incluso cuando muchas goroutines la llaman concurrentemente.

Los equipos lo usan para la inicialización perezosa de recursos costosos, evitando al mismo tiempo los peligros de orden de init().

Resumen

Un singleton expone una instancia compartida para todo el programa.

Go puede implementar eso con variables a nivel de paquete, pero el código de producción idiomático prefiere la inyección explícita de dependencias y reserva sync.Once para casos como el registro de codecs o la carga de raíces TLS donde una configuración perezosa única es inevitable.

La biblioteca estándar usa sync.Once internamente para la inicialización única; tu código de aplicación debería usarlo con moderación y documentar por qué se justifican los globales.

Receta

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

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

Cuándo usar esto:

• Compilación/carga costosa única (regex, esquema, transporte HTTP predeterminado)
• Inicialización perezosa cuando main no puede pasar fácilmente dependencias a pilas de llamadas profundas
• Cachés internas de bibliotecas que deben ser para todo el proceso

Ejemplo de Trabajo

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")
}

Lo que esto demuestra:

• once.Do inicializa defaultReg en la primera llamada a Default()
• Las llamadas posteriores devuelven el mismo puntero sin bloqueo en la ruta activa
• Default() exportado documenta el punto de acceso global

Análisis Profundo

Cómo Funciona

• sync.Once almacena una bandera de finalización y un mutex
• La primera llamada a Do ejecuta f; los concurrentes en espera se bloquean hasta que se complete
• Después de la finalización, Do se convierte en una carga atómica rápida
• Si f entra en pánico, Once se queda atascado; no entres en pánico dentro de Do

sync.Once versus init()

Compensaciones del Singleton

Notas de Go

// Prefiere esto en el código de aplicación:
func NewAPI(reg *metrics.Registry) *API { return &API{reg: reg} }
 
// En main:
reg := metrics.NewRegistry()
api := NewAPI(reg)

• Restablecer globales en pruebas requiere etiquetas de compilación o inyección de dependencias
• No llames a once.Do con funciones diferentes; solo se ejecuta la primera
• Para http.DefaultClient en todo el proceso, prefiere un cliente explícito con tiempo de espera

Errores Comunes

• Pánicos dentro de once.Do - Once nunca reintenta; el paquete permanece roto. Solución: valida antes de Do o entra en pánico solo ante errores de programador que aceptas como fatales.
• Pool de bases de datos Singleton - Las pruebas compiten por estado compartido; las migraciones se vuelven globales. Solución: pasa *sql.DB desde main o un ayudante de prueba.
• init() marca servicios - Importar el paquete en pruebas accede a producción. Solución: sync.Once perezoso o sin red de inicialización.
• Default() oculto en todas partes - Las firmas omiten dependencias; los fakes son imposibles. Solución: inyecta la interfaz; reserva Default() solo para demostraciones.
• Bloqueo de doble verificación manual - Fácil de hacer mal antes de las suposiciones del modelo de memoria de Go 1.21. Solución: usa sync.Once en lugar de atómicos personalizados.
• Confusión de Once por instancia - Once debe vivir en la estructura si cada instancia se inicializa por separado. Solución: Once a nivel de paquete solo para verdaderos singletons.

Alternativas

Preguntas Frecuentes

Relacionado

• Funciones Constructoras y APIs de Paquete - cableado explícito de New
• Conceptos Básicos de Patrones Go - ejemplo introductorio de sync.Once
• Antipatrones Comunes en Bases de Código Go - init() y estado global
• Idiomas de Go: Composición Sobre Herencia - sesgo de inyección de dependencias

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