About sample-spring-cloud-webflux

sample microservices demonstrating usage of spring reactive support with spring webflux and integration spring cloud, eureka, ribbon, spring cloud gateway, spring data jpa and mongodb

p

Published by

piomin

Visit View Profile

README.md

View on GitHub

Reactive Microservices with Spring WebFlux and Spring Cloud

A sample microservices architecture built with Spring WebFlux and Spring Cloud demonstrating reactive programming patterns, service discovery, and API gateway implementation.

Detailed description: Reactive Microservices with Spring WebFlux and Spring Cloud

🏗️ Architecture Overview

This project demonstrates a reactive microservices architecture with the following components:

graph TB
  Client["Client Application"]
  Gateway["Gateway Service<br/>:8090"]
  Discovery["Discovery Service<br/>(Eureka)<br/>:8761"]
  Account["Account Service<br/>:2222"]
  Customer["Customer Service<br/>:3333"]
  MongoDB[(MongoDB<br/>:27017)]

  Client --> Gateway
  Gateway --> Account
  Gateway --> Customer
  Customer --> Account
  Account --> Discovery
  Customer --> Discovery
  Gateway --> Discovery
  Account --> MongoDB
  Customer --> MongoDB

  classDef serviceBox fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
  classDef dbBox fill:#f3e5f5,stroke:#4a148c,stroke-width:2px;
  classDef gatewayBox fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px;

  class Account,Customer,Discovery serviceBox
  class MongoDB dbBox
  class Gateway gatewayBox

Architecture Patterns

Reactive Programming: Built with Spring WebFlux for non-blocking, asynchronous processing
Service Discovery: Netflix Eureka for dynamic service registration and discovery
API Gateway: Spring Cloud Gateway for routing, load balancing, and cross-cutting concerns
Microservices: Domain-driven service boundaries with independent data stores

🚀 Services

Discovery Service (Eureka Server)

Port: 8761
Purpose: Service registry for microservices discovery
Technology: Netflix Eureka Server
Endpoint: http://localhost:8761 (Eureka Dashboard)

Gateway Service (API Gateway)

Port: 8090
Purpose: Single entry point, routing, and load balancing
Technology: Spring Cloud Gateway
Routes:
- /account/** → Account Service
- /customer/** → Customer Service

Account Service

Port: 2222
Purpose: Manages customer accounts and financial data
Technology: Spring WebFlux, MongoDB Reactive
Database: MongoDB collection for accounts

Customer Service

Port: 3333
Purpose: Manages customer information and aggregates account data
Technology: Spring WebFlux, MongoDB Reactive, WebClient
Database: MongoDB collection for customers
Dependencies: Calls Account Service for account aggregation

🛠️ Technology Stack

Technology	Version	Purpose
Java	21	Runtime environment
Spring Boot	3.4.6	Application framework
Spring Cloud	2024.0.1	Microservices infrastructure
Spring WebFlux	—	Reactive web framework
Spring Cloud Gateway	—	API Gateway
Netflix Eureka	—	Service discovery
MongoDB	4.0+	NoSQL database
Maven	3.6+	Build tool

📋 Prerequisites

Before running the application locally, ensure you have:

Java 21 or higher
Maven 3.6+
MongoDB 4.0+ running on localhost:27017

MongoDB Setup

Install MongoDB:

# macOS (Homebrew)
brew install mongodb/brew/mongodb-community
# Ubuntu/Debian
sudo apt-get install mongodb
# Windows
Download from https://www.mongodb.com/try/download/community

Start MongoDB:

# macOS/Linux
sudo systemctl start mongod
# or
brew services start mongodb/brew/mongodb-community
# Windows
net start MongoDB

Verify:

mongosh --eval "db.adminCommand('ismaster')"

🚀 Running Locally

Option 1: Manual Startup (Development)

Clone:

git clone https://github.com/piomin/sample-spring-cloud-webflux.git
cd sample-spring-cloud-webflux

Build:
```
mvn clean install
```

Start services in order:

Discovery Service:

cd discovery-service
mvn spring-boot:run

Account Service (new terminal):
```
cd account-service
mvn spring-boot:run
```
Customer Service (new terminal):
```
cd customer-service
mvn spring-boot:run
```
Gateway Service (new terminal):
```
cd gateway-service
mvn spring-boot:run
```

Option 2: Using JARs

Package:
```
mvn clean package
```

Run:

java -jar discovery-service/target/discovery-service-1.1-SNAPSHOT.jar
java -jar account-service/target/account-service-1.1-SNAPSHOT.jar
java -jar customer-service/target/customer-service-1.1-SNAPSHOT.jar
java -jar gateway-service/target/gateway-service-1.1-SNAPSHOT.jar

Verification

Eureka Dashboard: http://localhost:8761
Gateway Health: http://localhost:8090/actuator/health
API endpoints: (see API section)

📡 API Documentation

All API calls go through Gateway at http://localhost:8090.

Account Service APIs

Method	Endpoint	Description
GET	`/account/`	List all accounts
GET	`/account/{id}`	Get account by ID
GET	`/account/customer/{id}`	Accounts by client
POST	`/account/`	Create new account

Create Account Example:

curl -X POST http://localhost:8090/account/ \
  -H "Content-Type: application/json" \
  -d '{
    "number": "1234567890",
    "amount": 5000,
    "customerId": "1"
  }'

Customer Service APIs

Method	Endpoint	Description
GET	`/customer/`	List all customers
GET	`/customer/{id}`	Get customer by ID
GET	`/customer/{id}/with-accounts`	Customer + accounts
POST	`/customer/`	Create new customer

Create Customer Example:

curl -X POST http://localhost:8090/customer/ \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","type":"INDIVIDUAL"}'

🔧 Development & Troubleshooting

Project Structure

sample-spring-cloud-webflux/
├── discovery-service/
├── gateway-service/
├── account-service/
├── customer-service/
├── pom.xml
└── readme.md

Common Issues

MongoDB not running: start service on localhost:27017
Eureka startup: ensure discovery-service runs first
Port conflicts: verify ports 8761, 8090, 2222, 3333

🤝 Contributing

Fork the repo
Create a branch
Make changes & add tests
Submit a PR

📄 License

Licensed under the MIT License. See LICENSE for details.

sample-spring-cloud-webflux