DEV Community: Alejandro Lafourcade Despaigne

Día 14: Cambiaste una clase y rompiste 10 más. Efecto dominó.

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:23:36 +0000

Cambiaste un campo en un DTO. Un rename inocente. Y de repente tienes 10 clases con errores de compilación, 3 tests rotos y un compañero preguntándote "¿qué tocaste?".

No tocaste nada raro. Tocaste una clase. El problema es que esa clase está conectada a todo como si fuera el centro del universo. Y en tu codebase, probablemente lo es.

Esto no es solo de Java

El anti-pattern es el mismo en cualquier stack. Solo cambia la sintaxis:

Java / Spring Boot: un UserDTO compartido entre controller, service y repository
TypeScript / NestJS: un user.dto.ts que se usa en controllers, guards, pipes y servicios
Python / Django: un serializer gigante que sirve para crear, leer, actualizar y exportar
C# / .NET: un UserModel compartido entre API, business layer y data access
Ruby on Rails: un modelo User con as_json sobreescrito 4 veces para diferentes contextos
PHP / Laravel: un UserResource que hace transform distinto según quién lo llame

El patrón es siempre el mismo: un objeto compartido entre capas con necesidades distintas. Cuando lo tocas, se rompe todo.

Alto acoplamiento, baja cohesión

Dos conceptos que suenan a examen de facultad pero que definen si tu código es mantenible o una bomba de tiempo:

Acoplamiento = cuánto depende una clase de otra. Si cambiar A rompe B, C y D, están acopladas.

Cohesión = cuánto se relacionan las cosas dentro de una clase. Si una clase hace cosas que no tienen nada que ver entre sí, tiene baja cohesión.

Lo ideal: bajo acoplamiento, alta cohesión. La realidad de la mayoría de los proyectos: exactamente lo opuesto.

El ejemplo: un DTO que gobierna todo

Un solo UserDTO compartido entre controller, service y hasta la capa de persistencia:

public class UserDTO {
    private Long id;
    private String name;
    private String email;
    private String password;
    private String role;
    private LocalDateTime createdAt;
    private List<OrderDTO> orders;
    private AddressDTO address;
    private String creditCardLast4;
}

Y se usa en todos lados:

@RestController
public class UserController {
    @PostMapping("/users")
    public UserDTO createUser(@RequestBody UserDTO dto) { ... }

    @GetMapping("/users/{id}")
    public UserDTO getUser(@PathVariable Long id) { ... }
}

@Service
public class UserService {
    public UserDTO createUser(UserDTO dto) { ... }
    public UserDTO findById(Long id) { ... }
}

@Service
public class OrderService {
    public List<OrderDTO> getOrders(UserDTO user) { ... }
}

@Service
public class NotificationService {
    public void sendWelcome(UserDTO user) { ... }
}

@Service
public class ReportService {
    public Report generateUserReport(UserDTO user) { ... }
}

Ahora renombras name a fullName. O eliminas creditCardLast4 porque ya no lo necesitas en la respuesta. O agregas un campo.

Todos esos servicios se rompen. El controller se rompe. Los tests se rompen. El frontend se rompe. Todo porque compartes un objeto entre 5 capas con necesidades distintas.

El OrderService no necesita el password. El NotificationService no necesita las órdenes. El ReportService no necesita la tarjeta de crédito. Pero todos dependen del mismo DTO gigante.

En TypeScript sería el mismo problema con una interfaz User compartida entre routes, middleware y services. En Python, un serializer con 15 campos que se usa para crear, listar y exportar. La tecnología cambia, el error no.

La solución: cada capa recibe lo que necesita

import InArticleCTA from '../../components/InArticleCTA.astro';

// Lo que el frontend envía para crear un usuario
public record CreateUserRequest(
    String name,
    String email,
    String password
) {}

// Lo que el endpoint devuelve
public record UserResponse(
    Long id,
    String name,
    String email,
    String role,
    LocalDateTime createdAt
) {}

// Lo que el servicio de notificaciones necesita
public record UserNotificationInfo(
    String name,
    String email
) {}

// Lo que el servicio de reportes necesita
public record UserReportData(
    Long id,
    String name,
    String role,
    LocalDateTime createdAt,
    int totalOrders
) {}

Cada clase recibe exactamente lo que necesita. Ni más, ni menos.

@RestController
public class UserController {
    @PostMapping("/users")
    public UserResponse createUser(@RequestBody CreateUserRequest request) { ... }

    @GetMapping("/users/{id}")
    public UserResponse getUser(@PathVariable Long id) { ... }
}

@Service
public class NotificationService {
    public void sendWelcome(UserNotificationInfo user) { ... }
}

Ahora renombras un campo en CreateUserRequest. ¿Qué se rompe? Solo el controller y su test. Nada más. El servicio de notificaciones ni se entera. El de reportes sigue funcionando. Cero efecto dominó.

Los números

	Antes	Después
Clases afectadas por un cambio de DTO	10+	1-2
Campos innecesarios viajando por la red	5-6	0
Riesgo de exponer password en respuesta	Alto	Nulo

La otra cara: cohesión

Acoplamiento bajo sin cohesión alta no sirve de mucho. Mira esta clase:

@Service
public class UserService {
    public User createUser(CreateUserRequest req) { ... }
    public void sendWelcomeEmail(User user) { ... }
    public Report generateMonthlyReport() { ... }
    public void syncWithExternalCRM() { ... }
    public byte[] exportToCsv() { ... }
}

Crear usuarios, mandar mails, generar reportes, sincronizar con un CRM y exportar a CSV. ¿Qué tienen en común? Que involucran usuarios. Y eso no es suficiente para estar en la misma clase.

Alta cohesión significa que todo lo que hace una clase está estrechamente relacionado. Los métodos trabajan sobre los mismos datos para el mismo propósito.

@Service
public class UserService {
    public User create(CreateUserRequest req) { ... }
    public User findById(Long id) { ... }
    public User update(Long id, UpdateUserRequest req) { ... }
    public void deactivate(Long id) { ... }
}

@Service
public class UserNotificationService {
    public void sendWelcomeEmail(User user) { ... }
    public void sendDeactivationEmail(User user) { ... }
}

@Service
public class UserExportService {
    public byte[] exportToCsv(UserExportCriteria criteria) { ... }
    public Report generateMonthlyReport() { ... }
}

Cada clase tiene una razón para existir. Cada método trabaja con los mismos conceptos. Eso es cohesión alta.

Si ayer leíste el artículo del God Object, esto te va a sonar familiar. SRP, acoplamiento y cohesión son tres formas de mirar el mismo problema: clases que hacen demasiado y están conectadas a todo.

La regla práctica

Cuando necesitas hacer un cambio, hazte estas tres preguntas:

¿Cuántas clases tengo que tocar? Si son más de 2 o 3, tienes acoplamiento alto.
¿Los métodos de esta clase cambian juntos? Si no, tienes cohesión baja.
¿Estoy compartiendo un objeto entre capas que tienen necesidades diferentes? Si sí, necesitas modelos separados.

El error de fondo

El efecto dominó no es un problema de Spring, ni de Java, ni de ningún framework. Es un problema de diseño. Compartir objetos entre capas porque es "más rápido" y "menos código" funciona al principio. Después pagas el precio cada vez que tocas algo.

Un poco de duplicación explícita (modelos separados por capa) es infinitamente mejor que un acoplamiento implícito que te explota en la cara cuando menos lo esperas.

La próxima vez que vayas a compartir un DTO entre capas, hazte una pregunta: ¿realmente necesitan exactamente los mismos campos? Casi seguro que no.

Día 14 de #100ArchitectureDays.

Día 13: Tu clase tiene 50 métodos. Hace de todo. No hace nada bien.

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:23:16 +0000

Abre tu proyecto. Busca la clase más grande. La que tiene más métodos. La que todos tocan pero nadie entiende del todo. La que cuando entra alguien nuevo al equipo, le dices "no te preocupes por esa, ya la vas a ir entendiendo".

Esa clase tiene nombre técnico. Se llama God Object. Y probablemente le está costando a tu empresa más plata que cualquier bug que hayas corregido en el último año.

Lo mejor (y lo peor) es que no importa el lenguaje, el framework, ni el tamaño del equipo. Esta clase existe en tu proyecto. Solo cambia el nombre.

Esto no es solo de Spring

El anti-pattern es universal. Solo cambia el nombre del archivo:

Java / Spring Boot: OrderService, UserManager, PedidoController
.NET: OrderController con 40 endpoints y 12 servicios inyectados
Node / NestJS: user.service.ts que hace auth, emails, pagos y logging
Python / Django: views.py con 2000 líneas y toda la lógica de negocio
Ruby on Rails: el modelo User con 80 métodos y 15 callbacks
PHP / Laravel: el OrderService que también es PaymentService y MailService

El problema es el mismo: una clase que empezó razonable y se fue inflando con cada feature nueva, porque "total, ya está inyectado acá, le agregamos este método y listo".

Cómo sabes que lo tienes

Tu clase es un God Object si cumple al menos tres de estas:

Tiene más de 5 dependencias en el constructor (o imports/inyecciones).
Mezcla responsabilidades que no se hablan entre sí: validación, emails, PDFs, métricas, integraciones.
Cada merge request en esa clase genera conflictos con otros devs.
Para testear un método hay que mockear media aplicación.
Nadie en el equipo la entiende completa. Todos conocen "su pedazo".

Si las cumples todas, lo siento. Lo tuyo no es una clase, es una pequeña empresa.

El ejemplo clásico

Este es el tipo de clase del que hablamos. Java con Spring Boot, pero el patrón se ve igual en cualquier stack:

@Service
public class OrderService {

    private final OrderRepository orderRepository;
    private final ProductRepository productRepository;
    private final UserRepository userRepository;
    private final EmailClient emailClient;
    private final PdfGenerator pdfGenerator;
    private final MetricsService metricsService;
    private final WarehouseClient warehouseClient;
    private final DiscountEngine discountEngine;
    private final PaymentGateway paymentGateway;
    private final NotificationService notificationService;
    private final AuditLogger auditLogger;

    // Constructor con 11 dependencias...

    public Order createOrder(CreateOrderRequest request) { /* 80 líneas */ }
    public Order updateOrder(Long id, UpdateOrderRequest request) { /* 60 líneas */ }
    public void cancelOrder(Long id) { /* 45 líneas */ }
    public void processPayment(Long orderId) { /* 50 líneas */ }
    public void applyDiscount(Long orderId, String code) { /* 30 líneas */ }
    public byte[] generateInvoice(Long orderId) { /* 40 líneas */ }
    public void sendConfirmationEmail(Long orderId) { /* 25 líneas */ }
    public void notifyWarehouse(Long orderId) { /* 35 líneas */ }
    public void updateMetrics(Long orderId) { /* 20 líneas */ }
    public List<Order> findByUser(Long userId) { /* 15 líneas */ }
    public OrderReport generateReport(DateRange range) { /* 55 líneas */ }
    // ... 40 métodos más
}

Once dependencias, 50+ métodos, un constructor que no entra en la pantalla. Cada cambio es un campo minado.

Por qué duele en el día a día

El problema no es estético, es operacional. Lo sientes cada sprint:

Cada cambio es riesgoso. Tocas el cálculo de descuentos y, no se sabe cómo, rompes el envío de emails. Cuando todo está acoplado, un cambio en una línea tiene efectos en lugares inesperados.
Los tests son un infierno. Para probar un método simple tienes que mockear las 11 dependencias, aunque el método solo use 2.
Los merge conflicts son el pan de cada semana. Si tres devs tocan esta clase en paralelo, los conflictos están garantizados.
Nadie se anima a refactorizarla. Es tan grande y tan usada que el primero que la toque en serio va a romper media aplicación.

Al final, cada feature nueva tarda el doble de lo que debería. Y eso sí se traduce en plata.

La solución: Single Responsibility Principle

SRP no dice "una clase hace una cosa". Dice algo más preciso, y más útil: una clase debe tener una única razón para cambiar.

