Migrar desde Resilience4j

Cómo se corresponden los registries, configs, decoradores y anotaciones de Spring de Resilience4j con resilience4cata, qué no tiene equivalente y qué se comporta distinto.

¿Deberías migrar?

resilience4cata cubre ocho políticas (retry, hedge, circuit breaker, rate limiter, adaptive limit, timeout, bulkhead, fallback) para Java 21+ puro, con código generado en tiempo de compilación. Quédate en Resilience4j si necesitas algo de esto, que resilience4cata todavía no tiene:

• integración con Spring Boot 3, CDI o AspectJ (resilience4cata se integra solo con Spring Boot 4.1+, más abajo);
• operadores de Reactor, RxJava o corrutinas de Kotlin (resilience4cata solo admite CompletionStage / CompletableFuture);
• un bulkhead con pool de threads, una caché o un time limiter para futures arbitrarios;
• cambiar la configuración de una política en tiempo de ejecución (resilience4cata resuelve la configuración una sola vez, por diseño);
• una versión de Java anterior a la 21.

Considera migrar si te importan el overhead y la asignación de memoria por llamada (consulta Rendimiento), si quieres detectar los errores de configuración al compilar, o si prefieres anotaciones simples y código generado que puedes leer en lugar de proxies de AOP.

El modelo mental

Correspondencia de conceptos

Correspondencia de configuración

Los métodos de los builders de Resilience4j (las properties de Spring Boot usan los mismos nombres en kebab-case) y el atributo de resilience4cata con el mismo papel. Los valores predeterminados difieren en algunos casos; las columnas Predeterminado son las de cada biblioteca.

Circuit breaker

Retry

Rate limiter, timeout, bulkhead

Warning Tres valores predeterminados suelen sorprender: el retry de resilience4cata usa backoff exponencial con jitter completo desde 200 ms, no un valor fijo de 500 ms; su rate limiter rechaza de inmediato en lugar de esperar hasta 5 s; y su breaker no cronometra las llamadas a menos que configures slowCallDuration. Configúralos explícitamente al migrar.

Hedge

El módulo resilience4j-hedge de Resilience4j (2.x) es programático y solo async, como el nuestro (sin anotación de Spring), y lanza como mucho un hedge.

La semántica difiere: en Resilience4j gana el primer intento que termina, así que una falla rápida de cualquiera de los dos hace fallar la llamada; en resilience4cata gana el primer éxito, una falla de hedgeOn lanza el siguiente intento enseguida, y la llamada solo falla cuando todos los intentos han fallado (o uno falla con una falla de abortOn). El perdedor se cancela, y el circuit breaker, el bulkhead y el timeout dentro del hedge liberan lo que tenía.

Diferencias de comportamiento

El orden

Fallback → Retry (o Hedge) → CircuitBreaker → RateLimiter → AdaptiveLimit → Timeout → Bulkhead → método por defecto, sin importar el orden de las anotaciones. Coincide con el orden predeterminado de aspectos de Spring en Resilience4j para las políticas que ambas tienen. Donde Resilience4j cambia el orden de forma global con las propiedades <module>AspectOrder, resilience4cata lo cambia por método, tipo o bundle con @PolicyOrder, al compilar; el fallback sigue siendo la capa más exterior.

Un breaker abierto detiene los retries

Un retry nunca reintenta CallNotPermittedException, diga lo que diga su abortOn, así que en cuanto el breaker se abre, el retry se rinde de inmediato en lugar de seguir reintentando contra él. En Resilience4j tienes que agregar tú mismo esa excepción a ignoreExceptions.

Los errores no se registran ni se reintentan de forma predeterminada

recordOn y retryOn tienen como valor predeterminado Exception: un Error (por ejemplo OutOfMemoryError, AssertionError) no se reintenta y cuenta como éxito para el breaker. @Fallback(applyOn) tiene como valor predeterminado Throwable, así que un fallback sí captura los Errors a menos que los agregues a skipOn.

Los timeouts interrumpen el thread de quien llama

Un @Timeout síncrono no mueve la llamada a otro thread: se ejecuta donde la hiciste, y un watchdog compartido la interrumpe cuando se acaba el tiempo. El código que ignora las interrupciones se ejecuta hasta terminar antes de que quien llama reciba CallTimeoutException. Los timeouts nunca se disparan antes de tiempo y como mucho llegan unos dos ticks del watchdog tarde (ticks de 1–50 ms). Consulta Timeout.

Los breakers pasan a semiabierto en la siguiente llamada

No hay ningún temporizador que pase un breaker abierto a semiabierto: lo hace la primera llamada después de waitInOpen. Un snapshot tomado entre medio sigue diciendo OPEN.

La configuración se resuelve una sola vez

Los valores de las anotaciones, las configs con nombre y la configuración externa se combinan cuando se crea la instancia y nunca cambian después. No hay changeConfig, ni evento de refresco, ni recarga en caliente. Los listeners también quedan fijos cuando se construye el registry.

Autoinvocación en el estilo de interfaz

Con Resilient.of, una llamada de tu implementación a uno de sus propios métodos se salta las políticas, como un proxy de Spring. Las clases anotadas (el estilo de subclase) sí interceptan this.method(). Consulta Clases anotadas.

Las instancias son por método salvo que les des nombre

Una instancia de Resilience4j la comparte todo lo que usa su nombre. En resilience4cata cada método anotado obtiene sus propias instancias, con un id como com.acme.StockClient#stock(java.lang.String); da el mismo name a varios métodos para que compartan una (sus configuraciones resueltas deben ser entonces idénticas, R4C-REG-008). @Timeout no tiene name.

