Spring Cloud Basics

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        API Gateway                               │
│                    (Spring Cloud Gateway)                        │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│                     Service Discovery                            │
│                    (Eureka / Consul)                             │
└──────────┬─────────────────┬─────────────────┬──────────────────┘
           │                 │                 │
    ┌──────▼──────┐   ┌──────▼──────┐   ┌──────▼──────┐
    │  Service A  │   │  Service B  │   │  Service C  │
    │  (3 inst.)  │   │  (2 inst.)  │   │  (1 inst.)  │
    └─────────────┘   └─────────────┘   └─────────────┘
           │                 │                 │
           └─────────────────┼─────────────────┘
                             ▼
                    ┌────────────────┐
                    │  Config Server │
                    └────────────────┘

---

Quick Start - Eureka

Server

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

server:
  port: 8761
eureka:
  client:
    register-with-eureka: false
    fetch-registry: false

Client

spring:
  application:
    name: product-service
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka
  instance:
    prefer-ip-address: true

Full Reference: See service-discovery.md for Eureka HA and Config Server.

---

Quick Start - API Gateway

spring:
  cloud:
    gateway:
      routes:
        - id: product-service
          uri: lb://product-service
          predicates:
            - Path=/api/products/**
          filters:
            - StripPrefix=0

Full Reference: See gateway.md for custom filters and programmatic routes.

---

Quick Start - Circuit Breaker

@Service
public class ProductClient {

    @CircuitBreaker(name = "productService", fallbackMethod = "fallback")
    @Retry(name = "productService")
    public List<Product> getProducts() {
        return restClient.get()
            .uri("http://product-service/api/products")
            .retrieve()
            .body(new ParameterizedTypeReference<>() {});
    }

    private List<Product> fallback(Exception e) {
        return List.of();
    }
}

resilience4j:
  circuitbreaker:
    instances:
      productService:
        sliding-window-size: 10
        failure-rate-threshold: 50
        wait-duration-in-open-state: 10s

Full Reference: See resilience.md for Retry, Bulkhead, Rate Limiter, Feign.

---

Service Communication Pattern

@Service
@RequiredArgsConstructor
public class OrderService {

    private final ProductClient productClient;
    private final InventoryClient inventoryClient;
    private final PaymentClient paymentClient;

    @Transactional
    public Order createOrder(CreateOrderRequest request) {
        // 1. Verifica prodotti
        List<Product> products = request.items().stream()
            .map(item -> productClient.getProductById(item.productId()))
            .toList();

        // 2. Verifica inventario
        boolean available = inventoryClient.checkAvailability(request.items());
        if (!available) {
            throw new InsufficientInventoryException("Items not available");
        }

        // 3. Crea ordine
        Order order = Order.create(request.customerId(), products, request.items());
        order = orderRepository.save(order);

        // 4. Riserva inventario
        inventoryClient.reserveItems(order.getId(), request.items());

        // 5. Processa pagamento (con rollback)
        try {
            PaymentResult payment = paymentClient.processPayment(
                new PaymentRequest(order.getId(), order.getTotal())
            );
            order.setPaymentId(payment.paymentId());
            order.setStatus(OrderStatus.PAID);
        } catch (PaymentFailedException e) {
            inventoryClient.releaseReservation(order.getId());
            order.setStatus(OrderStatus.PAYMENT_FAILED);
            throw e;
        }

        return orderRepository.save(order);
    }
}

---

Load Balancer

@Configuration
public class LoadBalancerConfig {

    @Bean
    @LoadBalanced
    public RestClient.Builder loadBalancedRestClientBuilder() {
        return RestClient.builder();
    }
}

// Usage: use service name instead of host
restClient.get()
    .uri("http://product-service/api/products")
    .retrieve()
    .body(new ParameterizedTypeReference<>() {});

---

Distributed Tracing

management:
  tracing:
    sampling:
      probability: 1.0
  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans

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

---

Best Practices

| Do | Don't | |----|-------| | Use Service Discovery for all services | Hardcode service URLs | | Implement Circuit Breaker with fallback | Ignore failures | | Centralize config with Config Server | Duplicate configuration | | Add distributed tracing | Miss observability | | Use API Gateway as single entry point | Expose services directly |

---

When NOT to Use This Skill

• Single service - Spring Cloud adds unnecessary complexity
• Kubernetes native - Use K8s service discovery, ConfigMaps
• Simple deployments - Overhead not justified
• Specific components - Use dedicated skills for deep dives

---

Common Pitfalls

| Error | Cause | Solution | |-------|-------|----------| | No instances available | Service not registered | Verify Eureka registration | | Connection refused | Service down | Implement Circuit Breaker | | Timeout | Service slow | Configure appropriate timeouts | | Config not loading | Config server unreachable | Use fail-fast: false or fallback | | Load balancing not working | Missing @LoadBalanced | Annotate RestClient builder |

---

Anti-Patterns

| Anti-Pattern | Problem | Solution | |--------------|---------|----------| | Hardcoding service URLs | No discovery benefit | Use service names | | No circuit breaker | Cascading failures | Add Resilience4j | | Missing retry | Transient failures | Configure retry with backoff | | No config refresh | Changes need redeploy | Use @RefreshScope | | Synchronous everywhere | Tight coupling | Use async where appropriate |

---

Quick Troubleshooting

| Problem | Diagnostic | Fix | |---------|------------|-----| | Service not found | Check Eureka dashboard | Verify registration | | Config not loading | Check config server logs | Verify path, profile | | Circuit always open | Check failure threshold | Tune thresholds | | Gateway routing fails | Check predicates | Verify route config | | Load balancing not working | Check @LoadBalanced | Add annotation |

---

Reference Files

| File | Content | |------|---------| | service-discovery.md | Eureka Server/Client, Config Server | | gateway.md | API Gateway, Filters, Routes | | resilience.md | Circuit Breaker, Retry, Feign, Testing |

---

External Documentation

• Spring Cloud
• Spring Cloud Gateway
• Resilience4j