Lee esa definición de nuevo. "Razón para cambiar" es el criterio. Si tu clase cambia cuando cambia el pricing, cuando cambia el formato del email, y cuando cambia la integración con el warehouse, esas son tres razones para cambiar. Tres clases distintas.

Vamos al refactor. Primero, un OrderService con una sola responsabilidad: gestionar el ciclo de vida de las órdenes.

@Service
public class OrderService {

    private final OrderRepository orderRepository;
    private final OrderValidator orderValidator;
    private final OrderEventPublisher eventPublisher;

    public OrderService(OrderRepository orderRepository,
                        OrderValidator orderValidator,
                        OrderEventPublisher eventPublisher) {
        this.orderRepository = orderRepository;
        this.orderValidator = orderValidator;
        this.eventPublisher = eventPublisher;
    }

    public Order createOrder(CreateOrderRequest request) {
        orderValidator.validate(request);
        Order order = Order.from(request);
        Order saved = orderRepository.save(order);
        eventPublisher.publish(new OrderCreatedEvent(saved));
        return saved;
    }
}

De 11 dependencias a 3. Un método que se lee en 10 segundos. Un propósito claro.

El resto de funcionalidades va a servicios especializados, cada uno con su razón propia para existir:

@Service
public class OrderPricingService {
    private final DiscountEngine discountEngine;

    public Money calculateTotal(Order order, String discountCode) {
        Money subtotal = order.calculateSubtotal();
        Discount discount = discountEngine.resolve(discountCode);
        return discount.applyTo(subtotal);
    }
}

@Service
public class OrderNotificationService {
    private final EmailClient emailClient;
    private final PdfGenerator pdfGenerator;

    @EventListener
    public void onOrderCreated(OrderCreatedEvent event) {
        byte[] invoice = pdfGenerator.generate(event.getOrder());
        emailClient.sendOrderConfirmation(event.getOrder(), invoice);
    }
}

@Service
public class OrderFulfillmentService {
    private final WarehouseClient warehouseClient;

    @EventListener
    public void onOrderCreated(OrderCreatedEvent event) {
        warehouseClient.reserve(event.getOrder().getItems());
    }
}

Cada uno tiene una única razón para cambiar:

OrderPricingService cambia cuando cambian las reglas de pricing.
OrderNotificationService cambia cuando cambia el template del email o el PDF.
OrderFulfillmentService cambia cuando cambia la integración con el warehouse.

El detalle que hace que funcione: eventos

Fíjate que a los servicios secundarios no los llama OrderService. Se suscriben a un evento (OrderCreatedEvent) que OrderService publica.

Esto cambia tres cosas:

OrderService no conoce a OrderNotificationService ni a OrderFulfillmentService. No los importa, no los inyecta, no los llama.
Si mañana agregas un OrderAnalyticsService que escuche el mismo evento, no tocas OrderService. Ni una línea.
Los tests de OrderService solo verifican que el evento se publica, no todo lo que pasa después.

Si tu lenguaje/framework no tiene eventos nativos (Spring @EventListener, NestJS EventEmitter, Django signals, Rails callbacks), funciona igual con un bus de eventos simple. El patrón es el mismo.

La regla del constructor

Si quieres una heurística rápida que puedas aplicar mañana en tu proyecto:

Cuenta las dependencias del constructor de cada clase. Si tiene más de 4 o 5, es sospechoso.

No es un número mágico, pero es un olor fuerte. Piénsalo así: dos clases del mismo proyecto, una con 3 dependencias y otra con 11 — ¿cuál te da más miedo tocar?

Otra señal útil: si puedes agrupar los métodos de una clase en "bloques" que no se comunican entre sí, cada bloque probablemente debería ser su propia clase.

El error al aplicar SRP mal

El error más común es entender SRP como "un método por clase" y terminar con 200 archivos que no significan nada. Eso no es SRP, es fragmentación sin criterio.

SRP agrupa por cohesión: los métodos que trabajan con los mismos datos y cambian por los mismos motivos van juntos. Los que no, se separan.

La regla no es "una clase por método". Es "una clase por responsabilidad".

El resultado

ANTES:   OrderService (50 métodos, 11 dependencias)

DESPUÉS: OrderService             (ciclo de vida)
         OrderPricingService      (precios y descuentos)
         OrderNotificationService (emails y PDFs)
         OrderFulfillmentService  (warehouse)
         OrderReportingService    (reportes y métricas)

Cinco clases pequeñas que puedes testear, entender y modificar de forma independiente. Ninguna con más de 3 dependencias. Ninguna con más de 5 métodos.

La pregunta que tienes que hacerte

Tu God Object no se creó un día. Se fue armando commit a commit, con la lógica razonable de "ya está acá, le agrego este método y listo". Nadie diseña un monstruo de 50 métodos a propósito.

La próxima vez que vayas a agregar un método a una clase existente, hazte esta pregunta:

¿Esta clase cambiaría por el mismo motivo por el que estoy agregando este método?

Si la respuesta es sí, adelante. Si es no, ese método tiene otro hogar.

Con eso, ya tienes la mitad del SRP aplicado en la práctica.

Día 13 de #100ArchitectureDays.

Día 12: 5.000 personas hicieron click al mismo tiempo. Tu servidor pidió perdón.

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:22:56 +0000

Tu tienda online sale a internet. Llevas meses preparándote. La campaña de marketing hizo su trabajo. 5.000 personas están esperando con el dedo en el botón de "Comprar". La cuenta regresiva llega a cero. Todos hacen click al mismo tiempo.

Tu servidor tiene 20 threads. Se saturan en menos de un segundo. Los otros 4.980 requests se encolan. Empiezan los timeouts. El login deja de funcionar. La página de inicio no carga. El botón de "Comprar" gira y gira. La gente empieza a refrescar. Cada refresh son más requests. Más cola. Más timeouts. El ciclo se retroalimenta.

En 3 minutos, lo que iba a ser tu mejor día se convirtió en tu peor pesadilla.

No es un problema de capacidad. Es un problema de control.

La reacción instintiva es "necesitamos más servidores". Y sí, tal vez. Pero el problema real es otro: tu API no tiene límites. Cualquier cliente puede hacer las requests que quiera, a la velocidad que quiera. No hay semáforo. No hay velocidad máxima. No hay nada que diga "para un poco".

Esto no es exclusivo del lanzamiento de una tienda. Es el mismo problema cuando:

Un bot descubre tu API y la empieza a scrapear
Un frontend con un bug hace polling cada 100ms en vez de cada 10 segundos
Un partner de integración reintenta sin backoff exponencial
Un usuario frustrado martillea F5 porque la página "no carga"

Sin rate limiting, tu API es un buffet libre donde un solo comensal se puede comer toda la comida y dejar a los demás sin nada.

Rate limiting: el concepto

La idea es simple: poner un límite a cuántas requests puede hacer cada cliente en un período de tiempo. Si lo supera, la API le responde con un error claro (HTTP 429 — Too Many Requests) en vez de intentar procesar todo y colapsar.

El algoritmo más usado se llama Token Bucket y funciona así:

Cada cliente tiene un "balde" con N tokens
Cada request consume 1 token
Los tokens se regeneran a velocidad constante (por ejemplo, 50 por minuto)
Si el balde está vacío, la request se rechaza con 429

Es elegante porque permite ráfagas cortas (si el balde está lleno, puedes hacer varias requests rápidas) pero limita el tráfico sostenido.

Este algoritmo lo usan:

AWS API Gateway — Token Bucket con burst
Stripe API — 100 requests por segundo por defecto
GitHub API — 5.000 requests por hora para autenticados
Twitter/X API — Rate limits por endpoint y por ventana de tiempo
Cloudflare — Token Bucket configurable por zona
nginx — limit_req con leaky bucket (variante similar)

No es un concepto oscuro ni experimental. Es infraestructura estándar que cualquier API pública del mundo implementa. La pregunta no es "¿necesito rate limiting?" — es "¿por qué todavía no lo tengo?"

Implementación: cómo se ve

En cualquier lenguaje, rate limiting es un filtro que se ejecuta ANTES de tu lógica de negocio. Si el cliente ya superó su límite, ni siquiera llegas al controller.

La implementación del Token Bucket en Java es sorprendentemente simple:

public class TokenBucket {

    private final long capacity;
    private final double refillRatePerMs;
    private double tokens;
    private long lastRefillTimestamp;

    public TokenBucket(long capacity, long refillPerMinute) {
        this.capacity = capacity;
        this.refillRatePerMs = refillPerMinute / 60000.0;
        this.tokens = capacity;
        this.lastRefillTimestamp = System.currentTimeMillis();
    }

    public synchronized boolean tryConsume() {
        refill();
        if (tokens >= 1) {
            tokens--;
            return true;
        }
        return false;
    }

    private void refill() {
        long now = System.currentTimeMillis();
        double newTokens = (now - lastRefillTimestamp) * refillRatePerMs;
        tokens = Math.min(capacity, tokens + newTokens);
        lastRefillTimestamp = now;
    }
}

En Python con Flask sería un decorator. En Node con Express un middleware. En Go un middleware con golang.org/x/time/rate. El patrón es idéntico: interceptar, verificar, dejar pasar o rechazar.

Aplicándolo al escenario de la tienda

Volvamos al lanzamiento. Lo que necesitas es:

@Component
public class RateLimitFilter implements Filter {

    private final Map<String, TokenBucket> buckets = new ConcurrentHashMap<>();

    @Override
    public void doFilter(ServletRequest req, ServletResponse res,
                         FilterChain chain) throws IOException, ServletException {

        HttpServletRequest request = (HttpServletRequest) req;
        HttpServletResponse response = (HttpServletResponse) res;

        String clientIp = request.getRemoteAddr();
        String path = request.getRequestURI();

        TokenBucket bucket = buckets.computeIfAbsent(
            clientIp + ":" + path, k -> crearBucket(path));

        if (bucket.tryConsume()) {
            response.setHeader("X-Rate-Limit-Remaining",
                String.valueOf(bucket.getAvailableTokens()));
            chain.doFilter(req, res);
        } else {
            response.setStatus(429);
            response.setHeader("Retry-After", "10");
            response.getWriter().write("Too Many Requests");
        }
    }
}

Ahora cada IP tiene un límite. Los primeros 10 "Comprar" pasan. Del 11 en adelante reciben un 429 limpio en milisegundos, sin ocupar threads, sin tocar la base de datos, sin degradar el servicio para los demás.

Límites diferentes para rutas diferentes

No todos los endpoints son iguales. El endpoint de compra necesita protección fuerte (stock limitado, procesamiento pesado). El listado de productos puede ser más generoso:

Endpoint	Límite	Razón
`/comprar`	10/min	Proteger stock, procesamiento de pago
`/productos`	60/min	Lectura, ligero
`/login`	5/min	Prevención de fuerza bruta
`/imágenes`	100/min	Assets estáticos (mejor en CDN)

Los headers que el cliente necesita

Cuando rechazas una request con 429, sé un buen ciudadano HTTP. Dile al cliente cuándo puede reintentar:

HTTP/1.1 429 Too Many Requests
Retry-After: 10
X-Rate-Limit-Limit: 50
X-Rate-Limit-Remaining: 0

El frontend (o el bot, o el partner de integración) puede leer estos headers y adaptarse: mostrar un mensaje al usuario, implementar backoff, o simplemente dejar de disparar requests.

Los números del escenario de la tienda

	Sin rate limit	Con rate limit
Requests en ráfaga	5.000 simultáneas	10/min por IP
Latencia p95 (otros endpoints)	2.800ms	180ms
CPU promedio en pico	95%	45%
Disponibilidad bajo carga	78%	99.5%

El rate limiting no hizo que "Comprar" fuera más rápido. Hizo que todo lo demás siguiera funcionando. El login, la página de inicio, el carrito — todo siguió vivo porque un grupo de clientes impacientes no pudo agotar los recursos del servidor.

¿Rate limiting en el backend o en el API Gateway?

En un sistema real, generalmente lo quieres en ambos:

