Spring Boot 4 Microservices Project - Home Energy Tracker - Circuit Breaker Pattern (Part 10)

This comprehensive study note explores the architectural integration of the Circuit Breaker Pattern into the Spring Cloud API Gateway for the Home Energy Tracker microservices project. It details how to protect downstream microservices from cascading failures, prevent resource exhaustion during service outages, and gracefully handle fallback responses using Resilience4j and Spring Boot Actuator.

1. Why Do We Need a Circuit Breaker? (The Problem Statement)

In a distributed microservices architecture, services communicate over a network. When the system is healthy, the API Gateway acts as a transparent reverse proxy, routing incoming client requests to appropriate downstream services (User Service, Device Service, Ingestion Service, Insight Service).

However, real-world networks and infrastructure are fragile.

• The Failure Cascade: If a downstream service (e.g., the User Service) crashes, experiences extreme latency, or loses database connectivity, client requests to it will begin to fail.
• The Hammering Effect: Without protection, incoming client threads will continue to pound the degraded downstream service with continuous requests. This consumes thread pools, exhausts database connections, and prevents the struggling service from recovering, eventually dragging down other dependent services.
• Poor User Experience: By default, unhandled downstream errors return ugly, opaque HTTP 500 Internal Server Error responses without any actionable context for the client.

Real-Life Analogy

Real-Life Analogy: Think of an electrical circuit breaker in your home. If a specific appliance starts drawing too much current or short-circuits, the circuit breaker trips to cut off the electricity immediately. This prevents electrical fires and protects your home appliances from frying. Once you fix the appliance, you manually or automatically reset the breaker to restore normal power flow. In microservices, the circuit breaker protects our downstream servers from electrical-like overloads when failures occur.

2. Core Mental Model: The Three States of a Circuit Breaker

The Circuit Breaker pattern operates as a finite state machine with three distinct states that govern whether requests are allowed to proceed to downstream services or intercepted immediately:

1. Closed State (Normal Operation):
   • Requests flow freely from the API Gateway to the downstream service.
   • The circuit breaker monitors and counts failures in the background using a sliding time or call window.
2. Open State (Trip & Protect):
   • Triggered when the failure rate crosses a configured threshold (e.g., 20% failure across recent calls).
   • Requests are immediately rejected at the API Gateway level without hitting the downstream service.
   • Instead of failing with a 500 error, requests are routed to a fallback handler returning a clean HTTP 503 Service Unavailable.
3. Half-Open State (Probe & Recovery Test):
   • After a configured cooling timeout (e.g., 5 seconds), the circuit breaker enters the half-open state.
   • A limited number of test requests (e.g., 2 requests) are allowed through to the downstream service to test if it has recovered.
   • If the test calls succeed, the circuit transitions back to the Closed state. If they fail, it returns immediately to the Open state.

3. Adding Required Dependencies

To implement this inside our Spring Cloud Gateway project, we must update the pom.xml to include Spring Boot Actuator (for metrics and health monitoring) and Spring Cloud Starter Circuit Breaker Resilience4j.

<dependencies>
    <!-- Spring Boot Actuator for health metrics and monitoring -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>

    <!-- Spring Cloud Circuit Breaker with Resilience4j implementation -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-circuit-breaker-resilience4j</artifactId>
    </dependency>
</dependencies>

4. Implementing Fallback Routes in API Gateway

When a circuit breaker trips or a downstream service goes down, we must intercept the failure and return a graceful fallback response instead of a raw HTTP 500 error. We configure fallback router beans in our API Gateway configuration.

Naive vs. Decoupled Fallback Implementation

• Naive Approach: Catching exceptions inside every single route filter manually, leading to massive boilerplate code duplication across routes.
• Decoupled Approach (Spring Cloud Gateway Functional Routing): Defining reusable RouterFunction beans that return standardized HTTP status codes and friendly error payloads.

@Bean
public RouterFunction<ServerResponse> userFallbackRoute() {
    return RouterFunctions.route(
        RequestPredicates.path("/fallback/user"),
        request -> ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE)
            .bodyValue("User service is down")
    );
}

