Microservices Design Patterns: The Complete Engineering Catalog
Master the 33 architectural blueprints for distributed transactions, event-driven streaming, API routing, resilience boundaries, and zero-trust service mesh coordination.
1. Modern Microservices Architecture Topology
The following blueprint illustrates how enterprise microservices decouple client traffic, enforce resilience boundaries, coordinate asynchronous events, and maintain data consistency:
+-----------------------------------------------------------------------------------------+
| ENTERPRISE MICROSERVICES DISTRIBUTED PATTERN TOPOLOGY |
+-----------------------------------------------------------------------------------------+
[ Mobile Client ] [ Web Client (SPA) ] [ Partner 3rd-Party API ]
\ | /
\ | /
v v v
+---------------------------------------------------------------+
| API GATEWAY / BFF (Spring Cloud Gateway) |
| - Rate Limiter (Token Bucket / Redis) |
| - JWT Authentication & Header Propagation |
| - SSL Termination & Response Compression |
+---------------------------------------------------------------+
/ \
/ \
v v
+--------------------------+ +--------------------------+
| Order Service (Pod) | | Inventory Service (Pod) |
| [Envoy Sidecar Proxy] |<-->| [Envoy Sidecar Proxy] |
| - Circuit Breaker (R4j) |mTLS| - Bulkhead Thread Pool |
| - Transactional Outbox | | - Compensating Tx Logic |
+--------------------------+ +--------------------------+
| | | |
(Local DB) (CDC Debezium) (Local DB) (CDC Debezium)
v v v v
[Postgres] +------------------+ [Postgres]
|
v
+------------------------------------+
| APACHE KAFKA EVENT STREAM HUB |
| - Topic: orders.v1 (Partitioned) |
| - Topic: inventory.v1 |
+------------------------------------+
/ \
/ \
v v
+---------------------------+ +---------------------------+
| Payment Orchestrator | | CQRS Read Model View |
| - Saga State Machine | | - ElasticSearch Engine |
| - Failure Recovery | | - Sub-5ms Query Latency |
+---------------------------+ +---------------------------+2. Distributed Data Management Patterns
In a distributed architecture, monolithic two-phase commits (2PC) do not scale. The primary challenge is maintaining data consistency across independent database boundaries:
Saga Pattern (Orchestration vs Choreography)
Executes a series of local transactions across microservices. If any step fails, the Saga coordinates compensating transactions to reverse changes in reverse order.
Transactional Outbox & CDC
Solves the dual-write problem by saving domain entity updates and pending event messages inside the same local ACID transaction. A CDC engine (Debezium) tails WAL logs to stream to Kafka.
3. Distributed Resilience & Fault Tolerance Patterns
When a downstream dependency suffers latency spikes or crashes, upstream services must prevent cascading exhaustion of connection pools and worker threads:
| 1 | // ========================================================================= |
| 2 | // CLASS MODEL & STATE MACHINE: Circuit Breaker Isolation |
| 3 | // State Invariants: CLOSED (pass) -> OPEN (fail-fast) -> HALF-OPEN (probe) |
| 4 | // Algorithm: Sliding Window Failure Threshold & Graceful Degradation |
| 5 | // ========================================================================= |
| 6 | public class PaymentProcessingService { |
| 7 | private final CircuitBreaker circuitBreaker; |
| 8 | private final PaymentGatewayClient gatewayClient; |
| 9 | |
| 10 | public PaymentProcessingService(CircuitBreakerRegistry registry, PaymentGatewayClient client) { |
| 11 | this.gatewayClient = client; |
| 12 | this.circuitBreaker = registry.circuitBreaker("paymentGateway", |
| 13 | CircuitBreakerConfig.custom() |
| 14 | .failureRateThreshold(50.0f) // Invariant: Trip when >50% calls fail |
| 15 | .slowCallRateThreshold(70.0f) // Invariant: Trip when >70% calls exceed 2s |
| 16 | .slowCallDurationThreshold(Duration.ofSeconds(2)) |
| 17 | .waitDurationInOpenState(Duration.ofSeconds(15)) // Cool-off time |
| 18 | .slidingWindowSize(20) |
| 19 | .build()); |
| 20 | } |
| 21 | |
| 22 | // Algorithm: Protected invocation with circuit state evaluation |
| 23 | public PaymentResult chargeCard(ChargeRequest request) { |
| 24 | Supplier<PaymentResult> protectedCall = CircuitBreaker.decorateSupplier( |
| 25 | circuitBreaker, () -> gatewayClient.executeCharge(request)); |
| 26 | |
| 27 | return Try.ofSupplier(protectedCall) |
| 28 | .recover(CallNotPermittedException.class, ex -> fallbackDegradedQueue(request)) |
| 29 | .get(); |
| 30 | } |
| 31 | |
| 32 | // Fallback Algorithm: Graceful degradation via async queue |
| 33 | private PaymentResult fallbackDegradedQueue(ChargeRequest request) { |
| 34 | return PaymentResult.deferredProcessing(request.transactionId()); |
| 35 | } |
| 36 | } |
4. Microservices Pattern Comparison & Trade-Off Matrix
Systematic trade-offs between distributed coordination alternatives:
| Pattern | Primary Advantage | Operational Complexity | Failure Mode / Pitfall | Recommended Usage |
|---|---|---|---|---|
| Saga Orchestration | Central visibility, no circular events | Medium (Requires orchestrator coordinator) | Orchestrator becomes a single point of business logic bloat | Complex e-commerce checkout, payment & fulfillment |
| Transactional Outbox | Eliminates dual-write data corruption | Medium (Requires Debezium / CDC) | Duplicate messages (requires downstream idempotency) | All services publishing events to Kafka or RabbitMQ |
| Circuit Breaker | Prevents cascading thread pool exhaustion | Low (Resilience4j library integration) | Misconfigured thresholds trip during momentary blips | All synchronous HTTP / gRPC inter-service calls |
| Service Mesh (Istio) | Zero-touch mTLS, canary routing, tracing | High (50MB+ RAM and 2ms RTT per pod) | Complex xDS synchronization issues and memory bloat | Large clusters (30+ services) needing Zero-Trust mTLS |
Frequently Asked Questions (Microservices Patterns)
What is the difference between Saga Orchestration and Saga Choreography?
In Saga Choreography, microservices listen to domain events and autonomously trigger next steps without a central coordinator. This works well for simple workflows (2–4 steps). In Saga Orchestration, a dedicated orchestrator service explicitly directs participants via commands. Orchestration prevents circular dependencies and provides centralized workflow monitoring for complex multi-step distributed transactions.
Why is the Transactional Outbox pattern necessary when publishing to Kafka?
A standard service cannot atomically write to a local database and publish a message to Apache Kafka in a single transaction (dual-write problem). If the DB write succeeds but Kafka fails (or vice versa), state becomes corrupt. The Transactional Outbox pattern writes both business entities and outbox events into the same relational database transaction. A separate Debezium CDC or polling worker then guarantees at-least-once delivery to Kafka.
When should you NOT use CQRS (Command Query Responsibility Segregation)?
CQRS introduces substantial complexity: dual data models, eventual consistency latency between write and read stores, and event synchronization overhead. If your application has symmetric read/write workloads, simple relational CRUD requirements, or requires immediate read-your-own-writes consistency without eventual lag, CQRS is an anti-pattern.