Spring Cloud و اجزای میکروسرویسSpring Cloud & Microservices Building Blocks

Picture a small restaurant with everything under one roof: chef, cashier, pantry, waiter. Need something from the pantry? A few steps away. Now turn that restaurant into a ten-branch chain across the city. Suddenly things that were "free" and obvious — "where's the pantry?", "what's today's price?", "what if one branch catches fire?" — become real, hard problems.

Splitting a monolith (an app where everything runs in a single process) into microservices (small, independent services) is exactly this. This lesson is about the tools Spring Cloud hands you for each of these newly-born problems.

Mental model: what problems does Spring Cloud actually solve?

Let's build the feel of the problem first. In a monolith, when method A called method B, it was just an in-process call — a few nanoseconds, never failed, never left things "half done." The JVM handed you these guarantees for free. The moment you move B to a separate service on another machine, that same call now crosses the network: it can slow down, time out, or die mid-flight.

The table below shows exactly how each "free gift" of the monolith turns into a microservice problem, and which Spring Cloud component answers it:

Spring Cloud is not one framework; it's a release train (BOM) that version-aligns many independent projects. Each train is tied to a specific Spring Boot version. As of mid-2025 the relevant trains are (the names are London Underground stations — a team in-joke):

• 2024.0.x ("Moorgate") → Spring Boot 3.4.x
• 2025.0.0 ("Northfields") → Spring Boot 3.5.x
• 2025.1.x ("Oakwood") → Spring Boot 4.0.x

Key point: you should never hand-write the version of individual spring-cloud-* artifacts. Pin the train via the BOM and let it choose the right version of every piece:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>2024.0.1</version> <!-- matches your Boot 3.4.x -->
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

1. Service discovery (Eureka)

Analogy: a living phone book

Imagine you want to call a friend, but his number changes every week. A fixed number written on paper goes stale fast. The fix? A central, living phone book where anyone whose number just changed re-registers themselves immediately; and instead of memorizing the number, you ask the book each time: "what's so-and-so's number right now?"

Real problem: service instances are ephemeral (short-lived, disposable) — autoscaling, restarts, and container schedulers hand out new IPs constantly. Hard-coding http://10.0.3.14:8080 is a fantasy; that IP won't exist tomorrow.

Model: a registry (Eureka Server) — the central phone book. Instances register with it on startup and heartbeat to it (a heartbeat is a small "I'm still alive" ping). Clients query (or cache) the registry to resolve a logical name like order-service to a live host list.

Eureka server

First we build the phone book itself. One annotation is enough:

@SpringBootApplication
@EnableEurekaServer
public class DiscoveryServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(DiscoveryServerApplication.class, args);
    }
}

# discovery-server application.yml
server:
  port: 8761
eureka:
  client:
    register-with-eureka: false   # the server doesn't register with itself
    fetch-registry: false
  server:
    # In dev, disable self-preservation so dead instances evict quickly.
    # In prod, LEAVE IT ON — it protects against mass-eviction during network blips.
    enable-self-preservation: true

Notice the server sets register-with-eureka: false — "I am the phone book, I don't list myself in myself." Port 8761 is Eureka's well-known convention.

A client that registers

Now a real service that wants to be listed:

# order-service application.yml
spring:
  application:
    name: order-service          # THIS becomes the registry key clients look up
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true      # register IP, not hostname (important in containers)
    lease-renewal-interval-in-seconds: 10   # heartbeat cadence

That line spring.application.name: order-service is the heart of it: this name is the key others use to find you. Nicely, just adding the spring-cloud-starter-netflix-eureka-client dependency auto-registers the app; in modern versions no annotation is required.

Senior nuances

This is where senior answers diverge from junior ones:

• Eureka is AP, not CP. This comes from the CAP theorem. CAP says that in a distributed system, when the network partitions (parts get cut off from each other), you can only have two of three: Consistency (everyone always sees one answer), Availability (you always get an answer), Partition tolerance. Since partitions are unavoidable, you effectively choose between C and A. Eureka picks Availability: rather than blocking, it serves a possibly stale registry. This is a deliberate choice — you tolerate calling a just-dead instance (your circuit breaker handles that) in exchange for the registry never being a single point of blocking failure. Consul and ZooKeeper lean CP (they prefer consistency).
• Self-preservation mode: if Eureka stops receiving the expected number of heartbeats (e.g., a network partition), it stops evicting instances, assuming the network — not the instances — failed. Great in prod, maddening in dev.
• Client-side caching: clients fetch the registry and cache it (default 30s refresh). So there's always a propagation delay between an instance dying and clients noticing — another reason resilience patterns are mandatory, not optional.