API Gateway / Load Balancer (nginx, AWS API Gateway, Cloudflare): Primera línea de defensa. Bloquea tráfico malicioso antes de que llegue a tu app. Protege contra DDoS.
Aplicación (tu código): Segunda línea. Límites específicos por lógica de negocio (por ejemplo, máximo 3 compras del mismo producto por usuario para evitar acaparadores).

El gateway protege tu infraestructura. Tu app protege tu negocio.

Rate limiting no es hostilidad

Esto es importante: rate limiting no es ser malo con tus clientes. Es proteger la experiencia de todos tus clientes. Incluyendo los que no están haciendo nada mal.

Es como el límite de velocidad en una autopista. No existe para molestarte. Existe para que la autopista funcione para todos.

Una API sin rate limiting es una autopista sin límite de velocidad. Funciona bien con poco tráfico. El día que aparece un camión, un bot, o 5.000 personas emocionadas — se pudre todo.

Esto es el Día 12

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. Si tu API no tiene rate limiting, el próximo bot, el próximo lanzamiento, o el próximo Black Friday te va a recordar por qué lo necesitas.

Sigue la saga completa en #100ArchitectureDays.

Todo el código está en GitHub — con una implementación manual del Token Bucket sin dependencias externas para que entiendas el algoritmo por dentro. Si te está sirviendo, déjame una estrella — es gratis y ayuda a que más gente lo encuentre.

Día 11: System.out.println en producción — la confesión que nadie hace

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:22:17 +0000

Son las 3 de la mañana. Producción está caído. Abres los logs. 50.000 líneas de System.out.println que dicen cosas como "entró al método", "valor: " + algo, "pasó por acá". Ninguna tiene timestamp. Ninguna tiene nivel de severidad. Ninguna te dice qué request generó ese log.

Bienvenido a tu propia pesadilla. La diseñaste tú mismo.

Y antes de que digas "yo no hago eso" — haz un grep rápido de System.out.println en tu proyecto. O de console.log si estás en Node. O de print() sin logging si estás en Python. El resultado te va a sorprender.

Esto no es solo de Java

El anti-pattern es universal. Cada lenguaje tiene su versión:

Java: System.out.println en vez de SLF4J/Logback
JavaScript/Node: console.log en vez de Winston/Pino
Python: print() en vez del módulo logging
Go: fmt.Println en vez de log/slog o Zap
Ruby: puts en vez de Logger
.NET: Console.WriteLine en vez de ILogger

El problema es el mismo en todos los casos: estás imprimiendo texto plano a stdout sin estructura, sin niveles, sin metadata. Parece que estás logueando. Pero cuando lo necesitas de verdad, descubres que lo que tienes es ruido.

Por qué System.out.println destruye tu producción

No es solo que no tenga metadata. Es que afecta el rendimiento:

Es sincrónico — cada println bloquea el thread hasta que el output se flushea. Con 200 threads concurrentes, todos escribiendo a stdout, creas contención en un recurso compartido.
No tiene niveles — no puedes filtrar. ¿Quieres ver solo errores? Imposible. Es todo o nada.
No tiene contexto — cuando 100 requests concurrentes imprimen "Procesando pago...", no sabes cuál es cuál.
No rota — stdout no tiene rotación de archivos. Si redireccionas a un archivo, crece hasta llenar el disco.

El ANTES: el caos

@Service
public class PagoService {

    public PagoResponse procesarPago(PagoRequest request) {
        System.out.println("Procesando pago...");
        System.out.println("Monto: " + request.getMonto());
        System.out.println("Cliente: " + request.getClienteId());

        try {
            var resultado = gateway.cobrar(request);
            System.out.println("Pago OK: " + resultado.getId());
            return resultado;
        } catch (Exception e) {
            System.out.println("Error en pago: " + e.getMessage());
            throw e;
        }
    }
}

En producción esto se ve así:

Procesando pago...
Monto: 15000
Procesando pago...
Cliente: 4821
Monto: 8700
Error en pago: timeout
Cliente: 9102
Pago OK: TXN-44291
Procesando pago...

¿Qué pago falló? ¿De qué cliente? ¿A qué hora? No tienes idea. Los logs de distintos requests se mezclan. Es ruido puro.

El DESPUÉS: logging con sentido

@Service
public class PagoService {

    private static final Logger log = LoggerFactory.getLogger(PagoService.class);

    public PagoResponse procesarPago(PagoRequest request) {
        log.info("Procesando pago. clienteId={}, monto={}",
                 request.getClienteId(), request.getMonto());

        try {
            var resultado = gateway.cobrar(request);
            log.info("Pago exitoso. txnId={}, clienteId={}",
                     resultado.getId(), request.getClienteId());
            return resultado;
        } catch (Exception e) {
            log.error("Fallo al procesar pago. clienteId={}, monto={}",
                      request.getClienteId(), request.getMonto(), e);
            throw e;
        }
    }
}

Ahora los logs se ven así:

2026-04-13 03:14:22.841 INFO  [http-nio-8080-exec-7] c.a.s.PagoService : Procesando pago. clienteId=4821, monto=15000
2026-04-13 03:14:23.102 ERROR [http-nio-8080-exec-3] c.a.s.PagoService : Fallo al procesar pago. clienteId=9102, monto=8700
java.net.SocketTimeoutException: timeout
    at com.app.gateway.GatewayClient.cobrar(GatewayClient.java:45)

Cada línea tiene timestamp, nivel, thread, clase y datos estructurados. En 2 segundos sabes qué falló, cuándo y para quién.

Los niveles no son decoración

Cada framework de logging tiene los mismos niveles. La tabla aplica a cualquier lenguaje:

Nivel	Cuándo usarlo	Ejemplo
ERROR	Algo falló y necesita atención	Error al procesar pago, conexión perdida
WARN	Algo raro pero la app sigue	Retry #3, cache miss inesperado
INFO	Eventos de negocio relevantes	Pago procesado, usuario creado
DEBUG	Detalle técnico para troubleshooting	Query ejecutada, payload recibido
TRACE	Todo lo demás (casi nunca en prod)	Entrada/salida de cada método

La regla: en producción corres en INFO. Si hay un problema, subes un paquete específico a DEBUG sin reiniciar. En Spring Boot, Actuator te permite cambiar niveles de log en caliente:

curl -X POST localhost:8080/actuator/loggers/com.tuapp.gateway \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "DEBUG"}'

Sin redeploy. Sin restart. Cambias el nivel, miras los logs, resuelves el problema, vuelves a INFO.

En Node con Winston es similar: cambias el level del transport en runtime. En Python con logging.getLogger().setLevel(). El concepto es el mismo en todos lados.

Structured logging: el salto de calidad

Si tus logs van a un ELK Stack, Datadog, CloudWatch o cualquier herramienta de observabilidad, el formato texto plano es un problema. Lo que necesitas es JSON:

{
  "timestamp": "2026-04-13T03:14:23.102Z",
  "level": "ERROR",
  "logger": "com.tuapp.service.PagoService",
  "message": "Fallo al procesar pago",
  "clienteId": 9102,
  "monto": 8700,
  "stack_trace": "java.net.SocketTimeoutException..."
}

Buscable. Filtrable. Alertable. Puedes hacer queries como "dame todos los ERROR del PagoService en la última hora donde monto > 10000". Intenta hacer eso con System.out.println.

En Spring Boot se configura con Logstash encoder. En Node con Pino (que ya sale en JSON por default). En Python con python-json-logger. En Go con slog (que viene integrado desde Go 1.21).

Lo que NO deberías loguear

Antes de loguear todo, un segundo:

Passwords, tokens, API keys. Jamás. Ni en DEBUG. log.debug("Token: {}", token) es un incidente de seguridad esperando a pasar.
Datos personales sensibles. DNI, tarjetas de crédito, datos médicos. Si tu log tiene PII, tienes un problema de compliance.
El request body completo. Un JSON de 2MB en cada log llena tu disco en horas.
Datos que no ayudan a diagnosticar nada. "Entró al método" no es información. "Procesando pedido 4821 para cliente 102" sí lo es.

El error de fondo

System.out.println te da una falsa sensación de visibilidad. Parece que estás logueando. Parece que tienes información. Pero cuando la necesitas de verdad, a las 3AM con producción caído, descubres que lo que tienes es ruido.

Logging profesional no es difícil. Todos los lenguajes y frameworks modernos ya tienen las herramientas listas. Solo tienes que dejar de usar print y empezar a pensar qué información necesitarías para diagnosticar un problema que todavía no pasó.

Haz un grep de System.out.println en tu proyecto. Si aparece más de cero veces en código de producción, tienes tarea.

Esto es el Día 11

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales.

Sigue la saga completa en #100ArchitectureDays.

Todo el código está en GitHub — con el BEFORE/AFTER para que veas la diferencia en la consola en tiempo real. Si te está sirviendo, déjame una estrella — es gratis y ayuda a que más gente lo encuentre.

Día 10: Le pusiste índices a todo y ahora los INSERT tardan 800ms

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:22:03 +0000

Antes de arrancar, una confesión: a mí no me gustan las bases de datos. Me aburren. Prefiero escribir código de negocio, diseñar arquitecturas, resolver problemas de integración. Pero justamente por eso aprendí a respetarlas. Porque cada vez que las ignoré, me mordieron. Fuerte.

Hoy toca hablar de índices. Un tema que muchos consideran aburrido y que termina siendo un infierno en producción.

La historia típica es esta: alguien en el equipo corre un EXPLAIN, ve un full table scan, y la solución parece obvia: "ponle un índice". Funciona. La query pasa de 3 segundos a 40 milisegundos. Eureka.

Entonces le ponen índice a la siguiente columna. Y a la siguiente. Y a la siguiente. Seis meses después, los INSERT tardan 800ms y nadie entiende por qué.

Bienvenido al anti-pattern más común en bases de datos: indexar todo por si acaso.

Qué es un índice (y por qué cuesta)

Antes de hablar de código, el concepto. Porque esto no es exclusivo de MySQL ni de PostgreSQL — es de cualquier base de datos que hayas usado o vayas a usar.

Un índice es una estructura de datos adicional que la base mantiene en paralelo a tu tabla. Generalmente es un B-tree (o un B+tree) que ordena los valores de una columna para que buscar uno específico sea logarítmico en vez de lineal.

Acelera las lecturas. Eso está claro.

Lo que nadie te cuenta es el otro lado: cada índice hay que mantenerlo actualizado en cada escritura. Cuando haces un INSERT, la base no solo escribe la fila — actualiza todos los índices de esa tabla. Cada uno. Uno por uno.

Si tienes 12 índices, cada INSERT tiene que actualizar 12 estructuras de datos. Cada UPDATE que toque una columna indexada recalcula ese índice. Cada DELETE limpia la fila y limpia los índices asociados.

No es gratis. Nunca fue gratis.

Y esto aplica en:

PostgreSQL (B-tree, GIN, GiST, BRIN)
MySQL / MariaDB (B-tree, Hash, Full-text)
Oracle (B-tree, Bitmap)
SQL Server (Clustered, Non-clustered)
MongoDB (B-tree, compound, text, geospatial)
DynamoDB (local + global secondary indexes)

Cambia la sintaxis. Cambia el engine. El tradeoff es idéntico: escrituras más caras a cambio de lecturas más baratas.

El ANTES: la tabla navideña

Mira esta entidad. Dime si no te suena de algún proyecto:

@Entity
@Table(name = "pedidos", indexes = {
    @Index(name = "idx_cliente",     columnList = "clienteId"),
    @Index(name = "idx_fecha",       columnList = "fecha"),
    @Index(name = "idx_estado",      columnList = "estado"),
    @Index(name = "idx_total",       columnList = "total"),
    @Index(name = "idx_moneda",      columnList = "moneda"),
    @Index(name = "idx_sucursal",    columnList = "sucursal"),
    @Index(name = "idx_vendedor",    columnList = "vendedorId"),
    @Index(name = "idx_canal",       columnList = "canal"),
    @Index(name = "idx_prioridad",   columnList = "prioridad"),
    @Index(name = "idx_tipo",        columnList = "tipo")
})
public class Pedido {
    @Id @GeneratedValue
    private Long id;
    private Long clienteId;
    private LocalDate fecha;
    private String estado;
    private BigDecimal total;
    private String moneda;
    private String sucursal;
    private Long vendedorId;
    private String canal;
    private String prioridad;
    private String tipo;
}

