Eureka UP, Gateway 502 Drops — Spring Boot Microservices

Microservices with Spring Boot and Spring Cloud is a fundamental concept in modern Java development. Moving away from the 'Monolithic' architecture—where every feature lives in a single code base—to a distributed system allows for independent scaling, faster deployment cycles, and technological flexibility. However, it introduces the 'Distributed System Tax': complexity in networking, security, and data consistency.

In this guide, we'll break down exactly what Microservices with Spring Boot and Spring Cloud is, why it was designed this way, and how to use it correctly in real projects by leveraging Service Discovery, Configuration Management, and API Gateways. We focus on the Spring Cloud 2023.x release train (Leyton), ensuring your stack is ready for modern cloud environments.

By the end, you'll have both the conceptual understanding and practical code examples to use Microservices with Spring Boot and Spring Cloud with confidence, moving from a single JAR to a resilient, interconnected ecosystem.

What Is Microservices with Spring Boot and Spring Cloud and Why Does It Exist?

Microservices with Spring Boot and Spring Cloud is a core feature-set for building resilient distributed systems. While Spring Boot makes it trivial to create a standalone 'service' (like an Order Service or User Service), Spring Cloud provides the glue. It solves the problem of 'Service Discovery' (how Service A finds Service B without hardcoding IP addresses) and 'Circuit Breaking' (how to stop a failure in one service from cascading and crashing your entire ecosystem).

It exists because managing 50+ independent services manually is impossible; you need an automated infrastructure to handle the overhead. By using declarative tools like OpenFeign, Service A can call Service B just by using its name, while Eureka handles the dynamic IP mapping in the background.

package io.thecodeforge.orderservice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.openfeign.EnableFeignClients;

/**
 * io.thecodeforge Standard: High-Availability Microservice Setup
 * @EnableDiscoveryClient: Registers this service with Eureka/Consul so others can find it.
 * @EnableFeignClients: Enables declarative REST clients to call other services via name.
 */
@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients
public class OrderServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}

// --- Declarative Client Example ---
package io.thecodeforge.orderservice.client;

import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

/**
 * Using Feign for type-safe inter-service communication.
 * Hardcoded URLs are replaced by logical service names.
 */
@FeignClient(name = "inventory-service")
public interface InventoryClient {
    @GetMapping("/api/inventory/{skuCode}")
    boolean isInStock(@PathVariable("skuCode") String skuCode);
}

Common Mistakes and How to Avoid Them

When learning Microservices with Spring Boot and Spring Cloud, most developers hit the same set of gotchas. A major one is the 'Distributed Monolith,' where services are so tightly coupled that you can't update one without updating them all.

Another is neglecting 'Observability'—if a request fails across four different services, how do you trace it? Using tools like Micrometer Tracing (the successor to Sleuth) and Zipkin is non-negotiable for production debugging. Furthermore, failing to implement Circuit Breakers means that if your Payment Service hangs, your entire Checkout process will also hang until the connection times out.