Ali's setup: the Eureka server is the backbone that lets the gateway and inter-service calls address lb://order-service instead of IPs — the same discovery registry the gateway's DiscoveryClient route locator reads from.

2. Config Server & centralized config

Analogy: the company's central notice board

Say you run a company with 50 employees and each must know "what are today's working hours?" The dumb way: hand each employee a paper slip to keep; changing the hours means editing 50 slips. The right way: a central notice board everyone reads from; you change it once, everyone sees it.

Real problem: N services × M environments = an explosion of .properties files. You also want to change config without redeploying and keep secrets (like DB passwords) out of your Docker images.

Model: a Config Server backs onto a Git repo (or Vault) and plays the role of that notice board. Clients fetch their config at startup along three axes: {application} (which service), {profile} (which environment, e.g. dev/prod), {label} (which Git branch).

Server

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication { /* ... */ }

# config-server application.yml
server:
  port: 8888
spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/acme/config-repo
          default-label: main
          search-paths: '{application}'   # one folder per service

The beautiful part: the source of truth is a Git repo. That means every config change has history, review, and rollback — just like code. The repo layout drives resolution:

config-repo/
├── application.yml            # shared defaults for ALL services
├── order-service.yml          # order-service, all profiles
├── order-service-prod.yml     # order-service, prod profile (overrides)
└── gateway.yml

application.yml is like "company-wide rules" that apply to everyone; order-service-prod.yml is like "an exception for this department in this situation" that overrides the general rules.

Client

Since Spring Boot 2.4+, use spring.config.import (the old bootstrap.yml requires the legacy bootstrap starter):

# order-service application.yml
spring:
  application:
    name: order-service
  config:
    import: "optional:configserver:http://localhost:8888"

Property precedence matters: Config Server values override local application.yml — that's the whole point, so a central change always wins. (Note that optional: at the start of the string; you'll see in the pitfalls why it's crucial.)

Runtime refresh

Here's an important subtlety: Config Server alone does not push changes. You changed the notice board, but the employees haven't looked at it yet. Clients must be told to re-pull. Two mechanisms:

1. @RefreshScope + /actuator/refresh — beans annotated @RefreshScope are destroyed and lazily recreated (lazily = on the next access) with new config after a POST to /actuator/refresh.
2. Spring Cloud Bus — broadcasts a /actuator/busrefresh over a message broker (a messaging middleman like RabbitMQ/Kafka) so you refresh all instances with one call instead of hitting each.

@RestControllerAdvice
@RefreshScope   // this bean gets rebuilt on refresh; without it, @Value is frozen at startup
public class FeatureFlags {
    @Value("${features.new-checkout:false}")
    private boolean newCheckoutEnabled;

    public boolean newCheckout() { return newCheckoutEnabled; }
}

Gotchas

• A raw @Value field on a non-refresh-scoped bean stays frozen forever. But @ConfigurationProperties beans are rebound on refresh by default (they participate in the environment change event).
• Refresh is not atomic across instances without the Bus — you'll have a window where instances disagree (some new config, some old).
• Never put secrets in plain Git. Use {cipher}-encrypted values (server-side symmetric/asymmetric key) or, better, HashiCorp Vault as a backend.

3. API Gateway — Spring Cloud Gateway

Analogy: the reception desk of a big office building

Picture an office tower with dozens of companies. If every visitor wandered up to any floor, chaos. Instead you have a reception desk at the entrance: it checks IDs (authentication), directs you to the right floor (routing), and holds back the crowd when it's busy (rate limiting). No individual company needs to hire its own guard.

Real problem: you need one ingress that handles routing, cross-cutting auth, header manipulation, rate limiting, and TLS termination (decrypting HTTPS right here) — so each service doesn't reimplement it.

Spring Cloud Gateway is reactive (built on Spring WebFlux / Netty). Reactive means non-blocking: instead of each request tying up a thread to completion, a few threads on an event loop juggle thousands of requests. So it handles high concurrency with few threads. (There is also a newer server-web-mvc variant for blocking stacks, but the reactive one is canonical.)

Core abstractions

Three words to know:

• Route = id + destination URI + predicates (conditions: when does this route match?) + filters (mutate request/response).
• Predicate: Path, Method, Header, Host, Query, After/Before/Between (time), Weight (for canary — sending, say, 5% of traffic to a new version).
• Filter: AddRequestHeader, RewritePath, CircuitBreaker, RequestRateLimiter, Retry, and custom GlobalFilters.

