Introduction to Microservices

// ── Monolith vs Microservices (conceptual structure) ─────────────────

// MONOLITH — single deployable unit:
//
//  ┌──────────────────────────────────────┐
//  │           E-Commerce App             │
//  │  ┌────────┐ ┌────────┐ ┌──────────┐ │
//  │  │  User  │ │ Order  │ │ Payment  │ │
//  │  │ Module │ │ Module │ │  Module  │ │
//  │  └────────┘ └────────┘ └──────────┘ │
//  │         Shared Database              │
//  └──────────────────────────────────────┘
//  Deploy everything together.
//  One bug can bring down the entire app.

// MICROSERVICES — independent deployable services:
//
//  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
//  │ User Service│   │Order Service│   │Pay  Service │
//  │  :8081      │   │  :8082      │   │  :8083      │
//  │  own DB     │   │  own DB     │   │  own DB     │
//  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘
//         └─────────────────┴─────────────────┘
//                    communicate via
//                  REST / gRPC / Events
//
//  Deploy, scale, and update each service independently.

// ── Core Microservices Principles ────────────────────────────────────

// 1. SINGLE RESPONSIBILITY
//    Each service owns exactly one business capability.
//    UserService  → registration, authentication, profile
//    OrderService → cart, checkout, order history
//    PayService   → billing, invoicing, refunds

// 2. DECENTRALISED DATA MANAGEMENT
//    Each service has its own database (DB-per-service pattern).
//    Services NEVER share tables or schemas directly.
//
//    UserService  → PostgreSQL (users table)
//    OrderService → MySQL     (orders table)
//    PayService   → MongoDB   (transactions collection)
//
//    Cross-service data needs → API call or event, never a JOIN.

// 3. INDEPENDENT DEPLOYABILITY
//    A team can build, test, and deploy their service
//    without coordinating with other teams.
//    Requires:  stable API contracts + backward compatibility.

// 4. DESIGNED FOR FAILURE
//    Any service can fail at any time.
//    Callers must handle timeouts, retries, and fallbacks.
//    Pattern: Circuit Breaker (Resilience4j / Hystrix).

// 5. DECENTRALISED GOVERNANCE
//    Teams choose the right tool for their service:
//    UserService  → Java / Spring Boot
//    RecommendService → Python / FastAPI
//    NotifyService    → Node.js / Express

// ── Synchronous: REST (HTTP) ──────────────────────────────────────────

// OrderService calls UserService to fetch user details:
@Service
@RequiredArgsConstructor
public class OrderService {

    private final RestTemplate restTemplate;
    // or: WebClient (non-blocking), OpenFeign (declarative)

    public OrderResponse placeOrder(CreateOrderRequest request) {
        // Synchronous HTTP call to UserService:
        UserResponse user = restTemplate.getForObject(
            "http://user-service/api/users/" + request.getUserId(),
            UserResponse.class
        );

        // If UserService is down → this call throws → order fails.
        // Solution: circuit breaker + fallback (see Resilience4j section).

        Order order = Order.builder()
            .userId(user.getId())
            .items(request.getItems())
            .build();
        return OrderResponse.from(orderRepository.save(order));
    }
}

// ── Asynchronous: Event-driven (Kafka) ───────────────────────────────

// OrderService publishes an event; PayService consumes it independently.

// Producer (OrderService):
@Service
@RequiredArgsConstructor
public class OrderEventPublisher {

    private final KafkaTemplate<String, OrderPlacedEvent> kafkaTemplate;

    public void publish(Order order) {
        OrderPlacedEvent event = new OrderPlacedEvent(
            order.getId(), order.getUserId(), order.getTotalAmount()
        );
        kafkaTemplate.send("order.placed", event);
        // OrderService continues immediately — does not wait for PayService.
    }
}

// Consumer (PayService):
@Service
public class PaymentEventListener {

    @KafkaListener(topics = "order.placed", groupId = "pay-service")
    public void handleOrderPlaced(OrderPlacedEvent event) {
        // PayService processes payment independently.
        paymentProcessor.charge(event.getUserId(), event.getAmount());
    }
}

// ── Spring Cloud Gateway configuration ───────────────────────────────

// pom.xml:
// <dependency>
//   <groupId>org.springframework.cloud</groupId>
//   <artifactId>spring-cloud-starter-gateway</artifactId>
// </dependency>

