Singleton
Instancia única
Garantiza que una clase tenga una única instancia y ofrece un punto de acceso a ella.
“Debe existir una sola instancia compartida (configuración, caché del proceso).”
workEl caso real
Tu API carga al arrancar la configuración y las feature flags (qué funcionalidades están activas en cada país) desde un archivo y un servicio remoto. La carga tarda medio segundo y debe hacerse una sola vez: si cada módulo tiene su propia copia, unos verán una funcionalidad activa y otros no.
warningEl problema sin el patrón
Cada servicio hace new Configuracion() y vuelve a leer el archivo y a llamar al servicio remoto. Además, cuando las flags se refrescan, unas copias quedan actualizadas y otras no, y el comportamiento de la API depende de qué copia usó cada petición.
check_circleCómo lo resuelve el patrón
La clase Configuracion tiene el constructor privado y un método estático que crea la instancia la primera vez y después devuelve siempre la misma. Hoy lo habitual es delegar esa garantía al contenedor de dependencias, registrando la clase con ciclo de vida singleton.
schemaDiagrama de clases
Diagrama interactivo: puedes acercar, mover el lienzo y pasar el cursor sobre cada clase para ver su detalle.
codeEl código, antes y después
class ServicioPagos {
private config = new Configuracion(); // vuelve a leer archivo y red
}
class ServicioEnvios {
private config = new Configuracion(); // otra copia, quizá con otras flags
}class Configuracion {
private static instancia?: Configuracion;
private flags = new Map<string, boolean>();
private constructor() {
// carga costosa: archivo + servicio remoto
}
static obtener(): Configuracion {
return (Configuracion.instancia ??= new Configuracion());
}
estaActiva(flag: string) { return this.flags.get(flag) ?? false; }
}
// Alternativa recomendada: el contenedor garantiza la instancia única
// y la inyecta como cualquier otra dependencia.
// contenedor.registrarSingleton(Configuracion);Ejemplos en TypeScript, simplificados para mostrar la idea: los tipos auxiliares (Pedido, Cliente…) se omiten.
Matiz importante
Singleton resuelve dos cosas a la vez (instancia única y acceso global), y por eso se considera a menudo un antipatrón: el acceso global oculta dependencias y complica las pruebas. En frameworks como ASP.NET Core, Spring o NestJS se registra el servicio como singleton en el contenedor: la instancia sigue siendo única, pero se inyecta y se puede sustituir en los tests. En entornos con varios hilos, la creación perezosa debe sincronizarse.
thumb_upCuándo usarlo
- ✓Un recurso debe existir una sola vez por proceso: configuración, caché en memoria, registro de métricas.
- ✓Crear la instancia es costoso y su estado tiene que ser coherente para todos.
do_not_disturb_onCuándo no usarlo
- ✕Lo usas como variable global para no pasar dependencias: oculta el acoplamiento y complica las pruebas.
- ✕Necesitas instancias distintas por prueba, por usuario o por petición.
- ✕Para conexiones a base de datos: lo que puede ser único es el punto de acceso que administra un pool de conexiones, no una conexión compartida por todo el sistema.
memoryPrincipios en juego
- •Instancia única controlada: todas las partes ven el mismo estado.
- •Inicialización perezosa: el costo se paga solo la primera vez que se usa.
hubPatrones relacionados
- •Abstract Factory, Builder y Prototype: sus fábricas o registros suelen ser instancias únicas.
- •Facade: muchas veces basta con una sola fachada.
- •Flyweight: ambos comparten instancias, pero un Singleton es una sola instancia que puede cambiar de estado, mientras que los flyweights son muchas instancias y siempre inmutables.
quizPon a prueba lo que leíste
Dos preguntas al azar sobre este patrón. Cada vez que las cambias salen otras.
code_blocksSingleton en tu lenguaje
El mismo caso, implementado completo y de forma idiomática. Se puede copiar y ejecutar.
LO IDIOMÁTICO EN TYPESCRIPT: Un módulo ES se evalúa una sola vez, así que exportar una instancia (export const config = ...) ya funciona como singleton. La clase con constructor privado y un campo estático privado # se usa cuando la creación debe ser perezosa. ??= crea la instancia solo la primera vez.
export class Configuracion {
static #instancia?: Configuracion;
readonly #flags: ReadonlyMap<string, boolean>;
private constructor() {
console.log('Cargando configuración (solo ocurre una vez)...');
this.#flags = new Map([
['pagos.billetera', true],
['envios.express', false],
]);
}
static obtener(): Configuracion {
return (Configuracion.#instancia ??= new Configuracion());
}
estaActiva(flag: string): boolean {
return this.#flags.get(flag) ?? false;
}
}
// ── Uso ──
const desdePagos = Configuracion.obtener();
const desdeEnvios = Configuracion.obtener();
console.log(desdePagos === desdeEnvios); // true
console.log(desdePagos.estaActiva('pagos.billetera')); // true
console.log(desdeEnvios.estaActiva('envios.express')); // false
// new Configuracion(); ← error de compilación: el constructor es privadoLO IDIOMÁTICO EN C# / .NET: Lazy<T> crea la instancia la primera vez que se usa y, por defecto, es seguro con varios hilos. En ASP.NET Core lo habitual es no escribir el patrón a mano: se registra el servicio con builder.Services.AddSingleton<Configuracion>() y el contenedor garantiza la instancia única.
var instancias = await Task.WhenAll(Enumerable.Range(0, 10).Select(_ => Task.Run(() => Configuracion.Instancia)));
Console.WriteLine($"10 hilos, misma instancia: {instancias.All(i => ReferenceEquals(i, instancias[0]))}"); // True
Console.WriteLine(Configuracion.Instancia.EstaActiva("pagos.billetera")); // True
Console.WriteLine(Configuracion.Instancia.EstaActiva("envios.express")); // False
public sealed class Configuracion
{
private static readonly Lazy<Configuracion> _instancia = new(() => new Configuracion());
public static Configuracion Instancia => _instancia.Value;
private readonly Dictionary<string, bool> _flags;
private Configuracion()
{
Console.WriteLine("Cargando configuración (solo ocurre una vez)...");
_flags = new() { ["pagos.billetera"] = true, ["envios.express"] = false };
}
public bool EstaActiva(string flag) => _flags.GetValueOrDefault(flag);
}LO IDIOMÁTICO EN JAVA: La forma recomendada en Java es un enum de un solo elemento ("Effective Java", ítem 3): la JVM garantiza una única instancia, es segura con hilos y resiste la serialización y la reflexión. En Spring no se escribe el patrón: los beans ya son singleton por defecto.
void main() throws Exception {
// Diez hilos virtuales la piden a la vez
try (var hilos = Executors.newVirtualThreadPerTaskExecutor()) {
var tareas = IntStream.range(0, 10).mapToObj(i -> hilos.submit(() -> Configuracion.INSTANCIA)).toList();
var instancias = new ArrayList<Configuracion>();
for (var tarea : tareas) instancias.add(tarea.get());
IO.println("10 hilos, misma instancia: " + instancias.stream().allMatch(i -> i == instancias.get(0))); // true
}
IO.println(Configuracion.INSTANCIA.estaActiva("pagos.billetera")); // true
IO.println(Configuracion.INSTANCIA.estaActiva("envios.express")); // false
}
enum Configuracion {
INSTANCIA;
private final Map<String, Boolean> flags;
Configuracion() {
IO.println("Cargando configuración (solo ocurre una vez)...");
flags = Map.of("pagos.billetera", true, "envios.express", false);
}
boolean estaActiva(String flag) {
return flags.getOrDefault(flag, false);
}
}LO IDIOMÁTICO EN JAVASCRIPT: En JavaScript el propio módulo es el singleton: se evalúa una sola vez y todos los import reciben lo mismo. La variable instancia es privada del módulo (no se exporta) y ??= la crea solo la primera vez que alguien la pide. No hace falta ninguna clase.
let instancia; // privada del módulo
function cargarConfiguracion() {
console.log('Cargando configuración (solo ocurre una vez)...');
const flags = new Map([
['pagos.billetera', true],
['envios.express', false],
]);
return Object.freeze({
estaActiva: (flag) => flags.get(flag) ?? false,
});
}
export function obtenerConfiguracion() {
return (instancia ??= cargarConfiguracion());
}
// ── Uso ──
const desdePagos = obtenerConfiguracion();
const desdeEnvios = obtenerConfiguracion();
console.log(desdePagos === desdeEnvios); // true
console.log(desdePagos.estaActiva('pagos.billetera')); // true
console.log(desdeEnvios.estaActiva('envios.express')); // falseLO IDIOMÁTICO EN PYTHON: Lo más pitónico es no escribir un Singleton: un módulo se importa una sola vez, así que sus objetos ya son únicos. Cuando la creación debe ser perezosa, @functools.cache sobre una función garantiza que se ejecute una sola vez. Es más simple y más fácil de probar que sobrescribir __new__.
from functools import cache
class Configuracion:
def __init__(self) -> None:
print("Cargando configuración (solo ocurre una vez)...")
self._flags = {"pagos.billetera": True, "envios.express": False}
def esta_activa(self, flag: str) -> bool:
return self._flags.get(flag, False)
@cache
def obtener_configuracion() -> Configuracion:
return Configuracion()
if __name__ == "__main__":
desde_pagos = obtener_configuracion()
desde_envios = obtener_configuracion()
print(desde_pagos is desde_envios) # True
print(desde_pagos.esta_activa("pagos.billetera")) # True
print(desde_envios.esta_activa("envios.express")) # False
# En las pruebas se puede reiniciar fácilmente
obtener_configuracion.cache_clear()LO IDIOMÁTICO EN GO: sync.OnceValue (Go 1.21) envuelve una función para que se ejecute una sola vez, aunque la llamen muchas goroutines a la vez, y devuelve siempre el mismo resultado. Es seguro con concurrencia sin escribir ningún mutex.
package main
import (
"fmt"
"sync"
)
type Configuracion struct {
flags map[string]bool
}
func (c *Configuracion) EstaActiva(flag string) bool {
return c.flags[flag]
}
var ObtenerConfiguracion = sync.OnceValue(func() *Configuracion {
fmt.Println("Cargando configuración (solo ocurre una vez)...")
return &Configuracion{flags: map[string]bool{"pagos.billetera": true, "envios.express": false}}
})
func main() {
// Diez goroutines la piden a la vez
var wg sync.WaitGroup
resultados := make([]*Configuracion, 10)
for i := range resultados {
wg.Go(func() { resultados[i] = ObtenerConfiguracion() })
}
wg.Wait()
todasIguales := true
for _, r := range resultados {
todasIguales = todasIguales && r == resultados[0]
}
fmt.Println("10 goroutines, misma instancia:", todasIguales) // true
fmt.Println(ObtenerConfiguracion().EstaActiva("pagos.billetera")) // true
fmt.Println(ObtenerConfiguracion().EstaActiva("envios.express")) // false
}LO IDIOMÁTICO EN RUST: std::sync::LazyLock inicializa un valor static la primera vez que se usa, de forma segura entre hilos. Rust no permite estado global mutable sin sincronización: el singleton es inmutable o se protege con un Mutex, y el compilador lo exige.
use std::collections::HashMap;
use std::sync::LazyLock;
use std::thread;
struct Configuracion {
flags: HashMap<&'static str, bool>,
}
impl Configuracion {
fn esta_activa(&self, flag: &str) -> bool {
self.flags.get(flag).copied().unwrap_or(false)
}
}
static CONFIGURACION: LazyLock<Configuracion> = LazyLock::new(|| {
println!("Cargando configuración (solo ocurre una vez)...");
Configuracion {
flags: HashMap::from([("pagos.billetera", true), ("envios.express", false)]),
}
});
fn main() {
// Diez hilos la piden a la vez
let instancias: Vec<&'static Configuracion> = thread::scope(|s| {
let hilos: Vec<_> = (0..10).map(|_| s.spawn(|| &*CONFIGURACION)).collect();
hilos
.into_iter()
.map(|h| h.join().expect("el hilo terminó con error"))
.collect()
});
let misma = instancias.iter().all(|i| std::ptr::eq(*i, instancias[0]));
println!("10 hilos, misma instancia: {misma}"); // true
println!("{}", CONFIGURACION.esta_activa("pagos.billetera")); // true
println!("{}", CONFIGURACION.esta_activa("envios.express")); // false
}LO IDIOMÁTICO EN PHP: En PHP cada petición web empieza desde cero, así que un singleton vive lo que dura la petición. La forma clásica usa un constructor privado, ??= para crear la instancia una sola vez y __clone privado para que no se pueda copiar. En Laravel no se escribe a mano: $app->singleton(...).
<?php
declare(strict_types=1);
final class Configuracion
{
private static ?self $instancia = null;
/** @var array<string, bool> */
private array $flags;
private function __construct()
{
echo "Cargando configuración (solo ocurre una vez)...\n";
$this->flags = ['pagos.billetera' => true, 'envios.express' => false];
}
private function __clone() {}
public static function obtener(): self
{
return self::$instancia ??= new self();
}
public function estaActiva(string $flag): bool
{
return $this->flags[$flag] ?? false;
}
}
$desdePagos = Configuracion::obtener();
$desdeEnvios = Configuracion::obtener();
var_dump($desdePagos === $desdeEnvios); // bool(true)
var_dump($desdePagos->estaActiva('pagos.billetera')); // bool(true)
var_dump($desdeEnvios->estaActiva('envios.express')); // bool(false)
// new Configuracion(); ← Error: el constructor es privado