Diez índices. Para una tabla transaccional que recibe miles de INSERTs por hora. Cada escritura paga el costo de mantener diez B-trees actualizados. Todos. Para cada fila.

Alguien los puso en algún momento pensando "por si acaso alguien quiere buscar por canal". Nadie nunca buscó por canal. Pero el índice sigue ahí, encareciendo cada escritura, consumiendo disco, ralentizando los backups.

El DESPUÉS: solo lo que importa

@Entity
@Table(name = "pedidos", indexes = {
    @Index(name = "idx_cliente_fecha", columnList = "clienteId, fecha"),
    @Index(name = "idx_estado",        columnList = "estado")
})
public class Pedido {
    // mismos campos
}

Dos índices. Uno compuesto que cubre el 80% de las queries reales (buscar pedidos de un cliente en un rango de fechas) y otro para el filtro por estado que el dashboard usa todo el tiempo.

Nada más. El resto de las columnas no necesitan índice porque nadie las filtra en producción.

Los números del benchmark

	ANTES (10 índices)	DESPUÉS (2 índices)	Mejora
INSERT 5K registros	~1240ms	~380ms	69%
SELECT por cliente	~5ms	~5ms	Sin cambio
Espacio en disco	2.1 GB	380 MB	82%

Los SELECTs apenas cambiaron porque los 8 índices que sacamos casi nunca se usaban. Estaban ahí consumiendo disco y frenando escrituras sin que nadie los necesitara.

El código de este benchmark está en el repo — puedes correrlo y ver los números reales en tu máquina. Cambia la cantidad de registros para ver cómo escala la diferencia.

Las 4 reglas para decidir qué indexar

Regla 1: Mira las queries reales, no las que imaginas

El error más común es indexar en teoría. "Por si acaso alguien consulta por sucursal". Nadie va a consultar por sucursal. Pero el índice está ahí, encareciendo cada escritura para una query que no existe.

Mira lo que tu app hace de verdad:

-- PostgreSQL: las queries más lentas
SELECT query, calls, mean_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

-- MySQL: queries que hacen full scan
SELECT * FROM sys.statements_with_full_table_scans
ORDER BY no_index_used_count DESC;

-- MongoDB: queries lentas
db.system.profile.find({millis: {$gt: 100}}).sort({ts: -1});

Si no hay una query real que use esa columna en un WHERE, JOIN o ORDER BY, no necesitas el índice. Punto.

Regla 2: Los índices compuestos son tu mejor amigo

Un índice compuesto en (clienteId, fecha) cubre automáticamente:

WHERE clienteId = ? → usa la primera columna
WHERE clienteId = ? AND fecha > ? → usa ambas
ORDER BY clienteId, fecha → usa ambas
WHERE clienteId = ? ORDER BY fecha → usa ambas

Un índice por separado en clienteId y otro en fecha no dan el mismo resultado. El optimizador elige uno de los dos, no los combina mágicamente. Un índice compuesto bien pensado reemplaza 2 o 3 índices individuales.

Regla 3: Las columnas de baja cardinalidad casi nunca justifican un índice solo

Un campo estado con 4 valores posibles (PENDIENTE, PROCESADO, ENVIADO, CANCELADO) filtra el 25% de la tabla por valor. En tablas grandes, eso sigue siendo un montón de filas. El optimizador a veces decide ignorar el índice y hacer un full scan porque es más rápido.

Lo mismo con booleanos. Un índice en una columna activo donde el 90% es true es inútil — la query va a tocar el 90% de las filas de todas formas.

Si insistes en indexar una columna de baja cardinalidad, combínala con otra columna más selectiva en un índice compuesto.

Regla 4: La regla del 5%

Si una query devuelve más del 5% de las filas de la tabla, el optimizador probablemente ignore el índice y haga un full scan. Porque leer un 5% de la tabla ordenada secuencialmente es más rápido que saltar de un lado a otro siguiendo un B-tree.

Los índices son para queries selectivas. Si tu filtro es "tráeme el 80% de las filas", indexar no ayuda.

La pregunta clave antes de crear un índice

Antes de crear un índice, pregúntate: ¿esta tabla recibe más lecturas o más escrituras?

Tabla de productos / catálogo: miles de lecturas por segundo, pocas escrituras por día. Ponle los índices que quieras. Los reads valen mucho y los writes casi no duelen.
Tabla de eventos / logs / auditoría: miles de escrituras por segundo, lecturas ocasionales para reportes. Cada índice duele mucho. Indexa lo mínimo indispensable.
Tabla de pedidos / transacciones: escrituras Y lecturas frecuentes. Aquí es donde tienes que ser quirúrgico. Indexa lo que las queries reales necesitan, nada más.

No hay una respuesta universal. Hay tradeoffs. Tu trabajo es entenderlos, no ignorarlos.

El error de fondo

El problema nunca fue "faltan índices". El problema fue no preguntarse cuáles.

Poner un índice en cada columna es como poner un semáforo en cada esquina — en algún momento, el remedio es peor que la enfermedad.

Un índice es un contrato: "acepto pagar más en cada escritura para ganar velocidad en esta lectura específica". Si no sabes cuál es la lectura que estás optimizando, no firmes el contrato.

Esto es el Día 10

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. La próxima vez que alguien diga "ponle un índice", pregúntale dos cosas: ¿a cuál columna? y ¿por qué?. Si no puede responder las dos, no hay que indexar nada todavía.

Sigue la saga completa en #100ArchitectureDays.

Todo el código está en GitHub — con un benchmark que puedes correr para ver en vivo cómo los índices de más frenan los INSERTs. Si te está sirviendo, déjame una estrella — es gratis y ayuda a que más gente lo encuentre.

Día 9: Tu app funcionó todo el QA. El lunes a las 9am explotó con 100 usuarios.

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:21:48 +0000

Viernes, 18:00. Deploy a producción. Todo anda perfecto con el equipo de testing. El lunes a las 9:00 entran 100 usuarios reales y la app escupe:

SQLTransientConnectionException: Connection is not available,
request timed out after 30000ms

El pool de conexiones se quedó sin stock. Y nadie configuró nada porque "Spring Boot se encarga de eso".

Si esto te suena familiar, seguí leyendo.

Qué es un connection pool (y por qué existe)

Antes de hablar de código, necesitamos entender de qué estamos hablando. Porque este problema no es de Spring ni de Java — es de cualquier aplicación que hable con una base de datos.

Abrir una conexión a una base de datos es caro. Cada conexión implica:

Un TCP handshake (3 roundtrips de red)
Autenticación (usuario, password, negociación SSL si aplica)
Negociación de protocolo con el servidor
Alocación de recursos en el lado del servidor

Todo junto puede tardar 50-100ms. Si tu endpoint abre y cierra una conexión por cada request, con 100 requests por segundo estás creando 100 conexiones nuevas por segundo. Eso mata a la base de datos.

La solución existe desde los 90s y es universal: un connection pool. Creás N conexiones al inicio, las dejás abiertas, y las reutilizás. Cuando tu código necesita una conexión, la pide prestada del pool. Cuando termina, la devuelve. Nadie abre ni cierra nada.

Cada lenguaje tiene su implementación:

Java: HikariCP (el que usa Spring Boot por defecto), C3P0, Apache DBCP
Python: SQLAlchemy Pool, psycopg2 pool, Django lo maneja internamente
Node.js: pg-pool, mysql2 pool, Prisma tiene pool integrado
Go: el database/sql del stdlib maneja el pool automáticamente
Ruby: ActiveRecord tiene pool integrado
.NET: el ADO.NET tiene pooling automático

La herramienta cambia. El concepto es idéntico: no crear conexiones nuevas, reusar las que ya tenés.

El primer error: no configurarlo

La configuración por defecto de HikariCP en Spring Boot es:

maximum-pool-size: 10     # Máximo 10 conexiones
connection-timeout: 30000 # 30 segundos esperando una conexión

10 conexiones. Para una app con 100 usuarios concurrentes donde cada request tarda 200ms en la query, eso significa que podés procesar 50 requests por segundo (10 conexiones / 0.2 seg). Suena bien.

Pero si un endpoint tiene una query que tarda 2 segundos — un reporte, una búsqueda compleja, una transacción larga — esas 10 conexiones sirven 5 requests por segundo. El resto espera. Y si más de 10 requests llegan al mismo tiempo, alguno va a esperar 30 segundos completos y explotar con timeout.

El segundo error (el grave): connection leaks

Peor que tener pocas conexiones es perder conexiones. Un connection leak pasa cuando tu código pide una conexión del pool y nunca la devuelve.

// NUNCA hagas esto
public List<Reporte> generar() {
    Connection conn = dataSource.getConnection();
    PreparedStatement stmt = conn.prepareStatement("SELECT ...");
    ResultSet rs = stmt.executeQuery();
    return mapear(rs);
    // Si hubo una excepción arriba, conn.close() nunca se llama
    // La conexión queda colgada. Para siempre.
}

Este patrón — en cualquier lenguaje — es una bomba de tiempo. Cada error deja una conexión huérfana. Después de 10 errores, tu pool está vacío. La app entera se cae, no solo este endpoint.

El síntoma clásico:

"Funciona un rato y después se cuelga. Si reiniciamos el pod, vuelve a andar."

Reiniciar el pod limpia el pool. Pero el leak sigue ahí, esperando.

La versión correcta

En Spring Boot, nunca llames a dataSource.getConnection() directamente. Usá JdbcTemplate:

@Service
public class ReporteService {

    private final JdbcTemplate jdbcTemplate;