# gateway application.yml
spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true          # auto-create routes from Eureka service ids
          lower-case-service-id: true
      routes:
        - id: order-service
          uri: lb://order-service         # lb:// = resolve via LoadBalancer + discovery
          predicates:
            - Path=/api/orders/**
          filters:
            - RewritePath=/api/orders/(?<segment>.*), /$\{segment}
            - name: CircuitBreaker
              args:
                name: ordersCB
                fallbackUri: forward:/fallback/orders
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10   # tokens/sec
                redis-rate-limiter.burstCapacity: 20
                key-resolver: "#{@userKeyResolver}"

That lb://order-service is the payoff of discovery + load balancing: the lb:// prefix (short for load-balanced) tells the gateway "this isn't an IP, it's a logical name; resolve it from the registry to a live instance and spread the load."

A custom global filter (auth / correlation id)

A global filter is like a guard every visitor must pass:

@Component
public class AuthGlobalFilter implements GlobalFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = exchange.getRequest().getHeaders().getFirst(HttpHeaders.AUTHORIZATION);
        if (token == null || !token.startsWith("Bearer ")) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();   // short-circuit; do NOT call chain
        }
        // enrich the request going downstream
        ServerHttpRequest mutated = exchange.getRequest().mutate()
                .header("X-User-Id", extractUserId(token))
                .build();
        return chain.filter(exchange.mutate().request(mutated).build());
    }

    @Override public int getOrder() { return -100; } // run before routing filters
    private String extractUserId(String token) { /* verify + parse JWT */ return "u123"; }
}

Note that setComplete(): when the token is invalid, it closes the response right here and does not call chain.filter(...) — so the request never reaches the target service. This is called "short-circuiting."

Key resolver bean for the rate limiter (rate-limit per user, not globally):

@Bean
KeyResolver userKeyResolver() {
    return exchange -> Mono.just(
        exchange.getRequest().getHeaders().getFirst("X-User-Id"));
}

Gateway gotchas

• Never block in a filter. (Explained above.)
• Filter order matters (Ordered); global auth must precede routing/rewrite filters — just as the guard must come before the floor guide.
• The gateway is a natural chokepoint — put your coarse rate limiting and circuit breaking here, but keep fine-grained resilience inside services too (defense in depth).

Ali's setup: the gateway is the site's single ingress; routes use lb:// names resolved through Eureka, with a CircuitBreaker filter fronting each downstream so a dead service returns a fallback instead of a hung request.

4. Client-side load balancing — Spring Cloud LoadBalancer

Analogy: pick your own line, no middleman

