ارتباطِ سرویس‌ها و مسیرِ کاملِ یک درخواستService Communication & the Full Request Path

When you split an application from a monolith into microservices, something strange happens: code that yesterday was a plain method call — orderService.charge(user) — becomes a full journey across the network, with latency, errors, timeouts, dropped packets, and a service on the far end that might not answer at all. This chapter is precisely about that "gap between services": how two services talk, what path a single request travels from the moment a user taps a button until the response comes back, and how to make that path survive the real world — where the network is fundamentally unreliable.

The versions we anchor to are real and current: Spring Boot 3.5 with Spring Cloud 2025.0 (codename Northfields), released in 2025, and the official Spring gRPC 1.0 GA, which graduated from experimental to a full member of the Spring portfolio.

1) The two big families: synchronous and asynchronous

First, let's split the world in half, because 90% of architectural decisions start from this one choice.

Synchronous (request-response): service A sends a request and blocks until B's answer arrives. Like a phone call. The timing relationship is tight: both must be alive and ready at the same instant. Protocols: HTTP/REST, gRPC.

Asynchronous (message-driven): service A drops a message into an intermediary (a broker like Kafka or RabbitMQ) and returns immediately to its own work. Service B picks the message up and processes it whenever it can. Like a letter. The timing relationship is loose: sender and receiver need not be alive simultaneously.

Topology overview: services, gateway and broker | نمای کلیِ توپولوژی — سرویس‌ها، gateway و broker.

flowchart LR
  Client([Mobile / Web]) --> GW[API Gateway]
  GW --> Order[Order Service]
  GW --> User[User Service]
  Order -->|sync REST/gRPC| Payment[Payment Service]
  Order --> OrderDB[(Order DB)]
  User --> UserDB[(User DB)]
  Order -->|async event| Broker[(Kafka / RabbitMQ)]
  Broker --> Notify[Notification Service]
  Broker --> Analytics[Analytics Service]

Notice: we call payment synchronously because the user must know right then whether the transaction succeeded; but we push "send notification" and "analytics" asynchronously because the user need not wait for them. This separation is the heart of good design.

2) Synchronous communication in Spring

2-1) REST: from RestTemplate to RestClient

For years, Spring's default tool for calling HTTP was the RestTemplate class. But RestTemplate is in maintenance mode and is not recommended for new code. From Spring Framework 6.1 onward there's a modern, fluent synchronous client called RestClient that has all of RestTemplate's power but with a readable, chained API — and it reuses the same message-converter infrastructure.

// A RestClient with a base URL and a default header
@Configuration
public class HttpClients {

    @Bean
    RestClient paymentClient(RestClient.Builder builder) {
        return builder
            .baseUrl("http://payment-service")   // resolved via service discovery
            .requestInterceptor(new TraceIdPropagator()) // carry trace context forward
            .build();
    }
}

@Service
public class OrderService {
    private final RestClient paymentClient;

    public OrderService(RestClient paymentClient) {
        this.paymentClient = paymentClient;
    }

    public PaymentResult charge(ChargeRequest req) {
        return paymentClient.post()
            .uri("/payments")
            .contentType(MediaType.APPLICATION_JSON)
            .header("Idempotency-Key", req.idempotencyKey())
            .body(req)
            .retrieve()
            .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> {
                throw new PaymentRejectedException(response.getStatusText());
            })
            .body(PaymentResult.class);
    }
}

2-2) OpenFeign: the declarative client

Hand-writing the URL and body for every call is tedious. Spring Cloud OpenFeign lets you declare an HTTP call as an interface and Spring generates the implementation. You just write the contract.

@FeignClient(name = "payment-service", path = "/payments")
public interface PaymentClient {

    @PostMapping
    PaymentResult charge(@RequestHeader("Idempotency-Key") String key,
                         @RequestBody ChargeRequest req);

    @GetMapping("/{id}")
    PaymentResult find(@PathVariable("id") String id);
}