    public ReporteService(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    public List<Reporte> generar() {
        return jdbcTemplate.query(
            "SELECT id, nombre, total FROM reportes WHERE fecha > ?",
            (rs, rowNum) -> new Reporte(
                rs.getLong("id"),
                rs.getString("nombre"),
                rs.getBigDecimal("total")
            ),
            LocalDate.now().minusDays(30)
        );
    }
}

JdbcTemplate maneja la conexión por vos. La pide, la usa, y la devuelve. Siempre. Incluso si hay una excepción. Si usás JPA/Hibernate, @Transactional hace lo mismo.

Este patrón se repite en todos los lenguajes:

Python: usá with connection.cursor() (context manager)
Node.js: usá pool.query(), nunca pool.connect() sin .release()
Go: usá db.Query(), no db.Conn()
Ruby: ActiveRecord maneja todo, no pelees contra él

La regla universal: dejá que el framework maneje el ciclo de vida de la conexión.

Leak detection: tu seguro de vida

HikariCP tiene una funcionalidad que te salva de los leaks silenciosos:

spring:
  datasource:
    hikari:
      leak-detection-threshold: 60000  # 60 segundos

Si una conexión lleva más de 60 segundos sin ser devuelta, HikariCP te lo dice en los logs con un stack trace completo de quién la pidió:

[WARN] HikariPool-1 - Connection leak detection triggered for
  on thread http-nio-8080-exec-7, stack trace follows:
    java.lang.Exception: Apparent connection leak detected
      at com.example.ReporteService.generar(ReporteService.java:23)

Archivo, línea, thread. No más adivinar. Activalo siempre. Es gratis y te va a salvar una noche de guardia.

La matemática del pool size (el punto que nadie entiende)

Todos quieren saber: "¿cuántas conexiones necesito?" La intuición dice: más es mejor. La intuición está equivocada.

La fórmula del autor de HikariCP:

connections = ((core_count * 2) + effective_spindle_count)

Para un servidor de base de datos con 4 cores y un SSD:

conexiones = (4 * 2) + 1 = 9

Sí. 9 conexiones. En un pool bien configurado, 9 conexiones pueden manejar miles de requests por segundo.

¿Por qué? Porque la base de datos solo puede hacer trabajo real en paralelo hasta cierto límite. Si tu servidor tiene 4 cores, más de 8-10 queries concurrentes empiezan a pelearse por CPU. Agregás más context switches, más locks, más contención. Más conexiones no te da más throughput — te da menos.

La clave no es tener muchas conexiones. Es devolverlas rápido.

La configuración que recomiendo

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 10000       # 10 seg, no 30
      idle-timeout: 300000            # 5 min
      max-lifetime: 1200000           # 20 min
      leak-detection-threshold: 60000
      pool-name: mi-app-pool

¿Por qué estos valores?

20 conexiones: suficiente para la mayoría de apps CRUD. Ajustá según tu caso.
minimum-idle 5: no mantengas 20 conexiones abiertas a las 3am cuando no hay nadie.
connection-timeout 10s: si en 10 segundos no hay conexión, algo está mal. Fallá rápido.
max-lifetime 20min: las conexiones se renuevan para evitar firewalls que matan conexiones idle.
pool-name: cuando tengas múltiples datasources, saber cuál es cuál vale oro.

Métricas que tenés que mirar

Con Actuator + Micrometer tenés estas métricas en tiempo real:

hikaricp.connections.active    → Conexiones en uso ahora
hikaricp.connections.idle      → Conexiones disponibles
hikaricp.connections.pending   → Threads esperando conexión
hikaricp.connections.timeout   → Timeouts acumulados

Reglas simples para leer estas métricas:

Si pending > 0 de forma sostenida → tu pool es chico
Si timeout crece → tenés un problema serio (leak o pool agotado)
Si active está siempre al máximo → estás al límite
Si idle nunca baja de minimum-idle → todo bien

Cuándo NO tocar el pool size

Para "mejorar performance" sin datos — Subir de 10 a 100 conexiones no hace tu app más rápida. Probablemente la haga más lenta.
Sin medir primero — Si no sabés cuántas conexiones activas tenés en promedio, no sabés si necesitás más. Medí antes de tocar.
Cuando el problema es un leak — Más conexiones solo te dan más tiempo antes de que explote. Arreglá el leak.
Sin coordinar con el DBA — Si tu base soporta 100 conexiones y vos configurás 80 en cada instancia con 3 instancias, le estás pidiendo 240 conexiones a una base que soporta 100. Boom.

Esto es el Día 9

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. Si tu app dice "too many connections", el problema no es el límite. Es cuánto tardás en devolver cada una.

La próxima vez que alguien te diga "hay que subir el pool size", preguntale dos cosas: ¿cuántas conexiones activas hay en promedio? ¿cuánto tardan las queries? Si no puede responder las dos, no hay que subir nada. Hay que medir.

Seguí la saga completa en #100ArchitectureDays.

Todo el código está en GitHub — con un demo del leak funcionando para que lo veas romper en vivo. Si te está sirviendo, dejame una estrella — es gratis y ayuda a que más gente lo encuentre.

Día 8: El usuario subió un Excel y tu servidor pidió perdón

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:21:30 +0000

El usuario sube un Excel con 500.000 filas. Tu endpoint lo lee, lo procesa, y le devuelve el resultado. Sincrónicamente. En el mismo thread del request HTTP.

El browser muestra "esperando respuesta del servidor" durante 4 minutos. El load balancer corta por timeout a los 60 segundos. La app se come 2GB de memoria. El pod se reinicia. El usuario vuelve a intentar. Y así tres veces.

Si esto te suena familiar, seguí leyendo.

HTTP no fue diseñado para esto

Antes de hablar de código, necesitamos hablar de algo más fundamental: HTTP es un protocolo de request-response diseñado para respuestas rápidas. Millisegundos, tal vez segundos. No minutos.

Cuando metés una operación de 4 minutos dentro de un request HTTP, estás peleando contra todo el stack:

El load balancer tiene un timeout (generalmente 60 segundos)
El proxy tiene un timeout
El browser tiene un timeout
La conexión TCP tiene un timeout
Tu thread pool tiene un límite de threads

Todo conspira contra vos. Y no es un bug — es que estás usando la herramienta equivocada para el trabajo.

Es como mandar un paquete de 200 kilos por correo postal. Técnicamente podrías. Pero no fue diseñado para eso. Necesitás un flete.

El patrón universal: recibí, encolá, procesá, notificá

La solución no es "hacer que tarde menos". La solución es cambiar la arquitectura. Y el patrón es el mismo en cualquier lenguaje:

1. RECIBIR  → Aceptar el request, validar lo básico
2. ENCOLAR  → Generar un ID de job, responder inmediatamente
3. PROCESAR → En background, en batches, con progreso
4. NOTIFICAR → El usuario consulta el estado o recibe una notificación

Esto existe en todos lados:

Python/Django: Celery + Redis como broker
Node.js: Bull/BullMQ con Redis, o AWS SQS
Go: Goroutines + channels, o temporal.io para workflows complejos
Ruby/Rails: Sidekiq
Java/Spring: @Async + ThreadPoolExecutor, o Spring Batch para escenarios pesados
.NET: Hangfire, o Azure Functions

La herramienta cambia. El patrón es idéntico: no proceses en el thread del request HTTP.

El crimen contra la arquitectura

Mirá este endpoint. Parece inocente. Es un desastre:

@PostMapping("/importar")
public ResponseEntity<String> importar(@RequestParam MultipartFile archivo) {
    List<Registro> registros = parser.parsear(archivo); // 500K filas en memoria
    for (Registro r : registros) {
        validar(r);
        transformar(r);
        guardar(r);               // 500K INSERTs, uno por uno
    }
    return ResponseEntity.ok("Listo");
}

Contemos los problemas:

Todo en memoria: 500K objetos Java. Si cada uno pesa 1KB, son 500MB solo en datos. Más los objetos temporales, fácilmente llegás a 2GB.
Todo secuencial: un registro a la vez. Si cada INSERT tarda 2ms, son 1000 segundos. Más de 16 minutos.
Todo síncrono: el usuario espera con el browser abierto. El thread HTTP queda bloqueado.
Cero feedback: el usuario no sabe si va por el registro 100 o el 499.999.
Todo o nada: si falla en la fila 499.999, ¿perdiste todo? ¿Hacés rollback de 499.998 registros?

La versión que respeta al usuario (y al servidor)

Paso 1: Recibí y respondé inmediatamente

@PostMapping("/importar")
public ResponseEntity<ImportacionResponse> importar(
        @RequestParam MultipartFile archivo) {

    String jobId = importacionService.encolar(archivo);

    return ResponseEntity.accepted().body(
        new ImportacionResponse(jobId, "PROCESANDO",
            "/importaciones/" + jobId + "/estado")
    );
}

El usuario sube el archivo y en menos de un segundo recibe un ID de trabajo y una URL para consultar el progreso. No espera. No hay timeout. No hay pantalla de "cargando" durante 4 minutos.

HTTP 202 Accepted — "recibí tu pedido, te aviso cuando esté". Ese es el status code correcto para operaciones asíncronas. No 200. No 201. 202.

Paso 2: Procesá en background por batches

@Async("importacionExecutor")
public void procesar(String jobId, Path archivoPath) {
    Importacion importacion = repository.findByJobId(jobId);
    importacion.setEstado("EN_PROGRESO");

    try (Stream<Registro> registros = parser.stream(archivoPath)) {
        List<Registro> batch = new ArrayList<>(1000);
        int procesados = 0;

        for (Registro r : registros) {
            try {
                batch.add(transformar(validar(r)));
            } catch (ValidationException e) {
                importacion.incrementarErrores();
            }

            if (batch.size() >= 1000) {
                repository.saveAll(batch);  // UN saveAll cada 1000
                batch.clear();
                procesados += 1000;
                importacion.setProcesados(procesados);
                repository.save(importacion);
            }
        }

        // Guardar ultimo batch parcial
        if (!batch.isEmpty()) {
            repository.saveAll(batch);
        }

        importacion.setEstado("COMPLETADO");
    } catch (Exception e) {
        importacion.setEstado("ERROR");
    }
    repository.save(importacion);
}

Tres cosas clave cambiaron:

Stream en vez de lista: no cargás 500K filas en memoria. Las leés de a poco. En Python es un generator. En Node es un readable stream. En Go es un scanner.
Batches de 1000: en vez de un INSERT por fila, hacés un saveAll cada 1000 registros. La base de datos te lo agradece — un bulk insert de 1000 es mucho más rápido que 1000 inserts individuales.
Progreso persistido: el usuario puede consultar cuántas filas se procesaron y cuántas fallaron. Sin adivinar.

Paso 3: Configurá el thread pool

@Bean("importacionExecutor")
public Executor importacionExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(2);
    executor.setMaxPoolSize(4);
    executor.setQueueCapacity(10);
    executor.setThreadNamePrefix("import-");
    executor.setRejectedExecutionHandler(
        new ThreadPoolExecutor.CallerRunsPolicy()
    );
    return executor;
}

No uses el executor por defecto. Si no configurás un pool, Spring crea un thread nuevo por cada tarea. Con 50 usuarios subiendo archivos a la vez, tenés 50 threads compitiendo por CPU y memoria. Eso no escala.

El CallerRunsPolicy es elegante: si la cola está llena, en vez de tirar un error, ejecuta la tarea en el thread del caller. Funciona como back-pressure natural. "Estoy ocupado, hacelo vos."

Decile al usuario qué está pasando

La UX importa tanto como la arquitectura. El peor error es dejar al usuario adivinando.

{
  "jobId": "abc-123",
  "estado": "EN_PROGRESO",
  "totalRegistros": 500000,
  "procesados": 125000,
  "errores": 42,
  "porcentaje": 25,
  "tiempoEstimado": "3 minutos"
}

El frontend hace polling cada 5 segundos (o mejor: usa WebSocket/SSE) y muestra una barra de progreso real. El usuario ve que algo está pasando. No se pone ansioso. No recarga la página. No genera requests duplicados.

Esto aplica a cualquier framework y cualquier frontend. La respuesta JSON con progreso es universal.

La regla de los tres tiempos

Si tu operación tarda segundos, puede ser síncrona. Respondé en el request, nadie se queja.

Si tarda minutos, tiene que ser asíncrona. Recibí, encolá, procesá en background, notificá.

Si tarda horas, necesitás un sistema de colas dedicado (RabbitMQ, SQS, Kafka) o un framework de batch processing (Spring Batch, Celery, Temporal). Y probablemente necesitás retry, dead letter queue, y monitoreo.

No es una cuestión de elegancia. Es que HTTP no fue diseñado para operaciones de larga duración. El timeout del load balancer, el timeout del browser, el timeout del proxy — todo te va a explotar en la cara si intentás forzar una operación de minutos en un protocol de milisegundos.

Cuándo NO usar async

Operaciones que tardan menos de 5 segundos — La complejidad del async no se justifica. Dejalo síncrono.
Cuando el usuario necesita el resultado para continuar — Si el paso siguiente depende del resultado, async no ayuda. El usuario va a quedarse esperando igual, pero haciendo polling.
Sin infraestructura para monitoreo — Los jobs async que fallan silenciosamente son un clásico de terror. Si no podés ver los jobs fallidos, estás volando a ciegas.
Con archivos pequeños — 100 registros no justifican toda esta maquinaria. Procesalos síncrono, respondé en 200ms, y seguí con tu vida.

Esto es el Día 8

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. Si tu endpoint tiene un timeout de 4 minutos, no necesitás un timeout más largo. Necesitás otra arquitectura.

Y lo más importante: tratá al usuario como adulto. Decile "esto tarda 3 minutos" y mostrále el progreso. Es mil veces mejor que una pantalla en blanco con un spinner eterno.

Seguí la saga completa en #100ArchitectureDays.

Todo el código está en GitHub. Si te está sirviendo, dejame una estrella — es gratis y ayuda a que más gente lo encuentre.

Día 7: ¿Quién te mandó a optimizar si ni siquiera mediste?

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:21:11 +0000

Después del post del Día 6 sobre caché, un amigo me escribió: "Ale, leí tu artículo y me puse a optimizar todo. Moví queries a vistas materializadas, metí un CDN, cambié el serializer de JSON. La app sigue tardando 3 segundos."