There are two load-balancing models. The server-side model is like a bank with a central teller who tells you "go to window 3." The client-side model is like a supermarket where you see all the lines yourself and pick one — no middleman, faster, but only with your own view (you don't know how crowded the next lane just got).

Ribbon is gone; Spring Cloud LoadBalancer (SCLB) is the replacement. "Client-side" means the caller holds the instance list (from discovery) and picks one itself — no dedicated LB hop.

@Configuration
public class ClientConfig {
    @Bean
    @LoadBalanced   // this annotation is what makes lb:// resolution work
    RestClient.Builder restClientBuilder() {
        return RestClient.builder();
    }
}

// Usage — "order-service" is a Eureka logical name, resolved + balanced automatically:
String body = restClient.get()
        .uri("http://order-service/orders/{id}", id)
        .retrieve()
        .body(String.class);

That @LoadBalanced is the magic: without it, order-service is treated as a real hostname and fails. With it, Spring takes the name, asks discovery for the instance list, and picks one.

The default strategy is round-robin (take turns, one after another in order); you can swap in RandomLoadBalancer or a custom ReactorLoadBalancer. SCLB also supports health-check filtering (only pick healthy instances) and zone-aware filtering (prefer instances in the same geographic zone for lower latency). Because it's client-side, each caller balances independently — great for latency (no extra hop) but means no global view of load.

5. Resilience — Resilience4j

Analogy: the fuse in your home

Your house has a circuit breaker (fuse). When a device short-circuits, the fuse trips instantly and cuts the circuit — not out of cruelty, but because if current kept flowing, the whole house would burn. That's exactly the logic of resilience in a distributed system.

Real problem: in a distributed system, partial failure is the normal case. And the subtle bit: a slow downstream is worse than one that's fully down. Why? A dead service errors instantly and frees the thread; but a slow service holds each call for seconds, threads pile up, and you get cascading failure — one service's failure drags down its caller, which drags down its caller, all the way up.

Resilience4j gives you composable, lightweight (functional, no thread pool by default) decorators. The five patterns and the problem each solves:

Circuit breaker states

The circuit breaker is a state machine with three states:

        failure rate >= threshold
 CLOSED ─────────────────────────▶ OPEN
   ▲                                 │ wait duration elapses
   │ success rate ok                 ▼
   └──────────────── HALF_OPEN ◀─────┘
                  (allow N trial calls)

• CLOSED: calls pass (like a healthy fuse letting current through); failures are counted in a sliding window. This window can be count-based (over the last N calls) or time-based (over the last time span).
• OPEN: calls are rejected instantly with CallNotPermittedException (this is "fail fast" — the fuse has tripped); after waitDurationInOpenState, → HALF_OPEN.
• HALF_OPEN: a limited number of probe calls are let through to see if the dependency recovered; enough successes → CLOSED, a failure → back to OPEN. Like cautiously flipping the fuse back on to see if it trips again.

Configuration

resilience4j:
  circuitbreaker:
    instances:
      inventory:
        sliding-window-type: COUNT_BASED
        sliding-window-size: 20
        failure-rate-threshold: 50          # % failures to trip
        slow-call-duration-threshold: 2s
        slow-call-rate-threshold: 80        # % slow calls also trips it
        wait-duration-in-open-state: 10s
        permitted-number-of-calls-in-half-open-state: 3
        # count these as failures (don't count e.g. 404 as a fault):
        record-exceptions:
          - java.io.IOException
          - java.util.concurrent.TimeoutException
  retry:
    instances:
      inventory:
        max-attempts: 3
        wait-duration: 200ms
        enable-exponential-backoff: true
        exponential-backoff-multiplier: 2
        retry-exceptions:
          - java.io.IOException
  bulkhead:
    instances:
      inventory:
        max-concurrent-calls: 25
  ratelimiter:
    instances:
      inventory:
        limit-for-period: 100     # 100 calls...
        limit-refresh-period: 1s  # ...per second
        timeout-duration: 0       # don't wait for a permit; fail fast
  timelimiter:
    instances:
      inventory:
        timeout-duration: 3s
        cancel-running-future: true

Note slow-call-rate-threshold: the breaker doesn't only trip on explicit errors — it also trips if 80% of calls are slow, because as we said, slow is more dangerous than dead. And enable-exponential-backoff means it doubles the gap between retry attempts (200ms, 400ms, 800ms) to give the shaky dependency room to breathe.

Real code example: layered resilience with a fallback

@Service
public class InventoryClient {

    private final RestClient restClient;

    public InventoryClient(RestClient.Builder lbBuilder) {
        this.restClient = lbBuilder.baseUrl("http://inventory-service").build();
    }

    // Annotations stack; each names a config instance above.
    // 'fallbackMethod' MUST have the same signature + a trailing Throwable param.
    @CircuitBreaker(name = "inventory", fallbackMethod = "fallbackStock")
    @Retry(name = "inventory")             // note: applies ONLY to retryable exceptions
    @Bulkhead(name = "inventory")
    public int stockFor(String sku) {
        return restClient.get()
                .uri("/stock/{sku}", sku)
                .retrieve()
                .body(Integer.class);
    }

    // Called when the circuit is OPEN or the call ultimately fails.
    // Degrade gracefully — return a safe default, not an exception.
    public int fallbackStock(String sku, Throwable t) {
        // Distinguish "circuit open" from a real error if you want different behavior:
        if (t instanceof CallNotPermittedException) {
            log.warn("inventory circuit OPEN, serving cached stock for {}", sku);
        }
        return 0; // treat as out-of-stock rather than crashing checkout
    }
}

Critical signature rule: the fallbackMethod must have exactly the same signature as the original plus a trailing Throwable parameter — otherwise Resilience4j can't find it and errors at runtime.

For TimeLimiter the method must return a CompletableFuture (the time limiter needs an interruptible async boundary — you can't safely interrupt a blocking JDBC call):

@TimeLimiter(name = "inventory")
@CircuitBreaker(name = "inventory", fallbackMethod = "asyncFallback")
public CompletableFuture<Integer> stockAsync(String sku) {
    return CompletableFuture.supplyAsync(() -> stockFor(sku));
}
public CompletableFuture<Integer> asyncFallback(String sku, Throwable t) {
    return CompletableFuture.completedFuture(0);
}

The senior gotcha: aspect ordering of Retry vs CircuitBreaker

This is a favorite senior interview question. When you stack @Retry and @CircuitBreaker, which wraps which completely changes the semantics — and the Spring Boot default is a well-known trap.

The default decoration order (outer → inner) is:

Retry ▶ CircuitBreaker ▶ RateLimiter ▶ TimeLimiter ▶ Bulkhead ▶ method

So by default Retry is the outermost aspect and wraps CircuitBreaker. That is usually what you want: each retry attempt passes through the breaker and is recorded; the breaker sees per-attempt outcomes. But there's a documented pitfall (resilience4j issue #2383): with Retry outside the breaker, once the breaker is OPEN, Retry will keep re-issuing calls that the breaker instantly rejects with CallNotPermittedException — wasting attempts and, if CallNotPermittedException is in your retry-exceptions, spinning pointlessly. Conversely, if you put the breaker outermost (retry inside), a burst of retries against a flaky dependency can each be counted as a separate failure and trip the breaker far too fast.

You control it explicitly:

# Higher order value = OUTER decorator. Make the breaker outer, retry inner:
resilience4j.circuitbreaker.circuit-breaker-aspect-order=2
resilience4j.retry.retry-aspect-order=1

6. Distributed tracing — Micrometer Tracing + Zipkin

Analogy: a parcel with a tracking number

When you ship a parcel it gets a tracking number that's scanned at every stop — warehouse, truck, sorting center, your door. With that one number you can see the whole journey and pinpoint exactly where it got stuck. Distributed tracing is that, for a request.

Real problem: one user request fans out through gateway → order → inventory → payment. When it's slow or broken, a single-service log tells you nothing ("my part was fine"). You need one trace stitching all spans together.

In Spring Boot 3, Spring Cloud Sleuth is gone; tracing moved into Micrometer Tracing (a facade over Brave/Zipkin or OpenTelemetry — a uniform layer you can put different engines behind). Concepts:

• Trace: the whole request, identified by a traceId (the parcel's tracking number).
• Span: one unit of work (an HTTP call, a DB query), with a spanId and a parent (each scan at a stop).
• Context propagation: the traceId/spanId ride along in HTTP headers (traceparent for the W3C standard, or B3 headers for Brave) so the next service continues the same trace instead of starting a fresh one.

Dependencies (Brave → Zipkin flavor):

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<dependency>
  <groupId>io.zipkin.reporter2</groupId>
  <artifactId>zipkin-reporter-brave</artifactId>
</dependency>

management:
  tracing:
    sampling:
      probability: 1.0     # trace 100% in dev; sample down (e.g. 0.1) in prod for volume
  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans

Add trace ids to logs so you can grep a whole request across services:

logging:
  pattern:
    level: "%5p [${spring.application.name},%X{traceId:-},%X{spanId:-}]"

Good news: RestClient/WebClient/RestTemplate built from Spring's auto-configured builders are auto-instrumented — propagation and span creation happen without a single line of code. For manual spans (when you want to measure a specific piece of code separately):

@Autowired ObservationRegistry registry;

Observation.createNotStarted("inventory.reserve", registry)
    .observe(() -> inventoryClient.reserve(sku));   // creates a child span

Tracing gotchas

• Sampling is a cost/visibility tradeoff. 100% in prod will crush your collector (the server that gathers spans); use tail-based or probabilistic sampling, but keep it consistent so a sampled trace is complete end-to-end (not cut off halfway).
• Trace context propagates automatically only across instrumented boundaries. Manual thread pools, @Async, or message queues can lose context — you must wrap the executor (ContextExecutorService) or propagate headers on messages.
• Tracing ≠ metrics ≠ logs. The mature setup is all three correlated by traceId (the "three pillars" of observability).

Common pitfalls & best practices

Treat these like a pre-flight checklist:

• Resilience is not optional. Discovery has propagation lag; instances die between heartbeats. Every network call needs a timeout + breaker + fallback, or you'll cascade.
• Set timeouts everywhere. The default RestTemplate/HTTP client timeout is often infinite. A missing connect/read timeout is the single most common cause of thread-pool exhaustion.
• Don't retry non-idempotent operations blindly. ("Idempotent" means an operation whose repeated execution has the same effect as running it once — like "set the value to 5." But "subtract 5" is not idempotent.) Retrying a POST that already succeeded but whose response was lost = duplicate orders. Use idempotency keys.
• Fallbacks should degrade, not lie. Returning cached/empty data is fine; returning fabricated success that corrupts state is not.
• Config Server is a dependency — if it's down at startup and you used a non-optional: import, apps won't boot. Use optional: + sane local defaults, or fail-fast intentionally.
• Keep the gateway thin and non-blocking. Business logic belongs in services.
• Pin the BOM, never mix train versions. Version skew across spring-cloud-* artifacts is a top source of NoSuchMethodError at runtime.

Interview Questions

Now let's fold everything you learned into senior-style Q&A. Try answering each yourself first, then open the answer.

@Retry(name = "payment", fallbackMethod = "fb")
public PaymentResult charge(Order o) {
    return paymentClient.charge(o); // POST, no idempotency key
}