# timeout config — without this, defaults can be dangerous
spring:
  cloud:
    openfeign:
      client:
        config:
          payment-service:
            connect-timeout: 1000     # ms; establishing the connection
            read-timeout: 2000        # ms; waiting for the response
          default:
            logger-level: basic

2-3) gRPC: when speed and contract matter

REST runs on HTTP/1.1 and JSON: readable, simple, universal — but JSON is bulky and parsing it costs. gRPC is a protocol over HTTP/2 that encodes messages as compact binary with Protocol Buffers (protobuf) and generates both server and client code from a single .proto contract file. Benefits: faster, lighter, strongly typed contract, and native bidirectional streaming.

// payment.proto — the source of truth for the contract between two services
syntax = "proto3";
package payment;

service PaymentService {
  rpc Charge (ChargeRequest) returns (ChargeResponse);
}

message ChargeRequest {
  string order_id = 1;
  int64  amount_cents = 2;
  string idempotency_key = 3;
}

message ChargeResponse {
  string payment_id = 1;
  bool   approved = 2;
}

Since May 2025 the official Spring gRPC project reached 1.0 GA and became a full member of the Spring portfolio; there's now an official starter org.springframework.grpc:spring-grpc-spring-boot-starter that covers both server and client with autoconfiguration.

// Server side: implement the service generated from the proto
@Service
public class PaymentGrpcService extends PaymentServiceGrpc.PaymentServiceImplBase {

    @Override
    public void charge(ChargeRequest req, StreamObserver<ChargeResponse> obs) {
        var response = ChargeResponse.newBuilder()
            .setPaymentId(UUID.randomUUID().toString())
            .setApproved(true)
            .build();
        obs.onNext(response);   // send the response
        obs.onCompleted();      // close the stream
    }
}

3) Asynchronous communication: Kafka and RabbitMQ

When we say asynchronous, we mean we put a broker in the middle. But Kafka and RabbitMQ embody two different philosophies, and confusing them is one of the most common design mistakes.

Two broker topologies: queue vs log | توپولوژیِ دو broker — صف در برابر لاگ.

flowchart TB
  subgraph RabbitMQ [RabbitMQ: routing then delete]
    P1[Producer] --> EX{Exchange}
    EX -->|key=email| Q1[Queue email]
    EX -->|key=sms| Q2[Queue sms]
    Q1 --> C1[Worker A]
    Q2 --> C2[Worker B]
  end
  subgraph Kafka [Kafka: append-only log, retained]
    P2[Producer] --> T[(Topic: orders)]
    T --> G1[Consumer Group: billing]
    T --> G2[Consumer Group: analytics]
  end

3-1) Kafka with Spring

// Producer: publish an event
@Service
public class OrderEventPublisher {
    private final KafkaTemplate<String, OrderPlaced> kafka;

    public OrderEventPublisher(KafkaTemplate<String, OrderPlaced> kafka) {
        this.kafka = kafka;
    }

    public void publish(OrderPlaced event) {
        // key = orderId; all events for one order go to one partition => order preserved
        kafka.send("orders", event.orderId(), event);
    }
}

// Consumer
@Component
public class BillingListener {
    @KafkaListener(topics = "orders", groupId = "billing")
    public void onOrder(OrderPlaced event) {
        // must be idempotent! this message may be delivered more than once
        billing.charge(event.orderId(), event.amount());
    }
}

3-2) RabbitMQ with Spring

@Component
public class EmailListener {
    @RabbitListener(queues = "email.welcome")
    public void onSignup(UserSignedUp event) {
        emailService.sendWelcome(event.email());
    }
}

4) The full path of a request: from client to DB and back

Now let's follow a real request step by step. The user taps "Place Order." What layers does this request traverse?

1. The Client (browser/mobile) sends an HTTPS request to a domain.
2. The API Gateway (e.g., Spring Cloud Gateway) is the single entry point: it terminates TLS, checks the token with auth, applies rate limiting, generates or injects a trace id, and routes the request to the right service.
3. The Order Service receives the request, validates it, and calls the Payment Service synchronously to charge the money.
4. The Payment Service works with its own DB and returns the result.
5. The Order Service saves the order in its own DB, publishes an event (OrderPlaced) to Kafka (for async work like email), and returns the response to the gateway and from there to the client.

