Cualquier ingeniero backend ha vivido este drama al menos una vez en su carrera: un servicio de alta carga despacha sin despeinarse decenas de miles de peticiones por segundo desde una caché rápida en Redis, las gráficas de latencia son una línea recta y la monitorización está en verde. Hasta que llega el segundo en que caduca una clave muy popular — por ejemplo, la ficha de un producto estrella en rebajas o el perfil de una celebridad.
En una sola milésima de segundo, cientos de gorutinas paralelas consultan la caché, reciben un «no hay datos» (cache miss) y salen disparadas hacia la base de datos principal con exactamente la misma consulta SQL pesada. El pool de conexiones se colapsa, los tiempos de respuesta se disparan hasta las nubes, saltan timeouts en cascada y producción cae. En la industria esta pesadilla tiene nombres muy gráficos: Cache Stampede («estampida de caché») o Thundering Herd («efecto manada»).
La primera reacción instintiva suele ser montar bloqueos distribuidos con Redis Redlock o colgar un mutex global. Pero un bloqueo distribuido mete latencia extra de red y puede quedarse colgado si cae un nodo, mientras que un sync.Mutex ingenuo frena en seco todo el resto de operaciones del proceso.
En el repositorio oficial de paquetes auxiliares de Go existe una solución sorprendentemente concisa y fiable para este problema: el paquete singleflight de la colección golang.org/x/sync.
Anatomía del pánico: cómo una clave caducada tumba la base de datos
Veamos la física del problema. Imagina un supermercado en vísperas de Nochevieja: se ha acabado el champán en la estantería. Si cada uno de los cien clientes corre personalmente al almacén a gritarle al único mozo «¡Tráeme una botella!», en la puerta del almacén se arma un tapón monumental y el trabajo se paraliza.
La salida sensata es evidente: el primero que llega le dice al encargado «Necesitamos champán». El encargado pide a las otras noventa y nueve personas que esperen un par de minutos junto a la estantería, entra al almacén, saca una caja y reparte las botellas entre todos los que esperan. Se hizo un único viaje a la trastienda y se atendió a cien clientes.
Eso mismo es lo que hace la estructura singleflight.Group. Suprime llamadas concurrentes duplicadas a una función en la memoria RAM de un mismo proceso, fusionándolas en una sola petición real.
Cómo funciona Group.Do y por qué no es una caché, sino una barrera de sincronización
La interfaz básica de singleflight.Group es minimalista:
func (g *Group) Do(key string, fn func() (any, error)) (v any, err error, shared bool)
Su mecánica es muy directa:
- La primera gorutina llama a
g.Do("product:42", fetchFromDB). El grupo comprueba que no hay ninguna tarea activa para la clave"product:42", registra una estructura internacall, toma un bloqueo local y ejecutafn(). - En ese mismo instante, otras 50 gorutinas paralelas llaman a
g.Docon la misma clave"product:42". El grupo detecta la llamada en curso, no vuelve a lanzarfny deja bloqueadas esas gorutinas mediante una primitivasync.WaitGroup. - Cuando la primera función termina y devuelve el resultado, las 51 gorutinas se desbloquean a la vez y reciben el mismo valor
v, el errorerry el indicadorshared = true(que señala que el resultado se ha compartido entre varios consumidores). - Acto seguido, la clave se elimina al instante del mapa interno del grupo.
Quédate con este matiz: singleflight no es una caché. No guarda absolutamente nada más allá de lo que dura la ejecución de la propia consulta. Si un microsegundo después de terminar el grupo entra una nueva petición, la función volverá a ejecutarse. singleflight protege el sistema únicamente frente a duplicados simultáneos en el instante del fallo de caché.
Protección contra bloqueos eternos: combinando DoChan con context.Context
El método clásico Group.Do bloquea la gorutina llamante hasta que la función termina. ¿Y si la base de datos se ha quedado colgada o el servicio externo ha dejado de responder? Todas las gorutinas que esperan quedarían secuestradas, las conexiones HTTP de los clientes se quedarían colgadas y la aplicación acabaría agotando la memoria.
Para evitarlo, el paquete ofrece el método no bloqueante DoChan, que devuelve un canal de solo lectura <-chan Result. Combinado con context.Context, te da una protección total frente a bloqueos indefinidos:
package repository
import (
"context"
"database/sql"
"fmt"
"golang.org/x/sync/singleflight"
)
type Product struct {
ID int64
Title string
Price int64
}
type ProductStore struct {
db *sql.DB
group singleflight.Group
}
func (s *ProductStore) GetProduct(ctx context.Context, tenantID int, productID int64) (*Product, error) {
// La clave de deduplicación debe respetar los límites de tenant y permisos
key := fmt.Sprintf("tenant:%d:product:%d", tenantID, productID)
ch := s.group.DoChan(key, func() (any, error) {
var p Product
query := `SELECT id, title, price FROM products WHERE tenant_id = $1 AND id = $2`
// Pasamos un contexto independiente a la consulta en segundo plano
// para que la cancelación de un cliente no aborte la ejecución del resto
err := s.db.QueryRowContext(context.Background(), query, tenantID, productID).
Scan(&p.ID, &p.Title, &p.Price)
if err != nil {
return nil, err
}
return &p, nil
})
select {
case <-ctx.Done():
// El cliente canceló la petición o saltó el timeout HTTP
return nil, ctx.Err()
case res := <-ch:
if res.Err != nil {
return nil, res.Err
}
// Protección contra carreras de memoria: devolvemos una copia de la estructura
orig := res.Val.(*Product)
copyItem := *orig
return ©Item, nil
}
}
Fíjate en un detalle sutil pero vital: dentro del closure fn pasamos un context.Background() independiente. Si pasaras ahí el ctx del primer cliente y ese cliente cortara la conexión, la cancelación del contexto mataría la consulta para todas las demás gorutinas que siguen esperando el resultado.
Trampas habituales: carreras de punteros y tiempo de vida del grupo
Al empezar con singleflight, los ingenieros con menos rodaje suelen tropezar con dos fallos de diseño clásicos:
- Carreras de datos sobre referencias mutables (Data Races):
Si tu función devuelve un puntero a una estructura (
*Product) o un slice, las 50 gorutinas recibirán una referencia al mismo bloque de memoria en el heap. Si más adelante alguno de los llamantes modifica un campo (por ejemplo,product.Price = 0), el programa sufrirá una data race de manual. La solución es devolver estructuras por valor o hacer una copia superficial (clone = *orig) antes de entregar el dato al cliente, tal como ves en el ejemplo anterior. - Tiempo de vida de la instancia del grupo:
La instancia
singleflight.Groupdebe vivir al nivel del servicio o repositorio de larga duración. Declararvar g singleflight.Groupdentro del cuerpo de un handler HTTP anula por completo el patrón: cada petición HTTP crearía su propio grupo vacío y no habría deduplicación alguna.
Poner singleflight delante de la base de datos cuando falla la caché lleva literalmente veinte líneas de código, pero te ahorra las peores caídas nocturnas en producción bajo picos de tráfico.

