La Guía Definitiva de Circuit Breakers en Spring Boot (Java)

1. Introducción a la Resiliencia en Sistemas Distribuidos

En las arquitecturas modernas de microservicios, los sistemas son de naturaleza distribuida. Las aplicaciones realizan llamadas remotas a través de la red a servidores de bases de datos, proveedores de SaaS externos y otros microservicios internos. Aunque la distribución por red ofrece escalabilidad y desacoplamiento, introduce un punto de fallo crítico: el fallo parcial.

Un sistema remoto puede fallar, sobrecargarse, experimentar alta latencia o sufrir microcortes de red transitorios. Sin las salvaguardas adecuadas, un fallo en una única dependencia aguas abajo (downstream) puede propagarse en cascada por todo el clúster:

Fallos en Cascada y Agotamiento del Pool de Hilos (Thread Pool Exhaustion)

Cuando un servicio aguas abajo es lento o no responde, los hilos del cliente que esperan una respuesta permanecen bloqueados. A medida que siguen llegando nuevas solicitudes, se asignan más hilos para llamar al servicio con problemas. Bajo carga, esto conduce rápidamente al Agotamiento del Pool de Hilos (Thread Pool Exhaustion) en el servicio cliente. Una vez que el pool se agota, el servicio cliente deja de responder por completo a todo el tráfico, incluso a solicitudes que no dependen del sistema remoto que está fallando.

Para construir aplicaciones tolerantes a fallos y resilientes, debemos seguir una filosofía de diseño fundamental: Diseñar para el fallo y fallar rápido (Fail Fast).

2. El Patrón Circuit Breaker: Teoría Principal

El patrón Circuit Breaker (Disyuntor/Cortocircuito), popularizado por Michael Nygard en su libro de referencia Release It!, actúa como una válvula de seguridad para llamadas remotas. Envuelve las llamadas a métodos protegidos y monitoriza los fallos.

Al igual que los interruptores magnetotérmicos (fusibles) del hogar evitan que las sobrecargas eléctricas quemen una casa, los circuit breakers de software cortan la conexión con un servicio de destino que está fallando para proteger al sistema emisor.

Los Tres Estados y sus Transiciones

Un circuit breaker de software estándar existe en uno de tres estados principales:

1. CLOSED (Cerrado - Estado Normal): El circuit breaker redirige todas las llamadas al servicio de destino. Monitoriza los resultados (éxitos, fallos, llamadas lentas). Si la tasa de fallos supera los umbrales configurados, pasa al estado OPEN.
2. OPEN (Abierto - Fallo Rápido): El circuit breaker impide que las llamadas lleguen al servicio de destino. Lanza inmediatamente una excepción CallNotPermittedException (falla rápido) o ejecuta un método de contingencia local (fallback).
3. HALF-OPEN (Semi-Abierto - Estado de Prueba): El circuit breaker permite que un número limitado y configurable de solicitudes de prueba pasen al servicio de destino. Si cualquiera falla, vuelve a OPEN. Si todas son exitosas, vuelve a CLOSED.

🌐 3 Ejemplos del Mundo Real: CLOSED, OPEN y HALF-OPEN

Para ver cómo operan estos estados en sistemas reales de producción, analizemos estos tres escenarios clásicos de arquitectura de software:

Ejemplo 1 E-Commerce (Servicio de Pedidos → Servicio de Inventario)

Cuando haces clic en "Comprar", el Servicio de Pedidos llama al Servicio de Inventario para reservar stock.

🟢 CLOSED (Normalidad)

El cliente compra una camiseta. La llamada viaja al inventario, este responde "Reservado OK" en 50ms y la compra se procesa. El disyuntor registra "Éxito" en su ventana deslizante.

🔴 OPEN (Fallo Rápido)

El inventario se apaga por mantenimiento y las llamadas dan timeout. Al cruzar el umbral del 50%, el circuito pasa a OPEN. Un nuevo cliente compra; el disyuntor bloquea la llamada en 0.1ms y ejecuta el fallback: guarda el pedido localmente y avisa *"Procesaremos el cobro cuando el sistema se recupere"*.

🟡 HALF-OPEN (Prueba)

Pasan los 30s de espera. El disyuntor pasa a HALF-OPEN y deja pasar 5 compras de prueba. Si las 5 tienen éxito porque el inventario volvió a encender, el circuito vuelve a CLOSED. Si alguna falla, regresa a OPEN y reinicia el timer.