Le pregunté: "¿Y mediste dónde está el cuello de botella?"

Silencio.

"¿Al menos sabés cuál de los 4 servicios que llama tu endpoint es el lento?"

Más silencio.

Ahí le dije lo que te voy a decir a vos: ¿quién te mandó a optimizar si ni siquiera mediste?

Esto tiene nombre: se llama profiling

Lo que mi amigo necesitaba no es una optimización. Es un diagnóstico. Y la técnica para hacerlo existe desde hace décadas: se llama profiling.

Profiling es medir cuánto tiempo tarda cada parte de tu código. No adivinar, no intuir — medir con números reales. Es la diferencia entre un médico que te dice "tomá ibuprofeno, algo te debe doler" y uno que te hace estudios antes de recetarte algo.

Todos los lenguajes y frameworks tienen herramientas para esto:

Java/Spring: Micrometer + Actuator
Python: cProfile, Py-Spy, Django Debug Toolbar
Node.js: Clinic.js, built-in profiler, OpenTelemetry
Go: pprof (viene integrado en el runtime)
.NET: dotnet-trace, Application Insights
Ruby/Rails: rack-mini-profiler, Stackprof

La herramienta cambia. El concepto es universal: antes de optimizar, medí.

El primo peligroso de la optimización prematura

Todos conocemos la frase de Knuth: "la optimización prematura es la raíz de todos los males." Pero hay un primo hermano igual de peligroso que nadie nombra: la optimización ciega.

"Seguro es la base de datos." No mediste. "Debe ser la serialización JSON." No mediste. "El servicio externo tarda mucho." Tampoco mediste.

Y así terminás optimizando cosas que tardan 2ms mientras el verdadero culpable — un servicio que tarda 3.2 segundos — sigue ahí, invisible, arruinándote la vida.

El caso de mi amigo

Mirá el endpoint que me mandó. Tarda 3.3 segundos y nadie sabe por qué:

@RestController
public class PedidoController {

    @GetMapping("/pedidos/{id}")
    public PedidoDTO obtenerPedido(@PathVariable Long id) {
        Pedido pedido = pedidoService.buscar(id);           // ¿cuánto tarda?
        Cliente cliente = clienteService.buscar(pedido.getClienteId()); // ¿cuánto?
        List<Producto> productos = productoService
            .buscarPorIds(pedido.getProductoIds());          // ¿cuánto?
        BigDecimal descuento = descuentoService
            .calcular(cliente, productos);                   // ¿cuánto?

        return PedidoDTO.from(pedido, cliente, productos, descuento);
    }
}

Cuatro llamadas. ¿Cuál es la lenta? No tenés idea. Y sin datos, estás tirando dardos con los ojos vendados.

Cómo se hace en Spring Boot (pero el concepto es el mismo en cualquier stack)

En Spring Boot, las herramientas de profiling son Actuator (expone métricas por HTTP) y Micrometer (instrumenta tu código con timers). Es el equivalente a pprof en Go o cProfile en Python.

Agregá las dependencias:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Configurá los endpoints:

management:
  endpoints:
    web:
      exposure:
        include: health, metrics, prometheus
  metrics:
    tags:
      application: mi-ecommerce

Con esto ya tenés /actuator/metrics expuesto. Podés ver cuánto tardan tus endpoints, cuántas conexiones a la base de datos estás usando, el estado del thread pool, la memoria. Todo.

Instrumentá cada operación

El segundo paso es ponerle un timer a cada operación que sospechás. En cualquier lenguaje el patrón es el mismo: "empezá a contar, ejecutá la operación, pará de contar". En Spring Boot se hace con Micrometer:

@Service
public class PedidoService {

    private final MeterRegistry registry;
    private final PedidoRepository repository;

    public PedidoService(MeterRegistry registry, PedidoRepository repository) {
        this.registry = registry;
        this.repository = repository;
    }

    public Pedido buscar(Long id) {
        return registry.timer("pedido.buscar").record(() ->
            repository.findById(id).orElseThrow()
        );
    }
}

Hacé lo mismo con cada servicio. Ahora cuando consultás /actuator/metrics/pedido.buscar ves:

{
  "name": "pedido.buscar",
  "measurements": [
    { "statistic": "COUNT", "value": 1523 },
    { "statistic": "TOTAL_TIME", "value": 2.41 },
    { "statistic": "MAX", "value": 0.008 }
  ]
}

2.41 segundos en total, 1523 llamadas, máximo 8ms. Este servicio no es el problema.

Ahora mirás descuento.calcular:

{
  "name": "descuento.calcular",
  "measurements": [
    { "statistic": "COUNT", "value": 1523 },
    { "statistic": "TOTAL_TIME", "value": 4562.7 },
    { "statistic": "MAX", "value": 3.2 }
  ]
}

4562 segundos acumulados. Máximo 3.2 segundos por llamada. Ahí está tu cuello de botella.

Resulta que el servicio de descuentos llama a una API externa que tarda un promedio de 3 segundos. Pero nadie lo sabía porque nadie midió.

@Timed: la versión declarativa

Si no querés meter registry.timer() en cada método, Spring tiene una anotación que hace lo mismo de forma más limpia:

@Service
public class DescuentoService {

    @Timed(value = "descuento.calcular",
           description = "Tiempo de cálculo de descuentos",
           percentiles = {0.5, 0.95, 0.99})
    public BigDecimal calcular(Cliente cliente, List<Producto> productos) {
        // tu lógica
    }
}

Los percentiles te dan información mucho más útil que el promedio. El p95 de 3.2 segundos te dice que el 5% de tus usuarios esperan más de 3 segundos. El promedio de 300ms te mentiría.

No te olvides de registrar el aspect:

@Bean
public TimedAspect timedAspect(MeterRegistry registry) {
    return new TimedAspect(registry);
}

El waterfall real

Una vez que medís todo, el panorama se ve así:

pedido.buscar        ████  8ms
cliente.buscar       ██████  15ms
producto.buscarIds   ████████  22ms
descuento.calcular   ████████████████████████████████████████  3200ms
                     |--- Aquí está el 98% del tiempo ---|

Sin medir, hubieras cacheado producto.buscarIds (22ms) pensando que era el culpable. Con datos, sabés exactamente qué atacar.

La solución al cuello de botella real

Ahora que sabés que descuento.calcular es el problema, podés tomar decisiones informadas:

¿Se puede cachear el resultado del descuento? Sí, si los descuentos no cambian por cada request.
¿Se puede hacer la llamada async? Sí, si podés mostrar el pedido sin el descuento y cargarlo después.
¿Se puede reemplazar la API externa? Quizás, internalizando las reglas de descuento.

La decisión correcta sale de los datos, no de la intuición.

Cuándo NO hacer profiling

En producción sin cuidado — Las métricas consumen recursos. Micrometer es liviano, pero si instrumentás cada línea de cada método vas a generar overhead. Medí lo que importa.
Con datos de desarrollo — Tu máquina local con 3 registros no reproduce un problema de producción con 3 millones. Hacé profiling con datos representativos.
Para micro-optimizaciones — Si tu endpoint tarda 50ms en total y querés bajar a 45ms, probablemente no valga la pena el esfuerzo. Enfocate en los que tardan segundos.
Sin un baseline — Si no sabés cuánto tardaba antes, no podés saber si mejoraste. Medí antes de tocar nada.

La regla que me salvó cien veces

Antes de optimizar cualquier cosa, respondé estas tres preguntas:

¿Dónde está el cuello de botella? (Datos, no intuición.)
¿Cuánto impacto tiene? (Si es el 2% del tiempo total, no importa.)
¿Cuál es el costo de optimizarlo? (A veces la solución es más cara que el problema.)

La optimización no es una actividad creativa. Es una actividad científica. Hipótesis, medición, conclusión. Y esto aplica igual si estás en Spring Boot, Django, Express o Rails.

Esto es el Día 7

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. La próxima vez que alguien diga "seguro es la base de datos", pedile los números.

Seguí la saga completa en #100ArchitectureDays.

Todo el código está en GitHub. Si te está sirviendo, dejame una estrella — es gratis y ayuda a que más gente lo encuentre.

Día 6: Tu caché no funciona y es tu culpa

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:20:55 +0000

Pusiste @Cacheable en cada método del servicio. La app sigue lenta. Bienvenido al club.

El error que todos cometemos

La primera vez que descubrís caché, es como descubrir el martillo. De repente todo parece un clavo. Endpoint lento? @Cacheable. Query pesada? @Cacheable. El servicio externo tarda? @Cacheable.

Y funciona. Al principio.

Después llegan los bugs. Silenciosos. Difíciles de reproducir. El tipo de bugs que te hacen cuestionar tu carrera.

El desastre en acción

Mirá este servicio de e-commerce:

@Service
public class ProductoService {

    @Cacheable("productos")
    public Producto obtenerProducto(Long id) {
        return productoRepository.findById(id).orElseThrow();
    }

    @Cacheable("precios")
    public BigDecimal obtenerPrecio(Long productoId) {
        return precioRepository.findPrecioActual(productoId);
    }

    @Cacheable("stock")
    public int obtenerStock(Long productoId) {
        return inventarioClient.consultarStock(productoId);
    }
}

Parece prolijo, ¿no? Cacheable en todo. Performance al máximo.

Ahora imaginá esto: un usuario ve un producto a $50.000. Lo agrega al carrito. Mientras tanto, el precio sube a $55.000. El usuario compra. ¿Qué precio le cobrás? El de la base de datos: $55.000. Pero él vio $50.000.

Felicitaciones. Acabás de generar un reclamo, una devolución, y posiblemente un problema legal.

¿Y el stock? Cacheaste que hay 3 unidades. Pero se vendieron todas hace 2 minutos. Ahora vendiste algo que no tenés.

El caché no falló. Vos cacheaste lo que no debías.

Las reglas del caché que nadie te enseña

El caché funciona cuando se dan dos condiciones juntas:

El dato cambia pocas veces — Categorías de producto, configuraciones del sistema, catálogos, roles de usuario.
El dato se lee muchas veces — Endpoints que reciben cientos o miles de requests por minuto.

Si falta una de las dos, el caché no te sirve. O peor: te perjudica.

Los precios cambian. El stock cambia. Los datos de sesión cambian. Eso no se cachea. O si se cachea, se hace con una estrategia muy deliberada y un TTL agresivamente corto.

La versión que sí funciona

@Service
public class ProductoService {

    // Categorías: cambian una vez por semana. Se leen miles de veces por día.
    @Cacheable(value = "categorias", key = "#categoriaId")
    public Categoria obtenerCategoria(Long categoriaId) {
        return categoriaRepository.findById(categoriaId).orElseThrow();
    }

    // Configuración del sistema: cambia cuando alguien la modifica manualmente.
    @Cacheable("configuracion")
    public ConfiguracionTienda obtenerConfiguracion() {
        return configuracionRepository.findActiva();
    }

    // Precio: NUNCA cacheado. Siempre fresco.
    public BigDecimal obtenerPrecio(Long productoId) {
        return precioRepository.findPrecioActual(productoId);
    }

    // Stock: NUNCA cacheado. Siempre en tiempo real.
    public int obtenerStock(Long productoId) {
        return inventarioClient.consultarStock(productoId);
    }
}

Y cuando alguien modifica una categoría:

@CacheEvict(value = "categorias", key = "#categoriaId")
public void actualizarCategoria(Long categoriaId, CategoriaRequest request) {
    // Actualizar en base de datos
    // El caché se invalida automáticamente
}

¿Ves la diferencia? No cacheamos todo. Cacheamos lo correcto.

Las 4 preguntas antes de cachear

Antes de poner @Cacheable en cualquier cosa, hacete estas preguntas:

1. ¿Con qué frecuencia cambia este dato?
Si cambia cada minuto, no lo cachees. Si cambia una vez por día, es candidato.

2. ¿Con qué frecuencia se lee?
Si se lee 10 veces por hora, no vale la pena. Si se lee 10.000 veces por minuto, es candidato perfecto.

