--- name: spring-cloud-basics description: | Spring Cloud patterns for microservices in Spring Boot 3.x. Covers Service Discovery, Config Server, API Gateway, Circuit Breaker, Load Balancing, and Distributed Tracing. USE WHEN: user mentions "spring cloud", "microservices architecture", "service discovery", "config server", "cloud native Spring" DO NOT USE FOR: specific components - use dedicated skills like `spring-cloud-gateway`, `spring-cloud-eureka`, `spring-cloud-config` allowed-tools: Read, Grep, Glob, Write, Edit --- # 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 ```java @SpringBootApplication @EnableEurekaServer public class EurekaServerApplication { public static void main(String[] args) { SpringApplication.run(EurekaServerApplication.class, args); } } ``` ```yaml server: port: 8761 eureka: client: register-with-eureka: false fetch-registry: false ``` ### Client ```yaml 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](service-discovery.md) for Eureka HA and Config Server. --- ## Quick Start - API Gateway ```yaml spring: cloud: gateway: routes: - id: product-service uri: lb://product-service predicates: - Path=/api/products/** filters: - StripPrefix=0 ``` > **Full Reference**: See [gateway.md](gateway.md) for custom filters and programmatic routes. --- ## Quick Start - Circuit Breaker ```java @Service public class ProductClient { @CircuitBreaker(name = "productService", fallbackMethod = "fallback") @Retry(name = "productService") public List getProducts() { return restClient.get() .uri("http://product-service/api/products") .retrieve() .body(new ParameterizedTypeReference<>() {}); } private List fallback(Exception e) { return List.of(); } } ``` ```yaml resilience4j: circuitbreaker: instances: productService: sliding-window-size: 10 failure-rate-threshold: 50 wait-duration-in-open-state: 10s ``` > **Full Reference**: See [resilience.md](resilience.md) for Retry, Bulkhead, Rate Limiter, Feign. --- ## Service Communication Pattern ```java @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 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 ```java @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 ```yaml 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](service-discovery.md) | Eureka Server/Client, Config Server | | [gateway.md](gateway.md) | API Gateway, Filters, Routes | | [resilience.md](resilience.md) | Circuit Breaker, Retry, Feign, Testing | --- ## External Documentation - [Spring Cloud](https://spring.io/projects/spring-cloud) - [Spring Cloud Gateway](https://docs.spring.io/spring-cloud-gateway/reference/) - [Resilience4j](https://resilience4j.readme.io/)