End-to-end trace of one request, sync path plus one async branch | ردیابیِ end-to-end یک درخواست، مسیرِ sync به‌همراهِ یک شاخهٔ async.

sequenceDiagram
    autonumber
    participant C as Client
    participant G as API Gateway
    participant O as Order Service
    participant P as Payment Service
    participant DB as Order DB
    participant K as Kafka

    C->>G: POST /orders (JWT, Idempotency-Key)
    G->>G: authN/authZ, rate limit, inject trace-id
    G->>O: POST /orders (+ trace-id, deadline)
    O->>P: charge(order) [sync, timeout 2s]
    P->>P: check Idempotency-Key
    P-->>O: 200 paymentId (approved)
    O->>DB: INSERT order (status=PAID)
    DB-->>O: ok
    O-->>K: publish OrderPlaced (fire-and-forget)
    O-->>G: 201 Created {orderId}
    G-->>C: 201 Created {orderId}
    Note over K: Notification & Analytics<br/>consume asynchronously later

5) Coordination: choreography vs orchestration

Suppose placing an order has several steps: charge payment, reserve inventory, create shipment. These steps are spread across several services. How do we coordinate them? There are two styles.

Choreography (a coordinated dance with no leader): there's no central brain. Each service listens to events, and when it sees the relevant event, does its own work and publishes a new event. Like a dance troupe where each dancer makes the next move by watching their neighbor.

Orchestration (an orchestra with a conductor): a central service (the orchestrator) stands like a conductor and commands each service in turn: "you charge the payment," "now you reserve the inventory." It knows and manages the flow.

Two coordination styles: leaderless (left) vs central conductor (right) | دو سبکِ هماهنگی — چپ بدونِ رهبر، راست با رهبرِ مرکزی.

flowchart LR
  subgraph Choreography
    O1[Order] -->|OrderPlaced| Pay1[Payment]
    Pay1 -->|Paid| Inv1[Inventory]
    Inv1 -->|Reserved| Ship1[Shipping]
  end
  subgraph Orchestration
    Orc[Order Orchestrator] --> Pay2[Payment]
    Orc --> Inv2[Inventory]
    Orc --> Ship2[Shipping]
  end

6) The Saga idea: transactions when you don't have ACID

In a monolith you'd slap on a @Transactional and if any step failed the database would roll everything back — atomicity was free. But when "charge payment" lives in the Payment database and "reserve inventory" in the Inventory database, a single transaction across both is impossible. This is where Saga enters.

Saga: PlaceOrder
  T1: charge payment      → C1: refund payment
  T2: reserve inventory   → C2: release inventory
  T3: create shipment     → C3: cancel shipment
If T3 fails → run C2 then C1 (in reverse order)

Saga state machine: forward progress and compensation on failure | ماشینِ حالتِ saga — پیش‌روی و جبران در صورتِ شکست.

stateDiagram-v2
    [*] --> PaymentCharged: T1 charge
    PaymentCharged --> InventoryReserved: T2 reserve
    InventoryReserved --> ShipmentCreated: T3 ship
    ShipmentCreated --> Completed: success
    InventoryReserved --> CompensatingT1: T3 failed
    CompensatingT1 --> Failed: refund done
    PaymentCharged --> Failed: T2 failed -> refund
    Completed --> [*]
    Failed --> [*]

7) Idempotency: the cornerstone of survival

We said the network is unreliable and messages get duplicated. Now the vital question: if the same "charge $100" request arrives twice, what happens? If you wrote it naively, it charges twice and the customer is furious. The solution: idempotency.

How it works: the client (or the calling service) generates a unique key for each logical operation (e.g., a UUID) and sends it in an Idempotency-Key header. Before doing the work, the receiving server checks this key in a table/cache: if it has seen it before, it returns the same previous response without re-executing; if it's new, it does the work and stores the result under that key.