# Centralized Config Example via Spring Cloud Config
spring:
  application:
    name: order-service
  config:
    import: "optional:configserver:http://forge-config-server:8888"
  cloud:
    gateway:
      routes:
        - id: order-route
          uri: lb://order-service
          predicates:
            - Path=/api/order/**

# Production-Grade Resilience4j Circuit Breaker Config
resilience4j.circuitbreaker:
  instances:
    inventoryService:
      registerHealthIndicator: true
      slidingWindowSize: 10
      minimumNumberOfCalls: 5
      permittedNumberOfCallsInHalfOpenState: 3
      waitDurationInOpenState: 10s
      failureRateThreshold: 50
      eventConsumerBufferSize: 10

Configuring Service Discovery with Eureka and Load Balancer

Service Discovery is the backbone of microservices communication. Without it, you're hardcoding IPs and ports, which breaks the moment you scale or redeploy. Netflix Eureka is the battle-tested service registry. Each service registers with its instance ID, hostname, port, and health status. The Spring Cloud LoadBalancer (replacement for Netflix Ribbon) picks a healthy instance using round-robin or custom rules.

Here's the catch: Eureka uses a heartbeat mechanism (30s by default). If a service misses three heartbeats, Eureka removes it. But a service can be 'UP' in Eureka while being completely broken — that's why custom health indicators are critical. Always implement a health endpoint that checks database, message queue, and external API availability.

Another pitfall: self-preservation mode. If Eureka loses too many heartbeats network-wide (e.g., due to a transient network partition), it stops evicting services to protect against false removals. That means your gateway might route to dead instances for minutes. Tune eureka.server.renewalPercentThreshold based on your cluster size.

package io.thecodeforge.gateway;

import org.springframework.cloud.client.loadbalancer.LoadBalanced;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class GatewayConfig {

    @Bean
    @LoadBalanced
    public RestTemplate loadBalancedRestTemplate() {
        return new RestTemplate();
    }
}

// In application.yml:
// spring:
//   cloud:
//     gateway:
//       routes:
//         - id: inventory-route
//           uri: lb://inventory-service
//           predicates:
//             - Path=/api/inventory/**

API Gateway: The Front Door to Your Microservices

An API Gateway is a single entry point that handles cross-cutting concerns: authentication, rate limiting, request/response transformation, and routing. Spring Cloud Gateway is the current standard — it's reactive (built on WebFlux) and non-blocking, meaning it can handle thousands of concurrent requests with minimal threads.

Why not a plain load balancer? A load balancer distributes traffic but doesn't understand HTTP semantics. A gateway can inspect paths, rewrite URLs, add headers, enforce rate limits per client, and handle CORS. It's also the perfect place to implement token validation (JWT) before requests reach your services, reducing duplicate auth logic.

Key configuration pitfall: route order matters. The gateway evaluates routes in the order they're defined. A generic catch-all route before a specific one will shadow all requests. Always declare specific routes first, then a fallback.

Performance note: Spring Cloud Gateway adds ~5-10ms per request in most cases. If you need sub-millisecond latency, consider running a dedicated sidecar proxy like Envoy instead. But for 95% of applications, the gateway is fine.

# Spring Cloud Gateway Configuration
spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=1
            - RemoveRequestHeader=Cookie
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/api/orders/**
          filters:
            - name: CircuitBreaker
              args:
                name: orderCircuitBreaker
                fallbackUri: forward:/fallback/orders
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20

Resilience: Circuit Breakers, Retries, and Bulkheads

In a distributed system, failures are not exceptions — they're the default. Resilience4j is the de facto library for Spring Boot applications. It provides three core patterns: - Circuit Breaker: monitors failures and opens the circuit when a threshold is hit, preventing further calls to a failing service. After a wait duration, it half-opens and tests the water. - Retry: automatically retries failed calls with exponential backoff, but must be used with an idempotent API (e.g., GET, PUT with idempotency key). - Bulkhead: limits concurrent calls to a service, preventing resource exhaustion from spilling over.

The biggest production mistake: configuring retry without a circuit breaker. If the downstream service is down, retries just amplify the load and delay the failure. Retries are for transient errors (timeouts, 503s), not for persistent failures.

Another trap: thread pool vs semaphore isolation. Resilience4j offers both. Thread pool isolation creates a separate thread pool per circuit breaker (isolated but resource-heavy). Semaphore isolation is lightweight but shares threads with the caller — a blocking downstream can still starve your application. Prefer thread pool isolation for critical paths.

Metrics to monitor: resilience4j.circuitbreaker.state.{name} and resilience4j.circuitbreaker.calls.{name} in Micrometer. Alert on OPEN state lasting more than 5 minutes.

# Resilience4j circuit breaker with retry and bulkhead
resilience4j.circuitbreaker:
  instances:
    inventoryService:
      registerHealthIndicator: true
      slidingWindowSize: 10
      minimumNumberOfCalls: 5
      permittedNumberOfCallsInHalfOpenState: 3
      waitDurationInOpenState: 10s
      failureRateThreshold: 50
      eventConsumerBufferSize: 10

resilience4j.retry:
  instances:
    inventoryService:
      maxRetryAttempts: 3
      waitDuration: 500ms
      retryExceptions:
        - org.springframework.web.client.HttpServerErrorException

resilience4j.bulkhead:
  instances:
    inventoryService:
      maxConcurrentCalls: 5
      maxWaitDuration: 100ms

Event-Driven Microservices: Why Your Synchronous Calls Are Burning Money

Stop pretending every service needs an instant reply. Synchronous HTTP calls chain services together, turning one failure into a cascade. You're paying for idle threads and lost messages. Event-driven architecture decouples services with a message broker (RabbitMQ, Kafka, or Redis Streams). Service A publishes an event and moves on. Service B picks it up when it's ready. No waiting. No cascading failures. Production systems use event sourcing to rebuild state from a log of events. Spring Cloud Stream wraps the broker with binders, so your code talks to channels, not queues. The WHY: resilience, scale, and audit trails. The HOW: define input/output channels in a functional interface, bind them via application.yml, and let Spring Cloud Stream handle serialization, retries, and dead-letter queues. This pattern saves your ass when a downstream service goes down at 3 AM.

// io.thecodeforge — java tutorial

import org.springframework.cloud.stream.function.StreamBridge;
import org.springframework.stereotype.Component;

@Component
public class OrderEventPublisher {

    private final StreamBridge streamBridge;

    public OrderEventPublisher(StreamBridge streamBridge) {
        this.streamBridge = streamBridge;
    }

    public void publishOrderCreated(String orderId) {
        // Sends an event to the 'order-created' binding — no waiting
        streamBridge.send("order-created-out-0", orderId);
    }
}

// application.yml:
// spring:
//   cloud:
//     stream:
//       bindings:
//         order-created-out-0:
//           destination: orders.topic
//           content-type: application/json
//       binders:
//         defaultRabbit:
//           type: rabbit

Reactive Microservices with Spring WebFlux: Stop Blocking, Start Scaling

Thread-per-request doesn't scale. Every blocked HTTP call ties up a thread from a finite pool. Under load, your services stall, and you throw hardware at the symptom. Reactive programming flips the model: event-loop threads handle thousands of concurrent requests with non-blocking I/O. Spring WebFlux runs on Netty and gives you reactive streams for MVC-style controllers, Mongo, R2DBC, and WebClient. The WHY: 10x throughput on the same hardware. The HOW: write controllers that return Mono (single value) or Flux (stream). Wrap blocking calls in subscribeOn to offload them. Use WebClient for non-blocking HTTP calls. You'll still write synchronous code inside a chain — just without waiting. Start small: replace one blocking REST client with reactive WebClient. Measure the thread savings. You'll convert the whole team.

// io.thecodeforge — java tutorial

import org.springframework.web.bind.annotation.*;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

@RestController
@RequestMapping("/orders")
public class ReactiveOrderController {

    private final WebClient webClient = WebClient.create("http://inventory-service");

    @GetMapping("/{orderId}/status")
    public Mono<String> getOrderStatus(@PathVariable String orderId) {
        // Non-blocking call — returns immediately, result arrives later
        return webClient.get()
                .uri("/inventory/" + orderId)
                .retrieve()
                .bodyToMono(String.class)
                .map(inventoryStatus -> "Order " + orderId + ": " + inventoryStatus);
    }
}

Stop Restarting Containers: Schema & Config Like a Pro

You don't 'create a schema in MySQL Workbench' for every microservice. You script it, version it, and automate it. Why? Because your dev, staging, and prod environments must match. Clicking around Workbench creates drift. Drift kills deployments.

Step 2: Write a Flyway or Liquibase migration script. Keep it in your microservice repo. For our employee service, a V1__create_employee_table.sql creates the schema. Step 3: Your application.properties points to a config server or environment variable for datasource URL, username, password. Hard-coding these is amateur hour.

You set spring.datasource.url and spring.jpa.hibernate.ddl-auto=validate in production. Validate means your app won't even start if the schema doesn't match your entities. That's the safety net your on-call rotation will thank you for.

// io.thecodeforge — java tutorial

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient
public class EmployeeServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(EmployeeServiceApplication.class, args);
    }
}

Run the Damn Thing: Microservice Startup in One Shot

Step 10 isn't 'run your employee microservice' from an IDE like a junior. You run it as a fat JAR or a container. Why? Because your IDE doesn't exist in production. Your microservice must boot, register with Eureka, and serve traffic — all without human fingers touching a run button.

First, mvn clean package -DskipTests. Then run java -jar target/employee-service-0.0.1-SNAPSHOT.jar. Watch the logs: you should see 'Registered instance with Eureka' and 'Started EmployeeServiceApplication'. If you don't see registration, your bootstrap.properties has a wrong eureka.client.serviceUrl.defaultZone.

Containerize it immediately. Dockerfile: FROM eclipse-temurin:17-jre-alpine, COPY target/*.jar app.jar, ENTRYPOINT ["java","-jar","/app.jar"]. Then docker run -p 8081:8081 --network microservices-net employee-service. This is your production-identical local run. Master this before you touch Kubernetes.

// io.thecodeforge — java tutorial

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/employees")
public class EmployeeController {

    private final EmployeeService service;

    public EmployeeController(EmployeeService service) {
        this.service = service;
    }

    @GetMapping("/{id}")
    public Employee getEmployee(@PathVariable Long id) {
        return service.findById(id);
    }

    @PostMapping
    public Employee createEmployee(@RequestBody Employee employee) {
        return service.save(employee);
    }
}

Testing Microservices: Contracts Beat Integration Hell

Synchronous integration tests across services are slow, brittle, and burn CI minutes. Instead, use consumer-driven contract tests with Spring Cloud Contract. Each service publishes a contract (Groovy or YAML) defining expected request/response behavior. The provider verifies against these contracts; the consumer stubs them. This catches breaking changes before deployment, without spinning up databases or message brokers. WireMock or Testcontainers handle external dependencies. For real isolation, pair contracts with in-memory test slices: @WebMvcTest for controllers, @DataJpaTest for repositories. The why: contracts decouple tests from infrastructure, making pipelines fast and deterministic. The how: start small—contract-test one inter-service API, stub everything else with Spring Cloud Contract's automatic stub generation. Run provider-side verification in your build, then let consumers test against generated stubs locally.

// io.thecodeforge — java tutorial
// Contract test for GET /users/{id}

@SpringBootTest(webEnvironment = WebEnvironment.MOCK)
@AutoConfigureMockMvc
@AutoConfigureStubRunner(
  ids = "com.example:user-service:+:stubs:8090",
  stubsMode = StubRunnerProperties.StubsMode.LOCAL
)
public class UserServiceContractTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void shouldReturnUserWhenExists() throws Exception {
        mockMvc.perform(get("/users/1"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.name").value("John"));
    }
}

Best Practices: Profile Configuration Over Environment Variables

Environment variables are global and hard to audit. Spring Boot profiles (@Profile) let you group configs by environment: application-dev.yml, application-prod.yml. Avoid scattering @Value annotations everywhere—bundle related config into @ConfigurationProperties classes with @Validated and JSR-303 annotations. For secrets, externalize to a vault (HashiCorp Vault, AWS Secrets Manager) and inject via spring.cloud.vault. Never hardcode URLs or credentials. Use spring.config.import to compose configs: spring.config.import=configserver:http://config-server:8888. Why: profiles enforce environment parity, reduce human error during deployments, and make configs testable. The how: refactor a single application.yml into three files (dev, staging, prod). Move all @Value into a single AppProperties class. Then add a spring.profiles.active=dev environment variable to launch. You'll thank yourself during audits.

// io.thecodeforge — java tutorial
// Typed config: no scattered @Value

@ConfigurationProperties(prefix = "app")
@Validated
@Component
public class AppProperties {

    @NotEmpty
    private String apiKey;
    @Min(1) @Max(65535)
    private int port;
    private List<String> allowedOrigins;

    // getters & setters
}