3. ¿Qué pasa si el dato está desactualizado?
Configuración de colores del sitio desactualizada 5 minutos? Nadie se muere. Precio desactualizado 5 minutos? Alguien pierde plata.

4. ¿Cómo lo invalido?
Si no tenés una estrategia clara de invalidación, no lo cachees. Un caché sin invalidación es una bomba de tiempo.

Qué cachear vs qué NO

Dato	Cambia	Se lee	¿Cachear?
Categorías	1x/mes	1000x/día	✅ SÍ
Configuraciones	1x/semana	500x/día	✅ SÍ
Precios	cada minuto	100x/día	❌ NO
Stock	cada compra	50x/día	❌ NO
Sesión usuario	cada request	1x	❌ NO

Cuándo NO cachear

Esto aplica a cualquier caché. Redis, Memcached, CDN, browser cache, lo que sea:

Datos financieros en tiempo real — Precios, saldos, tasas de cambio. El costo de un dato stale es demasiado alto.
Stock e inventario — Vender algo que no tenés es peor que una query lenta.
Datos de sesión o autenticación — Un usuario ve los datos de otro. Pesadilla de seguridad.
Resultados que dependen del momento — Rankings en vivo, dashboards real-time, contadores de stock.
Datos que cambian con cada request — Si cada llamada devuelve algo distinto, cachear no tiene sentido.

La regla es simple: si el costo de servir un dato viejo es mayor que el costo de una query lenta, no cachees.

El TTL no es opcional

Si vas a cachear, definí un TTL. Siempre. Un caché sin TTL es un dato que nunca se refresca hasta que reiniciés la aplicación o la memoria explote.

@Cacheable(value = "categorias", key = "#id")
// + configuración de TTL en tu cache manager:
// categorias -> TTL: 1 hora
// configuracion -> TTL: 30 minutos

El TTL es tu red de seguridad. Incluso si tu invalidación falla, el dato se refresca eventualmente.

El caché es una decisión de arquitectura

El caché no es un decorator que tirás encima del código para que ande más rápido. Es una decisión de arquitectura que implica tradeoffs reales:

Consistencia vs. performance
Memoria vs. latencia
Complejidad vs. velocidad

Cada @Cacheable que ponés es un contrato que dice: "acepto que este dato puede estar desactualizado por X tiempo, y las consecuencias son aceptables."

Si no podés articular ese contrato, no cachees.

Esto es el Día 6

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. No teoría abstracta. Código que podés correr y medir.

La próxima vez que estés por poner @Cacheable en un método, pará 30 segundos y hacete las 4 preguntas. Te van a ahorrar semanas de debugging de bugs fantasma que nadie puede reproducir.

Seguí la saga completa en #100ArchitectureDays.

Todo el código está en GitHub. Si te está sirviendo, dejame una estrella — es gratis y ayuda a que más gente lo encuentre.

Día 5: N+1 Queries — el bug que tu DBA ya sabe que tenés

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:19:26 +0000

Para mostrar 50 usuarios tu app hace 251 queries a la base de datos. Y vos ni te enteraste.

No falla. No tira excepción. No aparece en ningún log por default. Simplemente tu página tarda 4 segundos en cargar y nadie sabe por qué. Bueno, tu DBA sí sabe. Y te odia.

El supermercado

Imaginá que necesitás comprar 50 cosas. Vas al supermercado, comprás la primera, volvés a tu casa. Vas de nuevo, comprás la segunda, volvés. Y así 50 veces.

Ridículo, ¿no? Nadie haría eso en la vida real.

Bueno, tu ORM lo hace. Cada vez que accedés a una relación lazy, dispara un SELECT nuevo. Un viaje más a la base de datos. Uno por cada entidad. Y vos mirando el endpoint pensando "no sé por qué anda lento".

Esto se llama el problema N+1 y es, sin exagerar, el bug de performance más común en cualquier aplicación que use un ORM. No importa si es Hibernate, Django, ActiveRecord, Entity Framework o Prisma. Todos los ORMs tienen este problema. Si tu framework carga relaciones de forma lazy por default, estás expuesto.

El ANTES: lazy loading te arruina el día

Tenés un Usuario con una lista de Pedido. Clásico:

@Entity
public class Usuario {
    @Id
    @GeneratedValue
    private Long id;
    private String nombre;

    @OneToMany(mappedBy = "usuario")
    private List<Pedido> pedidos; // LAZY por default
}

Y en tu servicio hacés algo inocente:

List<Usuario> usuarios = usuarioRepository.findAll();

for (Usuario u : usuarios) {
    System.out.println(u.getNombre() + ": " + u.getPedidos().size());
}

Activá spring.jpa.show-sql=true y mirá el horror:

-- Query 1: traer todos los usuarios
SELECT * FROM usuario;

-- Query 2: pedidos del usuario 1
SELECT * FROM pedido WHERE usuario_id = 1;
-- Query 3: pedidos del usuario 2
SELECT * FROM pedido WHERE usuario_id = 2;
-- Query 4: pedidos del usuario 3
SELECT * FROM pedido WHERE usuario_id = 3;
-- ...
-- Query 51: pedidos del usuario 50
SELECT * FROM pedido WHERE usuario_id = 50;

1 query para los usuarios + 50 queries para los pedidos = 51 queries. Si cada usuario tiene 5 pedidos y cada pedido tiene ítems... ya estás en las 251 queries del título. Y eso para una sola request HTTP.

Multiplicá por 100 usuarios concurrentes y entendés por qué tu base de datos está llorando.

El DESPUÉS: un solo viaje al supermercado

La solución es decirle a Hibernate: "traeme todo de una, no seas vago".

Opción 1: JOIN FETCH en JPQL

@Query("SELECT u FROM Usuario u JOIN FETCH u.pedidos")
List<Usuario> findAllConPedidos();

Opción 2: @EntityGraph (más declarativo)

@EntityGraph(attributePaths = {"pedidos"})
@Query("SELECT u FROM Usuario u")
List<Usuario> findAllConPedidos();

Resultado en la base de datos:

-- UNA sola query
SELECT u.*, p.*
FROM usuario u
LEFT JOIN pedido p ON u.id = p.usuario_id;

251 queries se convierten en 1. Un solo viaje. Todo lo que necesitás, de una sola vez.

Los números

	ANTES	DESPUÉS	Mejora
Queries	251	1	99.6%
Tiempo	~4200ms	~85ms	98%

No es una mejora marginal. Es la diferencia entre una app que funciona y una que da vergüenza.

Cómo detectar N+1 antes de producción

No esperés a que tu DBA te mande un mensaje pasivo-agresivo. Detectalo vos:

1. Activá el logging de SQL en desarrollo:

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true

Si ves el mismo SELECT repitiéndose con diferentes parámetros, tenés un N+1.

2. Usá las estadísticas de Hibernate:

spring:
  jpa:
    properties:
      hibernate:
        generate_statistics: true

En el log vas a ver algo como:

Session Metrics {
    1234567 nanoseconds spent executing 251 JDBC statements
}

251 statements para un endpoint que debería hacer 1 o 2 queries. Ahí lo tenés. Evidencia irrefutable.

3. Regla de oro: si un endpoint ejecuta más de 10 queries, algo está mal. No hay excusa.

Cuándo NO usar JOIN FETCH

Antes de que salgas a ponerle JOIN FETCH a todo (sí, te vi), hay un caso donde te va a explotar en la cara:

// NUNCA hagas esto
@Query("SELECT u FROM Usuario u JOIN FETCH u.pedidos JOIN FETCH u.direcciones")
List<Usuario> findAllCompleto();

Si un usuario tiene 5 pedidos y 3 direcciones, Hibernate genera un producto cartesiano: 5 x 3 = 15 filas por usuario. Con 50 usuarios son 750 filas. Y la JVM tiene que deduplicar todo eso en memoria.

La regla: JOIN FETCH con una sola colección a la vez. Si necesitás múltiples colecciones, usá @BatchSize o queries separadas:

@Entity
public class Usuario {
    @OneToMany(mappedBy = "usuario")
    @BatchSize(size = 50) // Carga en lotes de 50 en vez de 1 por 1
    private List<Pedido> pedidos;

    @OneToMany(mappedBy = "usuario")
    @BatchSize(size = 50)
    private List<Direccion> direcciones;
}

@BatchSize convierte 50 queries individuales en 1 query con un IN clause. No es tan eficiente como JOIN FETCH, pero evita el producto cartesiano.

Esto no es solo Java

Si usás Django y hacés User.objects.all() y después accedés a user.orders en un loop, tenés el mismo problema. La solución allá es select_related y prefetch_related.

Si usás Rails, es includes(:orders).

Si usás Entity Framework, es .Include(u => u.Orders).

Si usás Prisma, es el include: { orders: true }.

El patrón es universal. Cambia la sintaxis, el problema es idéntico. Si tu ORM carga relaciones de forma lazy y vos iterás sin pensar, estás haciendo N+1. No importa el lenguaje, no importa el framework.

Esto es el Día 5

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. No teoría abstracta. Código que podés correr y medir.

La próxima vez que un endpoint ande lento, antes de escalar horizontalmente, antes de agregar un cache, antes de culpar a la base de datos... activá show-sql y contá las queries.

Te sorprendería la cantidad de problemas de performance que se resuelven con un JOIN FETCH bien puesto.

Seguí la saga completa en #100ArchitectureDays.

Todo el código está en GitHub. Si te está sirviendo, dejame una estrella — es gratis y ayuda a que más gente lo encuentre.

Día 4: Tu endpoint devuelve TODO. El frontend explota. La red llora.

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:19:08 +0000

Tu endpoint de productos funciona perfecto en desarrollo. 100 registros, respuesta instantánea. Pero en producción tenés 50,000 productos y cada request a /api/products carga los 50,000 en memoria, los serializa a JSON, y manda 10MB por la red.

El frontend hace un JSON.parse() de 10MB. El navegador se congela. El usuario cierra la pestaña. Y vos mirando los logs pensando "en mi máquina funciona".

El problema real

No paginar no es un shortcut. Es una bomba de tiempo.

Con 50,000 registros sin paginar, tu endpoint:

Carga todo en memoria — potencial OutOfMemoryError
Serializa todo a JSON — CPU al 100%
Transmite todo por la red — ~10MB por request
El cliente espera 30 segundos — timeout y usuarios frustrados

Y lo peor: escala linealmente. Hoy son 50,000, mañana son 200,000. El problema solo crece.

El ANTES: devolver todo

@Service
@Profile("before")
public class NoPaginationService implements ProductService {

    @Override
    public Object getProducts(int page, int size, Long cursor) {
        return repository.findAll(); // Los 50,000. Todos. Sin piedad.
    }
}

SELECT * FROM products;  -- 50,000 registros. RIP memoria.

El DESPUÉS: dos estrategias, cada una con su lugar

Offset Pagination — la clásica

@Service
@Profile("offset")
public class OffsetPaginationService implements ProductService {

    @Override
    public Object getProducts(int page, int size, Long cursor) {
        PageRequest pageRequest = PageRequest.of(page, size, Sort.by("id"));
        return repository.findAllProjectedBy(pageRequest);
    }
}

SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 1000;

Spring Data JPA te da Pageable out of the box. Le pasás página y tamaño, y te devuelve un Page<T> con los datos, el total de páginas, el total de elementos, si hay siguiente... todo. Para una UI con paginitas numeradas, es perfecto.

Pero tiene un problema. Cuanto más alto el offset, más lenta la query. ¿Por qué? Porque PostgreSQL tiene que:

Leer todos los registros hasta el offset
Ordenarlos
Descartar los primeros N
Devolver solo los siguientes M

Página 1: lee 20 registros. Página 2000: lee 40,020 registros para devolver 20.

Cursor Pagination — la escalable

@Service
@Profile("after")
public class CursorPaginationService implements ProductService {