Ejemplo 2 App de Transporte (Tellevo → API de Google Maps)

Para cotizar un viaje de carpooling, la app llama a Google Maps para obtener la ruta y la distancia exacta.

🟢 CLOSED (Normalidad)

El pasajero busca viaje. La app consulta a Google, obtiene la ruta óptima en 100ms, calcula la tarifa y presenta el viaje al instante.

🔴 OPEN (Fallo Rápido)

La tarjeta de la empresa expira y la API responde con error de autenticación `403`. El disyuntor pasa a OPEN. Al cotizar nuevos viajes, el disyuntor bloquea las llamadas y ejecuta un fallback local: calcula la tarifa aproximada usando distancia matemática en línea recta (Fórmula de Haversine) sobre coordenadas GPS. La app sigue vendiendo viajes.

🟡 HALF-OPEN (Prueba)

El administrador paga la cuenta de Google Maps. Pasan 60s, el disyuntor pasa a HALF-OPEN y deja pasar 5 llamadas a la API. Al responder con éxito, el disyuntor asume que la API está sana, pasa a CLOSED y cotiza de nuevo con máxima precisión.

Ejemplo 3 Plataforma de Streaming (App Principal → Motor de Recomendaciones)

Al abrir la app de streaming, la pantalla de inicio consulta al motor para mostrar las películas recomendadas para ti.

🟢 CLOSED (Normalidad)

Abres la app. El motor de recomendaciones analiza tus gustos y responde en 150ms. Tu pantalla inicial carga filas personalizadas al instante.

🔴 OPEN (Fallo Rápido)

Se estrena una serie viral y millones de personas entran a la vez. El motor de recomendaciones se satura de CPU y tarda 8s en responder (provocando timeouts). El disyuntor salta a OPEN. Al abrir la app, en milisegundos se ejecuta el fallback: carga una lista estática ya guardada en caché de *"Las 10 películas más populares del país"*. La app abre al instante y no frustra al usuario.

🟡 HALF-OPEN (Prueba)

Baja la ráfaga de tráfico. Tras el timer, el circuito pasa a HALF-OPEN y envía 5 solicitudes de prueba al motor. Al responder en menos de 200ms, el circuito vuelve a CLOSED y restaura las filas personalizadas.

3. La Evolución de los Circuit Breakers en Spring: De Hystrix a Resilience4j

Durante años, Netflix Hystrix fue el estándar de facto para circuit breakers en el ecosistema Spring Cloud. Sin embargo, Netflix depreco oficialmente Hystrix a finales de 2018, instando a los desarrolladores a buscar soluciones alternativas.

4. Conceptos Clave de Resilience4j y Ventanas Deslizantes (Sliding Windows)

Resilience4j utiliza una ventana deslizante (sliding window) para registrar y evaluar los resultados de las llamadas. Esta ventana se puede configurar de dos formas:

1. Ventana Deslizante Basada en Conteo (Count-Based)

La ventana deslizante es un buffer circular de tamaño fijo que contiene las últimas N llamadas. Si el tamaño de la ventana es 100, el circuit breaker evalúa la tasa de fallos basándose únicamente en las últimas 100 ejecuciones.

2. Ventana Deslizante Basada en Tiempo (Time-Based)

La ventana deslizante es un buffer circular que registra los resultados de las ejecuciones que ocurren dentro de los últimos N segundos. Se implementa utilizando agregaciones parciales (buckets) para minimizar el consumo de memoria.

Copiarresilience4j.circuitbreaker:
  configs:
    default:
      # slidingWindowType puede ser: COUNT_BASED (por defecto) o TIME_BASED
      slidingWindowType: TIME_BASED
      # slidingWindowSize cambia su significado según el tipo:
      # - En COUNT_BASED: representará un número de llamadas (ej. 50 llamadas)
      # - En TIME_BASED: representará segundos (ej. 50 segundos)
      slidingWindowSize: 60

CopiarCircuitBreakerConfig config = CircuitBreakerConfig.custom()
    .slidingWindowType(SlidingWindowType.TIME_BASED) // o COUNT_BASED
    .slidingWindowSize(60) // 60 segundos o 60 llamadas según el tipo
    .failureRateThreshold(50.0f)
    .build();

5. Configuración de un Proyecto Spring Boot con Resilience4j

Configuremos una aplicación moderna de Spring Boot 3.x con las dependencias requeridas.