// application.yml:
// spring:
//   cloud:
//     gateway:
//       routes:
//         - id: user-service
//           uri: lb://user-service        # 'lb://' = load-balanced via Eureka
//           predicates:
//             - Path=/api/users/**
//           filters:
//             - StripPrefix=1
//
//         - id: order-service
//           uri: lb://order-service
//           predicates:
//             - Path=/api/orders/**
//           filters:
//             - StripPrefix=1

// ── Programmatic route definition: ───────────────────────────────────
@Configuration
public class GatewayConfig {

    @Bean
    public RouteLocator routes(RouteLocatorBuilder builder) {
        return builder.routes()

            .route("user-service", r -> r
                .path("/api/users/**")
                .filters(f -> f
                    .stripPrefix(1)
                    .addRequestHeader("X-Gateway-Source", "api-gateway"))
                .uri("lb://user-service"))

            .route("order-service", r -> r
                .path("/api/orders/**")
                .filters(f -> f.stripPrefix(1))
                .uri("lb://order-service"))

            .build();
    }
}

// ── Client request flow: ──────────────────────────────────────────────
//
//  Mobile/Browser
//       │
//       ▼
//  API Gateway  :8080
//       │
//       ├── /api/users/**  ──▶  UserService  :8081
//       ├── /api/orders/** ──▶  OrderService :8082
//       └── /api/pay/**    ──▶  PayService   :8083
//
//  Client knows only the gateway URL.
//  Internal service ports/hosts are never exposed.

// ── Eureka Server (the registry): ────────────────────────────────────

// pom.xml:
// <dependency>
//   <groupId>org.springframework.cloud</groupId>
//   <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
// </dependency>

@SpringBootApplication
@EnableEurekaServer                    // turn this app into the registry
public class EurekaServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(EurekaServerApplication.class, args);
    }
}

// application.yml (Eureka Server):
// server:
//   port: 8761
// eureka:
//   client:
//     register-with-eureka: false    # server does not register itself
//     fetch-registry: false

// ── Eureka Client (every microservice): ──────────────────────────────

// pom.xml:
// <dependency>
//   <groupId>org.springframework.cloud</groupId>
//   <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
// </dependency>

@SpringBootApplication
@EnableDiscoveryClient                 // register with Eureka on startup
public class UserServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(UserServiceApplication.class, args);
    }
}

// application.yml (UserService):
// spring:
//   application:
//     name: user-service             # name used in registry + lb:// URIs
// eureka:
//   client:
//     service-url:
//       defaultZone: http://localhost:8761/eureka/

// ── Load-balanced RestTemplate via Eureka: ───────────────────────────
@Configuration
public class AppConfig {

    @Bean
    @LoadBalanced          // resolves lb://service-name via Eureka
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

// Usage in OrderService:
// restTemplate.getForObject("http://user-service/api/users/1", ...)
// Spring resolves "user-service" to a real host:port from the registry.

// pom.xml:
// <dependency>
//   <groupId>io.github.resilience4j</groupId>
//   <artifactId>resilience4j-spring-boot3</artifactId>
// </dependency>
// <dependency>
//   <groupId>org.springframework.boot</groupId>
//   <artifactId>spring-boot-starter-aop</artifactId>
// </dependency>

// application.yml:
// resilience4j:
//   circuitbreaker:
//     instances:
//       userService:
//         sliding-window-size: 10          # evaluate last 10 calls
//         failure-rate-threshold: 50       # open if ≥ 50 % fail
//         wait-duration-in-open-state: 10s # stay open for 10 s, then half-open
//         permitted-number-of-calls-in-half-open-state: 3

// ── Annotated usage: ──────────────────────────────────────────────────
@Service
@RequiredArgsConstructor
public class OrderService {

    private final RestTemplate restTemplate;

    // CircuitBreaker wraps this method.
    // fallbackMethod is called when the circuit is open OR the call fails.
    @CircuitBreaker(name = "userService", fallbackMethod = "fallbackUser")
    public UserResponse getUser(Long userId) {
        return restTemplate.getForObject(
            "http://user-service/api/users/" + userId,
            UserResponse.class
        );
    }

    // Fallback — same return type, extra Throwable parameter:
    private UserResponse fallbackUser(Long userId, Throwable ex) {
        // Return a cached/default response instead of propagating the error.
        return UserResponse.builder()
            .id(userId)
            .name("Unknown User")
            .build();
    }

    // ── Circuit states: ───────────────────────────────────────────────
    // CLOSED   → normal operation; calls pass through; failures counted.
    // OPEN     → circuit tripped; all calls return fallback immediately.
    // HALF-OPEN → after wait, a few test calls are allowed through.
    //             If they succeed → CLOSED. If they fail → OPEN again.
}