El procesador es obligatorio

Sin el procesador de anotaciones no se genera nada y Resilient.of falla con R4C-RT-003. No hay alternativa por reflexión ni por proxy.

El mismo servicio, de las dos formas

Una consulta de stock con un retry (3 intentos, separados por 500 ms, solo ante IOException), un breaker compartido con el nombre inventory, un timeout de 2 s y un fallback.

Resilience4j, con decoradores:

CircuitBreaker breaker = CircuitBreaker.of("inventory", CircuitBreakerConfig.custom()
        .failureRateThreshold(50)
        .slidingWindowSize(20)
        .minimumNumberOfCalls(10)
        .waitDurationInOpenState(Duration.ofSeconds(30))
        .permittedNumberOfCallsInHalfOpenState(3)
        .build());
Retry retry = Retry.of("inventory", RetryConfig.custom()
        .maxAttempts(3)
        .waitDuration(Duration.ofMillis(500))
        .retryExceptions(IOException.class)
        .ignoreExceptions(CallNotPermittedException.class)
        .build());
TimeLimiter timeLimiter = TimeLimiter.of(Duration.ofSeconds(2));
ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(4);

Supplier<CompletionStage<Integer>> decorated = Decorators
        .ofCompletionStage(() -> CompletableFuture.supplyAsync(() -> client.stock(sku), scheduler)) // a blocking call moved to a thread
        .withTimeLimiter(timeLimiter, scheduler)
        .withCircuitBreaker(breaker)
        .withRetry(retry, scheduler)
        .withFallback(List.of(Exception.class), e -> -1)
        .decorate();
int units = decorated.get().toCompletableFuture().join();

resilience4cata: las anotaciones en la interfaz,

public interface StockClient {

    @Fallback(method = "unknownStock")
    @Retry(name = "inventory", maxAttempts = 3, delay = "500ms", backoff = Backoff.FIXED, jitter = Jitter.NONE,
            retryOn = IOException.class)
    @CircuitBreaker(name = "inventory", failureRateThreshold = 50, windowSize = 20, minimumCalls = 10,
            waitInOpen = "30s", halfOpenCalls = 3)
    @Timeout("2s")
    int stock(String sku) throws IOException;

    default int unknownStock(String sku, Exception failure) {
        return -1;
    }
}

y el punto de llamada:

ResilienceRegistry registry = ResilienceTesting.registry(clock).build(); // ResilienceRegistry.builder() in production
StockClient stock = Resilient.of(StockClient.class, sku -> {
    calls.incrementAndGet();
    throw new IOException("inventory unreachable");
}, registry);

int units = stock.stock("SKU-1"); // three attempts 500 ms apart, then the fallback

La llamada síncrona sigue siendo síncrona: no hay executor, porque el timeout interrumpe el thread de quien llama en lugar de mover la llamada a otro.

Configuración externa. Las claves de application.yml de Spring Boot y sus equivalentes de resilience4cata en un archivo .properties (instances.inventory.* sobrescribe la anotación para esa instancia; defaults.* solo completa los atributos que la anotación no define):

# resilience4j.circuitbreaker.instances.inventory.sliding-window-size=50
instances.inventory.circuitBreaker.windowSize=50
# resilience4j.circuitbreaker.instances.inventory.wait-duration-in-open-state=10s
instances.inventory.circuitBreaker.waitInOpen=10s
# resilience4j.retry.instances.inventory.max-attempts=5
instances.inventory.retry.maxAttempts=5
# resilience4j.circuitbreaker.configs.default.failure-rate-threshold=40
defaults.circuitBreaker.failureRateThreshold=40

Cárgalo con ResilienceConfig.load() (como resilience4cata.properties en el classpath) o con ResilienceConfig.builder().classpath(…), y luego config.applyTo(ResilienceRegistry.builder()). Consulta Configuración.

Desde resilience4j-spring-boot3

resilience4cata-spring reemplaza a resilience4j-spring-boot3 en Spring Boot 4.1 o posterior (guía de Spring Boot). Quita spring-boot-starter-aop: no se teje ni se envuelve nada con proxies; el procesador de anotaciones genera las clases protegidas y la integración hace que Spring las instancie.

Las mismas claves en application.yml:

# resilience4j.circuitbreaker.instances.inventory.sliding-window-size: 50
# resilience4j.circuitbreaker.configs.default.failure-rate-threshold: 40
# resilience4j.retry.instances.inventory.max-attempts: 5
resilience4cata:
  defaults:
    circuit-breaker:
      failure-rate-threshold: 40
  instances:
    inventory:
      circuit-breaker:
        window-size: 50
      retry:
        max-attempts: 5

Las erratas detienen el arranque con el fichero y la línea de la clave, en lugar de ignorarse.

Paso a paso

1. Agrega las dependencias, incluido el procesador en el processor path (Instalación); con Spring Boot, resilience4cata-spring (más arriba).
2. Para cada llamada decorada, pon la llamada detrás de una interfaz (o anota la clase) y traduce la configuración con las tablas anteriores. Define backoff, jitter y maxWait explícitamente donde los valores predeterminados difieren.
3. Reemplaza Decorators/las anotaciones de Spring por las anotaciones de resilience4cata y Resilient.of (o Resilient.create para clases anotadas). Las llamadas que no puedas poner detrás de una interfaz pasan por un Pipeline.
4. Mueve los consumidores de eventos a ResilienceRegistry.Builder.listen(…), y las métricas al módulo de Micrometer.
5. Reemplaza las pruebas basadas en tiempo por ManualClock.
6. Compila con -Xlint:all -Werror si quieres: el código generado compila sin advertencias.