Arquitecturas Distribuidas: Sagas, Circuit Breaker, Resiliencia y Librerías Spring Boot

Paso                         Servicio       Acción                         Compensación
1. Crear pedido              pedidos        estado = PENDIENTE             estado = CANCELADO
2. Reservar stock            inventario     reservar(pedido, líneas)       liberar(pedido)
3. Cobrar                    pagos          cobrar(pedido, importe)        reembolsar(pedido)
4. Reservar transporte       envíos         reservar(pedido, dirección)    cancelarReserva(pedido)
5. Confirmar pedido          pedidos        estado = CONFIRMADO            (paso final, no se compensa)

Si falla el paso 4:
  reembolsar(pedido)  ->  liberar(pedido)  ->  pedido CANCELADO
Cada compensación usa el id del pedido como clave de idempotencia.

@Component
class SagaPedidoOrquestador {

    @Transactional
    @KafkaListener(topics = "saga.pedidos.respuestas", groupId = "orquestador")
    void alResponder(RespuestaPaso r) {
        SagaPedido saga = sagas.findById(r.pedidoId()).orElseThrow();

        switch (saga.estado()) {
            case RESERVANDO_STOCK -> {
                if (r.ok()) { saga.pasarA(COBRANDO); comandos.enviar(new Cobrar(saga.pedidoId(), saga.importe())); }
                else        { saga.pasarA(CANCELANDO); comandos.enviar(new CancelarPedido(saga.pedidoId())); }
            }
            case COBRANDO -> {
                if (r.ok()) { saga.pasarA(RESERVANDO_TRANSPORTE); comandos.enviar(new ReservarTransporte(saga.pedidoId())); }
                else        { saga.pasarA(COMPENSANDO_STOCK); comandos.enviar(new LiberarStock(saga.pedidoId())); }
            }
            case RESERVANDO_TRANSPORTE -> {
                if (r.ok()) { saga.pasarA(COMPLETADA); comandos.enviar(new ConfirmarPedido(saga.pedidoId())); }
                else        { saga.pasarA(COMPENSANDO_PAGO); comandos.enviar(new Reembolsar(saga.pedidoId())); }
            }
            case COMPENSANDO_PAGO -> { saga.pasarA(COMPENSANDO_STOCK); comandos.enviar(new LiberarStock(saga.pedidoId())); }
            case COMPENSANDO_STOCK -> { saga.pasarA(CANCELANDO); comandos.enviar(new CancelarPedido(saga.pedidoId())); }
            default -> log.warn("Respuesta inesperada {} en estado {}", r, saga.estado());
        }
        // comandos.enviar() escribe en el outbox: estado y comando se guardan juntos
    }
}

@Service
class InventarioClient {
    private final RestClient http;
    InventarioClient(RestClient.Builder b) { this.http = b.baseUrl("http://inventario").build(); }

    @CircuitBreaker(name = "inventario", fallbackMethod = "stockDesconocido")
    @Retry(name = "inventario")
    public Stock consultar(String sku) {
        return http.get().uri("/stock/{sku}", sku).retrieve().body(Stock.class);
    }

    private Stock stockDesconocido(String sku, Throwable causa) {
        return Stock.desconocido(sku);     // la tienda muestra "consultar disponibilidad"
    }
}

// application.yml
// resilience4j:
//   circuitbreaker:
//     instances:
//       inventario:
//         sliding-window-size: 20
//         failure-rate-threshold: 50            # % de fallos para abrir
//         slow-call-duration-threshold: 2s
//         slow-call-rate-threshold: 80
//         wait-duration-in-open-state: 30s
//         permitted-number-of-calls-in-half-open-state: 3
//   retry:
//     instances:
//       inventario:
//         max-attempts: 3
//         wait-duration: 200ms
//         enable-exponential-backoff: true
//         retry-exceptions: [java.io.IOException, org.springframework.web.client.ResourceAccessException]

<dependencies>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-jpa</artifactId></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-oauth2-resource-server</artifactId></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency>

  <dependency><groupId>org.flywaydb</groupId><artifactId>flyway-database-postgresql</artifactId></dependency>
  <dependency><groupId>org.postgresql</groupId><artifactId>postgresql</artifactId><scope>runtime</scope></dependency>
  <dependency><groupId>io.micrometer</groupId><artifactId>micrometer-registry-prometheus</artifactId></dependency>
  <dependency><groupId>io.micrometer</groupId><artifactId>micrometer-tracing-bridge-otel</artifactId></dependency>
  <dependency><groupId>io.opentelemetry</groupId><artifactId>opentelemetry-exporter-otlp</artifactId></dependency>
  <dependency><groupId>io.github.resilience4j</groupId><artifactId>resilience4j-spring-boot3</artifactId><version>2.2.0</version></dependency>

  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-configuration-processor</artifactId><optional>true</optional></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-testcontainers</artifactId><scope>test</scope></dependency>
  <dependency><groupId>org.testcontainers</groupId><artifactId>postgresql</artifactId><scope>test</scope></dependency>
</dependencies>

management:
  server:
    port: 8081                         # solo accesible dentro del clúster
  endpoints:
    web:
      exposure:
        include: health, info, prometheus, loggers
  endpoint:
    health:
      probes:
        enabled: true                  # /actuator/health/liveness y /readiness
      show-details: when-authorized
      group:
        readiness:
          include: readinessState, db, kafka
  info:
    git:
      mode: simple                     # rama y commit si usas git-commit-id-maven-plugin

# Cambiar el nivel de log en caliente:
#   curl -X POST localhost:8081/actuator/loggers/com.acme.taskflow \
#        -H 'Content-Type: application/json' -d '{"configuredLevel":"DEBUG"}'