@PostMapping("/payments")
public ResponseEntity<PaymentResult> charge(
        @RequestHeader("Idempotency-Key") String key,
        @RequestBody ChargeRequest req) {

    // if this key was already processed, return the stored response
    var existing = idempotencyStore.find(key);
    if (existing != null) {
        return ResponseEntity.ok(existing.result());
    }

    var result = paymentEngine.charge(req);       // the real work
    idempotencyStore.save(key, result);           // store for duplicate requests
    return ResponseEntity.ok(result);
}

To make storing the key safe against concurrent races, use a database unique constraint — and here's where dialects differ.

-- PostgreSQL: insert with idempotency; if the key exists, do nothing
INSERT INTO idempotency_keys (key, response, created_at)
VALUES (:key, :response, now())
ON CONFLICT (key) DO NOTHING;

-- Oracle: MERGE for the same behavior (Oracle traditionally lacked ON CONFLICT before 23ai)
MERGE INTO idempotency_keys t
USING (SELECT :key AS key FROM dual) s
ON (t.key = s.key)
WHEN NOT MATCHED THEN
  INSERT (key, response, created_at) VALUES (:key, :response, SYSTIMESTAMP);

8) Timeouts, retries with backoff and jitter

Three small tools that make the difference between a resilient system and a chain-reaction disaster.

8-1) Timeout: never wait forever

Every synchronous call must have a time ceiling. Without it, one slow downstream service can lock your threads one by one until the whole service goes to sleep. Two timeouts matter: connect-timeout (how long to wait to establish a connection) and read-timeout (how long to wait for a response).

8-2) Retry: try again, but carefully

Many errors are transient: a momentary network blip, a temporary 503. For these, retrying is reasonable. But naive retries are dangerous.

Exponential backoff: wait between each attempt, and grow the wait exponentially: 200ms, 400ms, 800ms... This gives the downstream service room to breathe.

Jitter: if all callers retry exactly 400ms later together, they form another synchronized wave. By adding a small randomness to each wait, you spread that wave out. Without jitter, all instances fail together and retry together; with jitter, attempts are spread across a wider time window.

With Resilience4j (the standard resilience library in the Spring ecosystem), these are just a few lines of config:

resilience4j:
  retry:
    instances:
      paymentApi:
        maxAttempts: 4                    # 4 attempts total (1 original + 3 retries)
        waitDuration: 200ms               # base wait
        enableExponentialBackoff: true    # 200 → 400 → 800 ...
        exponentialBackoffMultiplier: 2
        enableRandomizedWait: true        # turn jitter on
        randomizedWaitFactor: 0.5         # ±50% random jitter
        retryExceptions:
          - java.io.IOException
          - java.util.concurrent.TimeoutException
        ignoreExceptions:
          - com.acme.PaymentRejectedException   # business error: do not retry

@Retry(name = "paymentApi")
public PaymentResult charge(ChargeRequest req) {
    return paymentClient.charge(req.idempotencyKey(), req);
}

8-3) Deadline and deadline propagation

A timeout is usually "local": each hop has its own timeout. But in a chain A → B → C a problem arises. Suppose the client has a 3-second timeout. A calls B with a 3-second timeout, B calls C with a 3-second timeout. Now if B itself took 2.9 seconds and then calls C, C may work for another 3 seconds — 5.9 seconds total — while the client gave up long ago. C is doing pointless work, burning resources for a response nobody is waiting for anymore.

// A simple pattern for deadline propagation in REST
long remainingMs = deadline.toEpochMilli() - System.currentTimeMillis();
if (remainingMs <= 0) {
    throw new DeadlineExceededException("no time budget left");
}
// next call's timeout = remaining time (with a small margin)
var result = downstream.callWithTimeout(request, remainingMs - 50, deadline);

Full resilience pattern: deadline, timeout, retry, circuit breaker | الگویِ کاملِ resilience — deadline، timeout، retry، circuit breaker.