    @Override
    public Object getProducts(int page, int size, Long cursor) {
        List<Product> products;
        if (cursor == null || cursor == 0) {
            products = repository.findFirstPage(PageRequest.of(0, size + 1));
        } else {
            products = repository.findByCursorAfter(cursor, PageRequest.of(0, size + 1));
        }
        boolean hasNext = products.size() > size;
        // construir respuesta con nextCursor
    }
}

SELECT * FROM products WHERE id > 1000 ORDER BY id LIMIT 20;

En vez de decir "saltá 1000 y dame 20", le decís "dame los 20 que vienen después del ID 1000". PostgreSQL usa el índice, va directo al registro 1001, y lee 20. Siempre. No importa si estás en la página 1 o en la 2000.

Los números

Página 1 (offset=0):
  Offset:  5ms    |  Cursor:  5ms

Página 100 (offset=2000):
  Offset:  15ms   |  Cursor:  5ms

Página 1000 (offset=20000):
  Offset:  150ms  |  Cursor:  5ms

Página 2500 (offset=50000):
  Offset:  400ms+ |  Cursor:  5ms

¿Ves el patrón? Offset se degrada. Cursor se mantiene constante. O(n) vs O(1).

Con 50,000 registros la diferencia es 400ms vs 5ms. Con 5 millones de registros, offset puede tardar segundos mientras cursor sigue en 5ms. Es una diferencia arquitectónica, no una micro-optimización.

¿Cuál uso?

No hay una respuesta universal. Depende de tu caso de uso:

Escenario	Estrategia
Dashboard con tabla y paginitas numeradas	Offset — el usuario necesita saltar a la página 47
Scroll infinito (feed, timeline)	Cursor — rendimiento constante en cada scroll
API pública	Cursor — no querés que un cliente pida página 999999
Exportar datos en lotes	Cursor — procesás de a chunks sin degradar
Panel admin con pocos registros	Offset — la simplicidad gana, metadata completa

La regla general: si el usuario necesita saltar a una página específica, usá offset. Si siempre avanza secuencialmente, usá cursor.

La respuesta de cursor en la práctica

public record CursorPage<T>(
    List<T> content,
    String nextCursor,
    String previousCursor,
    boolean hasNext,
    boolean hasPrevious,
    int size
) {}

El truco está en pedir size + 1 registros. Si te vuelven 21 cuando pediste 20, sabés que hay más. Devolvés 20 y ponés hasNext: true con el cursor del último elemento. El cliente manda ese cursor en la siguiente request. Elegante y sin queries extra para contar totales.

Cuándo NO paginar

Sí, hay casos donde paginar agrega complejidad innecesaria:

Datasets que siempre van a ser chicos. Si tu tabla de categorías tiene 15 registros y nunca va a tener más de 50, un findAll() está bien. No sobre-ingenieres.
Búsquedas con filtros muy selectivos. Si tu query siempre devuelve menos de 100 resultados porque los filtros son específicos, la paginación agrega overhead sin beneficio.
Datos que necesitás completos para calcular algo. Si tenés que sumar todos los montos de un reporte, paginá en la base de datos y procesá en streaming, no pagines en la API.
Endpoints internos entre microservicios. Si el consumidor siempre necesita todo y está en la misma red, la paginación agrega latencia por el ida y vuelta extra.

Pero si tu endpoint es público, si el dataset crece, si un usuario puede llegar con un browser: paginá. Siempre.

Esto no es solo Java

Si usás Django, tenés Paginator para offset y podés implementar cursor con django-cursor-pagination o manualmente con filtros en el queryset.

Si usás Rails, kaminari y will_paginate hacen offset. Para cursor, filtrás con .where("id > ?", cursor).limit(size).

Si usás Express con Prisma, es skip/take para offset y cursor como parámetro nativo de Prisma.

Si usás FastAPI con SQLAlchemy, es .offset().limit() vs .filter(Model.id > cursor).limit().

El patrón es el mismo en todos los lenguajes. Offset usa OFFSET en SQL (o su equivalente) y se degrada linealmente. Cursor usa un WHERE con un valor de referencia y mantiene rendimiento constante. No importa el framework — la base de datos se comporta igual.

Esto es el Día 4

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. Código que podés correr, medir, y ver cómo se degrada offset mientras cursor se mantiene firme.

Si tu endpoint devuelve todo sin paginar, hoy es el día de arreglar eso. Tu base de datos, tu red, y tus usuarios te lo van a agradecer.

Seguí la saga completa en #100ArchitectureDays.

💻 Todo el código está en GitHub. Si te está sirviendo, dejame una ⭐ — es gratis y ayuda a que más gente lo encuentre.

Día 3: Agregaste un índice y la consulta sigue lenta. El problema no era el índice.

Alejandro Lafourcade Despaigne — Thu, 23 Apr 2026 20:18:48 +0000

Agregaste un índice en la columna status. Te sentiste bien. Pusheaste a producción. La query sigue tardando 3 segundos.

El DBA te mira. Vos mirás el índice. El índice existe. Pero PostgreSQL lo ignora completamente. Como si no estuviera. Y vos sin entender por qué.

El problema real

10,000 órdenes. Una query simple: buscar por estado y rango de fechas. Debería ser instantáneo. Pero no lo es.

El índice está ahí. Lo podés ver con \di en psql. Está creado, está sano, ocupa espacio en disco. Pero tu query hace Seq Scan — lee las 10,000 filas una por una como si el índice no existiera.

Spoiler: el índice no era el problema. Era cómo lo usabas.

El ANTES: LOWER() te arruina el día

@Query("SELECT o FROM Order o WHERE LOWER(o.status) = LOWER(:status) " +
       "AND o.createdAt BETWEEN :start AND :end")
List<Order> findByStatusIgnoreCaseAndDateRange(
    @Param("status") String status,
    @Param("start") LocalDateTime start,
    @Param("end") LocalDateTime end);

Se ve razonable, ¿no? "Por las dudas hago LOWER() para que sea case-insensitive." El problema es que ese LOWER() le dice a PostgreSQL: "olvidate del índice".

¿Por qué? Porque el índice está ordenado por el valor original de la columna: PENDING, SHIPPED, DELIVERED. Pero vos le estás pidiendo que busque por LOWER(status) — un valor transformado. PostgreSQL no puede usar un índice sobre status para buscar sobre LOWER(status). Son cosas diferentes.

Entonces hace lo único que puede: leer cada fila, aplicarle LOWER(), y comparar. Fila por fila. Las 10,000. Eso es un Seq Scan.

El DESPUÉS: normalizá antes, no durante

@Service
@Profile("after")
public class OptimizedQueryService implements OrderService {

    @Override
    public List<Order> findOrdersByStatusAndDateRange(String status, ...) {
        String normalizedStatus = status.toLowerCase();
        return repository.findByStatusAndDateRangeOptimized(normalizedStatus, start, end);
    }
}

@Query("SELECT o FROM Order o WHERE o.status = :status " +
       "AND o.createdAt BETWEEN :start AND :end")
List<Order> findByStatusAndDateRangeOptimized(
    @Param("status") String status,
    @Param("start") LocalDateTime start,
    @Param("end") LocalDateTime end);

La diferencia: normalizamos el dato al insertarlo (guardar siempre en minúsculas) y normalizamos el parámetro antes de la query (en Java, no en SQL). Así PostgreSQL compara columna vs valor directamente, y el índice funciona.

EXPLAIN ANALYZE: tu mejor amigo

No adivinés. Preguntale a la base de datos qué está haciendo:

-- Query LENTA
EXPLAIN ANALYZE
SELECT * FROM orders
WHERE LOWER(status) = 'pending'
AND created_at BETWEEN '2024-01-01' AND '2024-12-31';

Seq Scan on orders  (cost=0.00..285.00 rows=5000 width=64)
  Filter: ((lower(status) = 'pending') AND ...)
  Rows Removed by Filter: 5000
  Planning Time: 0.15 ms
  Execution Time: 45.23 ms

Seq Scan. Esa es la palabra que tenés que temer. Significa que PostgreSQL está leyendo toda la tabla.

Ahora la query optimizada:

-- Query RÁPIDA
EXPLAIN ANALYZE
SELECT * FROM orders
WHERE status = 'pending'
AND created_at BETWEEN '2024-01-01' AND '2024-12-31';

Index Scan using idx_orders_status_created on orders
  Index Cond: ((status = 'pending') AND ...)
  Planning Time: 0.12 ms
  Execution Time: 0.05 ms

Index Scan. PostgreSQL fue directo a los datos que necesitaba.

Los números

	ANTES	DESPUÉS	Mejora
Tipo de Scan	Seq Scan	Index Scan	-
Tiempo	~45ms	~0.05ms	900x
Filas escaneadas	10,000	~50	200x

Y eso con 10,000 registros. En producción con millones de filas, la diferencia entre Seq Scan e Index Scan es la diferencia entre un endpoint que responde y uno que hace timeout.

Cómo leer un EXPLAIN ANALYZE (sin dormirte)

No necesitás un doctorado. Buscá estas tres cosas:

Seq Scan = malo. Significa que lee toda la tabla. Si ves esto en una tabla grande, tenés un problema.
Index Scan = bueno. Significa que usa el índice y va directo a los datos.
Rows Removed by Filter = desperdicio. Son filas que leyó pero descartó. Cuanto más alto el número, peor.

Si tu query tiene Seq Scan y Rows Removed by Filter alto, no necesitás más RAM ni más CPU. Necesitás revisar tu WHERE clause.

Las funciones que matan tus índices

LOWER() no es la única culpable. Cualquier función aplicada a una columna en el WHERE invalida el índice:

UPPER(column) — mismo problema que LOWER
TRIM(column) — si necesitás trim, limpiá los datos al insertar
CAST(column AS ...) — cuidado con conversiones implícitas
EXTRACT(YEAR FROM column) — usá rangos de fechas en vez de extraer partes
column + 1 = 5 — reescribí como column = 4

La regla de oro: la columna indexada debe aparecer sola en un lado de la comparación. Si le envolvés una función, el índice no se puede usar.

Cuándo NO optimizar la query

Tablas chicas. Si tu tabla tiene 100 filas, un Seq Scan tarda microsegundos. PostgreSQL a veces elige Seq Scan a propósito porque es más rápido que buscar en el índice para tablas pequeñas.
Queries que corren una vez al día. Un reporte nocturno que tarda 2 segundos no necesita un índice. No optimices lo que no duele.
Cuando el índice ralentiza las escrituras. Cada índice que agregás hace que los INSERT y UPDATE sean más lentos. Si tu tabla tiene escritura intensiva, pensalo dos veces.
Cuando el selectividad es baja. Si el 80% de tus órdenes son PENDING, el índice en status no ayuda mucho — PostgreSQL va a leer casi toda la tabla de todas formas y prefiere Seq Scan.

Esto no es solo Java

Si usás Django con PostgreSQL y hacés Order.objects.filter(status__iexact='pending'), Django genera un UPPER() en la query. Mismo problema, misma solución: normalizá los datos.

Si usás Rails con where("LOWER(status) = ?", status.downcase), estás invalidando el índice.

Si usás cualquier ORM con cualquier base de datos relacional, la regla es la misma: las funciones en el WHERE matan los índices. No importa si es PostgreSQL, MySQL, Oracle o SQL Server. El optimizador no puede usar un índice sobre una columna transformada.

EXPLAIN ANALYZE es la versión PostgreSQL. MySQL tiene EXPLAIN, SQL Server tiene SET STATISTICS IO ON y los execution plans gráficos. Cada motor tiene su herramienta. Aprendé a usarla antes de agregar índices a ciegas.

Esto es el Día 3

Este artículo es parte de #100ArchitectureDays — una serie de problemas reales de arquitectura con soluciones reales. No teoría. Código que podés correr y medir.

La próxima vez que una query ande lenta, antes de agregar un índice, corré EXPLAIN ANALYZE. Puede que el índice ya exista y simplemente no lo estés usando. Diagnosticá primero, optimizá después.

Seguí la saga completa en #100ArchitectureDays.

💻 Todo el código está en GitHub. Si te está sirviendo, dejame una ⭐ — es gratis y ayuda a que más gente lo encuentre.