Dependencias (Maven - pom.xml)

Copiar<!-- Resilience4j Spring Boot Starter -->
<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot3</artifactId>
    <version>2.2.0</version>
</dependency>

<!-- Spring Boot Starter AOP (Requerido para la anotación) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

Configuración en YAML (application.yml)

Copiarresilience4j:
  circuitbreaker:
    configs:
      default:
        slidingWindowSize: 100
        slidingWindowType: COUNT_BASED
        minimumNumberOfCalls: 10
        failureRateThreshold: 50
        slowCallRateThreshold: 75
        slowCallDurationThreshold: 2000s
        waitDurationInOpenState: 15000s
        permittedNumberOfCallsInHalfOpenState: 5
        automaticTransitionFromOpenToHalfOpenEnabled: true
    instances:
      paymentServiceBreaker:
        baseConfig: default
        slidingWindowSize: 20
        failureRateThreshold: 40

6. Implementación Declarativa con `@CircuitBreaker` y Fallbacks

Resilience4j proporciona un aspecto de Spring AOP que intercepta las llamadas anotadas con @CircuitBreaker.

Copiar@Service
public class PaymentService {

    private final RestTemplate restTemplate;

    @CircuitBreaker(name = "paymentServiceBreaker", fallbackMethod = "processPaymentFallback")
    public String processPayment(String transactionId, double amount) {
        String externalUrl = "https://api.external-payment.com/v1/charge";
        return restTemplate.postForObject(externalUrl, new PaymentRequest(transactionId, amount), String.class);
    }

    // Método de contingencia (fallback)
    public String processPaymentFallback(String transactionId, double amount, Throwable exception) {
        if (exception instanceof CallNotPermittedException) {
            return "PAYMENT_SERVICE_UNAVAILABLE (Fallo Rápido)";
        }
        return "PAYMENT_PENDING (Almacenado localmente para procesamiento diferido)";
    }
}

7. Configuración Avanzada: Gestión de Excepciones y Oyentes

No todas las excepciones representan fallos del sistema o de infraestructura. Por ejemplo, los errores de negocio 4xx.

Copiarresilience4j.circuitbreaker:
  instances:
    orderServiceBreaker:
      recordExceptions:
        - org.springframework.web.client.HttpServerErrorException # Errores 5xx
        - java.util.concurrent.TimeoutException
      ignoreExceptions:
        - org.springframework.web.client.HttpClientErrorException # Errores 4xx

Suscripción a Eventos de Transición de Estado

Copiar@Configuration
public class CircuitBreakerEventListener {
    @PostConstruct
    public void registerListeners() {
        registry.getAllCircuitBreakers().forEach(breaker -> {
            breaker.getEventPublisher()
                .onStateTransition(event -> log.error("Transición: {}", event.getStateTransition()));
        });
    }
}

8. Uso Programático de Circuit Breakers

La envoltura programática con lambdas ofrece un control absoluto sobre la ejecución y permite evitar los límites tradicionales del proxy de Spring AOP.

Copiar@Service
public class ProgrammaticPaymentService {
    private final CircuitBreaker circuitBreaker;

    public String processPayment(String txId, double amount) {
        Supplier<String> paymentCall = () -> executePayment(txId, amount);
        Supplier<String> decorated = CircuitBreaker.decorateSupplier(circuitBreaker, paymentCall);
        
        return Try.ofSupplier(decorated)
                .recover(throwable -> "FALLBACK_TRIGGERED")
                .get();
    }
}

9. Observabilidad, Métricas y Monitoreo en Producción

Spring Boot Actuator se integra nativamente con Micrometer para exponer métricas exactas del estado de tus circuit breakers.

10. Estrategias de Prueba (Unitarias, Integración y Simulación)

Verificar las transiciones de estado programáticas mediante pruebas de integración robustas.

Copiar@SpringBootTest
class PaymentServiceIntegrationTest {
    @Autowired private PaymentService paymentService;
    
    @Test
    void testCircuitBreakerTrips() {
        // Simular fallos repetidos
        when(restTemplate.postForObject(any(), any(), any()))
            .thenThrow(new RuntimeException("Network Error"));

        for (int i = 0; i < 11; i++) {
            paymentService.processPayment("tx", 10.0);
        }

        assertEquals(CircuitBreaker.State.OPEN, circuitBreaker.getState());
    }
}

11. Buenas Prácticas en Producción y Errores Comunes