flowchart TD
  A[Incoming request + deadline] --> B{time budget left?}
  B -->|no| X[fail fast 504]
  B -->|yes| C[call downstream with remaining budget]
  C --> D{success?}
  D -->|yes| E[return result]
  D -->|transient error| F{retries left AND idempotent?}
  F -->|yes| G[wait backoff + jitter] --> B
  F -->|no| H[open circuit / fallback]

9) Contract testing: catch the broken contract before it breaks prod

The biggest fear in microservices: the Payment team changes a field in its response (amount becomes amountCents), deploys, and suddenly Order — which reads that field — breaks in production. No test caught it because each service passed its own tests. The solution: contract testing.

Two main tools: Spring Cloud Contract and Pact.

• Spring Cloud Contract: JVM-native. You write the contract with a DSL (Groovy/YAML). It supports both producer-driven and consumer-driven. From the contract it generates provider tests and ready stubs for the consumer. Best pick when all parties are Spring/JVM and you don't want a separate broker.
• Pact: consumer-driven and polyglot. The contract is generated from the consumer's tests and is in JSON, so it's language-agnostic — great when consumers are heterogeneous (e.g., a React frontend + a Java backend + a Python data service). It usually works with a central Pact Broker.

// Spring Cloud Contract — a contract in the Groovy DSL (provider side)
Contract.make {
    request {
        method 'POST'
        url '/payments'
        headers { contentType('application/json') }
        body([ orderId: 'o-1', amountCents: 5000 ])
    }
    response {
        status 200
        headers { contentType('application/json') }
        body([ paymentId: anyUuid(), approved: true ])
    }
}

10) API versioning: change without breaking

Services deploy independently, so you can't force every consumer to update in lockstep with you. You must be able to evolve your API without breaking old clients. This is where versioning enters.

Three common styles:

• URI versioning: /api/v1/orders vs /api/v2/orders. Explicit, simple, cacheable, and visible in logs — the most widely used.
• Header versioning: a custom header like X-API-Version: 2 or via Accept: application/vnd.acme.v2+json (known as "content negotiation"). The URL stays clean but it's less visible.
• Query param: /orders?version=2. Simple but pollutes caching and less recommended.

// URI versioning in Spring MVC
@RestController
@RequestMapping("/api/v2/orders")
public class OrderV2Controller {
    @GetMapping("/{id}")
    public OrderV2Dto get(@PathVariable String id) { ... }
}

11) The N+1 trap and the "chatty service"

The last and perhaps most insidious trap. In the ORM world you know the N+1 query problem: one query fetches a list of 100 orders, then in a loop it fires a separate query per order to fetch its customer — 101 queries total instead of 2. In microservices the same disaster strikes a hundred times harder, because each "query" is now a network call, not a memory access.

Classic example: the "my orders" page must show 20 orders with each one's product name. The naive code:

// Anti-pattern: N+1 over the network — one call per order
List<Order> orders = orderClient.findByUser(userId);       // 1 call
for (Order o : orders) {
    Product p = productClient.findById(o.productId());     // N separate calls! (20 times)
    o.setProductName(p.name());
}
// 21 network calls total for one page

The solutions:

• Batch/bulk endpoint: instead of N single calls, one call with a list of ids: productClient.findByIds(ids). One round trip instead of N.
• Data aggregation / BFF: a Backend-For-Frontend or aggregator layer that gathers several downstream calls (ideally in parallel) and returns one page-ready response.
• Denormalization / events: the order service caches the product name at write time (via an event) so that reads need no call at all.

// Correct: one bulk call instead of N calls
List<Order> orders = orderClient.findByUser(userId);        // 1 call
Set<String> ids = orders.stream().map(Order::productId).collect(toSet());
Map<String, Product> products = productClient.findByIds(ids) // 1 call
        .stream().collect(toMap(Product::id, identity()));
orders.forEach(o -> o.setProductName(products.get(o.productId()).name()));
// 2 calls total — not 21