5. Integrating Circuit Breaker Filters into Gateway Routes

Once the fallback route is established, we attach a Resilience4j circuit breaker filter to our primary routing definitions. This links each specific route to a unique circuit breaker ID and directs failures to our fallback endpoint (/fallback/user).

@Bean
public RouterFunction<ServerResponse> userRoutes(Builder builder) {
    return builder.route(RequestPredicates.path("/api/users/**"),
        request -> HandlerFunctions.http("http://user-service")
            .handle(request))
            .filter(CircuitBreakerFilterFunctions.circuitBreaker(
                "userServiceCircuitBreaker", 
                URI.create("forward:/fallback/user")
            ))
            .build();
}

6. Configuring Resilience4j Properties

To govern how our circuit breakers behave under load, we configure parameters inside application.properties. We set up global defaults as well as actuator exposure rules to inspect real-time circuit states.

7. Complete Microservice Circuit Breaker Matrix

We replicate the fallback routes and circuit breaker filters across all four core downstream services in our Home Energy Tracker system.

8. Step-by-Step Flow Walkthrough: When a Service Fails

1. Normal Request Flow:

   Structure & Concept Flow

   Copy DiagramCopy

   Client (Postman) -> API Gateway (/api/users/1) -> User Service (Returns 200 OK)

    

2. Downstream Service Failure & Circuit Trip:

   • User Service is stopped.
   • Client sends 4 consecutive requests through the API Gateway.
   • All 4 calls fail. Because minimum-number-of-calls is set to 4 and failure-rate-threshold is 20% (exceeded), the circuit breaker trips.
   • State transitions from CLOSED to OPEN.

3. Fallback Invocation:

   Structure & Concept Flow

   Copy DiagramCopy

   Client (Postman) -> API Gateway

   |

   [ Circuit is OPEN ]

   |

   v

   Forwards to /fallback/user

   |

   v

   Returns HTTP 503 "User service is down"

    

4. Self-Healing and Recovery Test (Half-Open):

   • After waiting 5 seconds (wait-duration-in-open-state), the circuit breaker transitions to HALF-OPEN.
   • The next 2 incoming requests (permitted-number-of-calls-in-half-open-state = 2) are allowed to probe the User Service.
   • If the User Service is restarted and responds successfully, the circuit transitions back to CLOSED.

9. Monitoring via Spring Boot Actuator

You can inspect the real-time operational status of all registered circuit breakers by invoking the Actuator endpoint:

GET http://localhost:8080/actuator/circuitbreakers

Sample JSON Response:

{
  "circuitBreakers": {
    "userServiceCircuitBreaker": {
      "status": "CLOSED",
      "failureRate": "0.0%",
      "slowCallRate": "0.0%",
      "bufferedCalls": 8,
      "failedCalls": 0
    },
    "deviceServiceCircuitBreaker": {
      "status": "HALF_OPEN",
      "failureRate": "50.0%",
      "bufferedCalls": 2,
      "failedCalls": 1
    }
  }
}

10. Summary and Key Takeaways

• System Protection: The Circuit Breaker pattern shields downstream microservices from request storms and cascading system failures during outages.
• Electrical Analogy: Just like a home fuse, the circuit breaker opens when failures exceed configured thresholds to stop hammering dead servers.
• Three States: Operates using Closed (normal flow), Open (immediate rejection + fallback), and Half-Open (probe recovery) states.
• Resilience4j Integration: Leveraging spring-cloud-starter-circuit-breaker-resilience4j provides enterprise-grade fault tolerance with minimal configuration.
• Count-Based Windows: Configured sliding windows evaluate a specific number of recent calls (e.g., evaluating the last 8 calls with a minimum of 4 calls).
• Graceful Fallbacks: Replaces cryptic HTTP 500 Internal Server errors with clean, meaningful HTTP 503 Service Unavailable messages via functional router filters.
• Real-Time Observability: Spring Boot Actuator exposes health metrics and live circuit breaker states for monitoring and debugging production environments.