From Monolith to Microservices: Scaling with Spring Boot and Spring Cloud

In today’s world, monolithic applications are rapidly being replaced by microservice architectures — where applications are divided into small, independent services that can scale, deploy, and evolve individually. monolithic applications microservice architectures — In this step-by-step tutorial, we’ll build a fully working microservices ecosystem from scratch using: build a fully working microservices ecosystem from scratch Spring Boot 3.2.x Spring Cloud Netflix Eureka (Service Discovery) Spring Cloud Gateway (API Gateway) Spring Cloud OpenFeign (Inter-Service Communication) Maven (Build Tool) Spring Boot 3.2.x Spring Boot 3.2.x Spring Cloud Netflix Eureka (Service Discovery) Spring Cloud Netflix Eureka Spring Cloud Gateway (API Gateway) Spring Cloud Gateway Spring Cloud OpenFeign (Inter-Service Communication) Spring Cloud OpenFeign Maven (Build Tool) Maven By the end, you’ll have four independent Spring Boot microservices running and talking to each other — no Docker, no complex infra, just clean Java + Spring setup. no Docker, no complex infra, Why I Used Microservices Architecture in My Project Why I Used Microservices Architecture in My Project In one of my recent projects, our monolithic application started facing several challenges as the business grew. We had multiple teams working on every small change or release caused deployment dependencies, performance bottlenecks, and testing delays. To overcome these challenges, we decided to migrate to a Microservices-based architecture using Spring Boot and Spring Cloud. migrate to a Microservices-based architecture using Spring Boot and Spring Cloud Key Pain Points in the Monolith: Key Pain Points in the Monolith: Every new feature deployment required full application redeployment. The codebase became large and tightly coupled. Database queries were shared between multiple modules. Downtime affected the entire system, even for small bugs. Every new feature deployment required full application redeployment. The codebase became large and tightly coupled. Database queries were shared between multiple modules. Downtime affected the entire system, even for small bugs. Architecture Overview Architecture Overview Our ecosystem will have four Spring Boot projects: Spring Boot projects: Service

Port

Role

Eureka Server

8761

Service registry — all services register here

Department Service

8081

Provides department data

Employee Service

8082

Provides employee data, calls department service

API Gateway

8080

Single entry point, routes requests to services Service

Port

Role

Eureka Server

8761

Service registry — all services register here

Department Service

8081

Provides department data

Employee Service

8082

Provides employee data, calls department service

API Gateway

8080

Single entry point, routes requests to services Service

Port

Role Service Service Service Port Port Port Role Role Role Eureka Server

8761

Service registry — all services register here Eureka Server Eureka Server Eureka Server 8761 8761 Service registry — all services register here Service registry — all services register here Department Service

8081

Provides department data Department Service Department Service Department Service 8081 8081 Provides department data Provides department data Employee Service

8082

Provides employee data, calls department service Employee Service Employee Service Employee Service 8082 8082 Provides employee data, calls department service Provides employee data, calls department service API Gateway

8080

Single entry point, routes requests to services API Gateway API Gateway API Gateway 8080 8080 Single entry point, routes requests to services Single entry point, routes requests to services Architecture Diagram Architecture Diagram ** ** How It Works in Real Time How It Works in Real Time Scenario 1 — Fetching an Employee’s Department Info Scenario 1 — Fetching an Employee’s Department Info When an HR manager opens an employee profile in the web app: Frontend calls GET https://api.mycompany.com/employees/1001 Request hits the API Gateway → routes to Employee Service Employee Service fetches employee details (from DB) and calls Department Service (via Feign + Eureka) to get department info. Employee Service aggregates both results and sends the response back to the Gateway → client. The client sees: Frontend calls GET https://api.mycompany.com/employees/1001 Request hits the API Gateway → routes to Employee Service API Gateway → Employee Service Employee Service fetches employee details (from DB) and calls Department Service (via Feign + Eureka) to get department info. Employee Service Department Service Employee Service aggregates both results and sends the response back to the Gateway → client. The client sees: { "employee": { "id": 1001, "name": "Alice Johnson", "departmentId": 2 }, "department": { "id": 2, "name": "Engineering" } } { "employee": { "id": 1001, "name": "Alice Johnson", "departmentId": 2 }, "department": { "id": 2, "name": "Engineering" } } Scenario 2 — Scaling Up Scenario 2 — Scaling Up During appraisal season, Employee Service traffic spikes. Since each microservice is independent, you can deploy multiple Employee Service instances (on Kubernetes, ECS, etc.). Eureka automatically registers them, and the API Gateway load-balances requests across all. During appraisal season, Employee Service traffic spikes. Employee Service Since each microservice is independent, you can deploy multiple Employee Service instances (on Kubernetes, ECS, etc.). multiple Employee Service instances Eureka automatically registers them, and the API Gateway load-balances requests across all. No config change neededNo downtimeSeamless scaling Step 1 — Create the Parent Folder Step 1 — Create the Parent Folder Create one folder to hold all projects: mkdir spring-microservices-ecosystem mkdir spring-microservices-ecosystem We’ll create four sub-modules: eureka-server department-service employee-service api-gateway eureka-server eureka-server department-service department-service employee-service employee-service api-gateway api-gateway Each module will be an independent Spring Boot Maven project. Spring Boot Maven project. Step 2 — Setup Eureka Server (Service Registry) Step 2 — Setup Eureka Server (Service Registry) Folder: eureka-server Folder: eureka-server 1️ Create pom.xml 1️ Create pom.xml 4.0.0 org.springframework.boot spring-boot-starter-parent 3.2.6 com.example eureka-server 1.0.0 17 2023.0.1 org.springframework.cloud spring-cloud-starter-netflix-eureka-server org.springframework.boot spring-boot-starter-web org.springframework.cloud spring-cloud-dependencies ${spring-cloud.version} pom import org.springframework.boot spring-boot-maven-plugin 4.0.0 org.springframework.boot spring-boot-starter-parent 3.2.6 com.example eureka-server 1.0.0 17 2023.0.1 org.springframework.cloud spring-cloud-starter-netflix-eureka-server org.springframework.boot spring-boot-starter-web org.springframework.cloud spring-cloud-dependencies ${spring-cloud.version} pom import org.springframework.boot spring-boot-maven-plugin 2️ Create main class 2️ Create main class package com.example.eurekaserver; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer; @SpringBootApplication @EnableEurekaServer public class EurekaServerApplication { public static void main(String[] args) { SpringApplication.run(EurekaServerApplication.class, args); }} package com.example.eurekaserver; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer; @SpringBootApplication @EnableEurekaServer public class EurekaServerApplication { public static void main(String[] args) { SpringApplication.run(EurekaServerApplication.class, args); }} 3️ application.yml 3️ application.yml server: port: 8761 spring: application: name: eureka-server eureka: client: register-with-eureka: false fetch-registry: false server: port: 8761 spring: application: name: eureka-server eureka: client: register-with-eureka: false fetch-registry: false Run & Verify Run & Verify Run EurekaServerApplication. Then open http://localhost:8761 — you should see the Eureka Dashboard. Run http://localhost:8761 — http://localhost:8761 http://localhost:8761 Step 3 — Create Department Service Step 3 — Create Department Service Folder: department-service Folder: department-service 1️ pom.xml 1️ pom.xml 4.0.0 org.springframework.boot spring-boot-starter-parent 3.2.6 com.example department-service 1.0.0 17 2023.0.1 org.springframework.boot spring-boot-starter-web org.springframework.cloud spring-cloud-starter-netflix-eureka-client org.springframework.cloud spring-cloud-dependencies ${spring-cloud.version} pom import org.springframework.boot spring-boot-maven-plugin 4.0.0 org.springframework.boot spring-boot-starter-parent 3.2.6 com.example department-service 1.0.0 17 2023.0.1 org.springframework.boot spring-boot-starter-web org.springframework.cloud spring-cloud-starter-netflix-eureka-client org.springframework.cloud spring-cloud-dependencies ${spring-cloud.version} pom import org.springframework.boot spring-boot-maven-plugin 2️ Main class 2️ Main class package com.example.departmentservice; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; @SpringBootApplication @EnableDiscoveryClient public class DepartmentServiceApplication { public static void main(String[] args) { SpringApplication.run(DepartmentServiceApplication.class, args);}} package com.example.departmentservice; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; @SpringBootApplication @EnableDiscoveryClient public class DepartmentServiceApplication { public static void main(String[] args) { SpringApplication.run(DepartmentServiceApplication.class, args);}} 3️ Model 3️ Model package com.example.departmentservice.model; public class Department { private Long id; private String name; public Department() {} public Department(Long id, String name) { this.id = id; this.name = name; } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } } package com.example.departmentservice.model; public class Department { private Long id; private String name; public Department() {} public Department(Long id, String name) { this.id = id; this.name = name; } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } } 4️ Controller 4️ Controller package com.example.departmentservice.controller; import com.example.departmentservice.model.Department; import org.springframework.web.bind.annotation.*; import java.util.*; @RestController @RequestMapping("/departments") public class DepartmentController { private static final List departments = Arrays.asList( new Department(1L, "Engineering"), new Department(2L, "HR"), new Department(3L, "Finance") ); @GetMapping public List getAll() { return departments; } @GetMapping("/{id}") public Department getById(@PathVariable Long id) { return departments.stream() .filter(dep -> dep.getId().equals(id)) .findFirst() .orElse(null); } } package com.example.departmentservice.controller; import com.example.departmentservice.model.Department; import org.springframework.web.bind.annotation.*; import java.util.*; @RestController @RequestMapping("/departments") public class DepartmentController { private static final List departments = Arrays.asList( new Department(1L, "Engineering"), new Department(2L, "HR"), new Department(3L, "Finance") ); @GetMapping public List getAll() { return departments; } @GetMapping("/{id}") public Department getById(@PathVariable Long id) { return departments.stream() .filter(dep -> dep.getId().equals(id)) .findFirst() .orElse(null); } } 5️ application.yml 5️ application.yml server: port: 8081 spring: application: name: department-service eureka: client: serviceUrl: defaultZone: http://localhost:8761/eureka/ server: port: 8081 spring: application: name: department-service eureka: client: serviceUrl: defaultZone: http://localhost:8761/eureka/ Step 4 — Create Employee Service (Feign Client + Eureka) Step 4 — Create Employee Service (Feign Client + Eureka) Folder: employee-service Folder: employee-service 1️pom.xml 1️pom.xml 4.0.0 org.springframework.boot spring-boot-starter-parent 3.2.6 com.example employee-service 1.0.0 17 2023.0.1 org.springframework.boot spring-boot-starter-web org.springframework.cloud spring-cloud-starter-netflix-eureka-client org.springframework.cloud spring-cloud-starter-openfeign org.springframework.cloud spring-cloud-dependencies ${spring-cloud.version} pom import org.springframework.boot spring-boot-maven-plugin 4.0.0 org.springframework.boot spring-boot-starter-parent 3.2.6 com.example employee-service 1.0.0 17 2023.0.1 org.springframework.boot spring-boot-starter-web org.springframework.cloud spring-cloud-starter-netflix-eureka-client org.springframework.cloud spring-cloud-starter-openfeign org.springframework.cloud spring-cloud-dependencies ${spring-cloud.version} pom import org.springframework.boot spring-boot-maven-plugin 2️ Main class 2️ Main class package com.example.employeeservice; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.openfeign.EnableFeignClients; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; @SpringBootApplication @EnableDiscoveryClient @EnableFeignClients public class EmployeeServiceApplication { public static void main(String[] args) { SpringApplication.run(EmployeeServiceApplication.class, args); } } package com.example.employeeservice; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.openfeign.EnableFeignClients; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; @SpringBootApplication @EnableDiscoveryClient @EnableFeignClients public class EmployeeServiceApplication { public static void main(String[] args) { SpringApplication.run(EmployeeServiceApplication.class, args); } } 3️ Feign client 3️ Feign client package com.example.employeeservice.feign; import com.example.employeeservice.model.Department; import org.springframework.cloud.openfeign.FeignClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; @FeignClient(name = "department-service") public interface DepartmentClient { @GetMapping("/departments/{id}") Department getDepartmentById(@PathVariable("id") Long id); } package com.example.employeeservice.feign; import com.example.employeeservice.model.Department; import org.springframework.cloud.openfeign.FeignClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; @FeignClient(name = "department-service") public interface DepartmentClient { @GetMapping("/departments/{id}") Department getDepartmentById(@PathVariable("id") Long id); } 4️ Models & Controller 4️ Models & Controller package com.example.employeeservice.model; public class Employee { private Long id; private String name; private Long departmentId; public Employee() {} public Employee(Long id, String name, Long departmentId) { this.id = id; this.name = name; this.departmentId = departmentId; } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public Long getDepartmentId() { return departmentId; } public void setDepartmentId(Long departmentId) { this.departmentId = departmentId; } } package com.example.employeeservice.model; public class Department { private Long id; private String name; public Department() {} public Department(Long id, String name) { this.id = id; this.name = name; } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } } package com.example.employeeservice.model; public class Employee { private Long id; private String name; private Long departmentId; public Employee() {} public Employee(Long id, String name, Long departmentId) { this.id = id; this.name = name; this.departmentId = departmentId; } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public Long getDepartmentId() { return departmentId; } public void setDepartmentId(Long departmentId) { this.departmentId = departmentId; } } package com.example.employeeservice.model; public class Department { private Long id; private String name; public Department() {} public Department(Long id, String name) { this.id = id; this.name = name; } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } } package com.example.employeeservice.controller; import com.example.employeeservice.feign.DepartmentClient; import com.example.employeeservice.model.Department; import com.example.employeeservice.model.Employee; import org.springframework.web.bind.annotation.*; import java.util.*; @RestController @RequestMapping("/employees") public class EmployeeController { private final DepartmentClient departmentClient; public EmployeeController(DepartmentClient departmentClient) { this.departmentClient = departmentClient; } private static final List employees = Arrays.asList( new Employee(1L, "Alice", 1L), new Employee(2L, "Bob", 2L), new Employee(3L, "Charlie", 1L) ); @GetMapping public List getAll() { return employees; } @GetMapping("/{id}") public Map getEmployeeWithDepartment(@PathVariable Long id) { Employee emp = employees.stream().filter(e -> e.getId().equals(id)).findFirst().orElse(null); if (emp == null) return Map.of("error", "Employee not found"); Department dept = departmentClient.getDepartmentById(emp.getDepartmentId()); return Map.of("employee", emp, "department", dept); } } package com.example.employeeservice.controller; import com.example.employeeservice.feign.DepartmentClient; import com.example.employeeservice.model.Department; import com.example.employeeservice.model.Employee; import org.springframework.web.bind.annotation.*; import java.util.*; @RestController @RequestMapping("/employees") public class EmployeeController { private final DepartmentClient departmentClient; public EmployeeController(DepartmentClient departmentClient) { this.departmentClient = departmentClient; } private static final List employees = Arrays.asList( new Employee(1L, "Alice", 1L), new Employee(2L, "Bob", 2L), new Employee(3L, "Charlie", 1L) ); @GetMapping public List getAll() { return employees; } @GetMapping("/{id}") public Map getEmployeeWithDepartment(@PathVariable Long id) { Employee emp = employees.stream().filter(e -> e.getId().equals(id)).findFirst().orElse(null); if (emp == null) return Map.of("error", "Employee not found"); Department dept = departmentClient.getDepartmentById(emp.getDepartmentId()); return Map.of("employee", emp, "department", dept); } } 5️ application.yml 5️ application.yml server: port: 8082 spring: application: name: employee-service eureka: client: serviceUrl: defaultZone: http://localhost:8761/eureka/ server: port: 8082 spring: application: name: employee-service eureka: client: serviceUrl: defaultZone: http://localhost:8761/eureka/ Step 5 — Create API Gateway Step 5 — Create API Gateway Folder: api-gateway api-gateway api-gateway 1️ pom.xml 1️ pom.xml 4.0.0 org.springframework.boot spring-boot-starter-parent 3.2.6 com.example api-gateway 1.0.0 17 2023.0.1 org.springframework.boot spring-boot-starter-webflux org.springframework.cloud spring-cloud-starter-gateway org.springframework.cloud spring-cloud-starter-netflix-eureka-client org.springframework.cloud spring-cloud-dependencies ${spring-cloud.version} pom import org.springframework.boot spring-boot-maven-plugin 4.0.0 org.springframework.boot spring-boot-starter-parent 3.2.6 com.example api-gateway 1.0.0 17 2023.0.1 org.springframework.boot spring-boot-starter-webflux org.springframework.cloud spring-cloud-starter-gateway org.springframework.cloud spring-cloud-starter-netflix-eureka-client org.springframework.cloud spring-cloud-dependencies ${spring-cloud.version} pom import org.springframework.boot spring-boot-maven-plugin 2️ Main class 2️ Main class package com.example.gateway; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class GatewayApplication { public static void main(String[] args) { SpringApplication.run(GatewayApplication.class, args); } } package com.example.gateway; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class GatewayApplication { public static void main(String[] args) { SpringApplication.run(GatewayApplication.class, args); } } 3️ application.yml 3️ application.yml server: port: 8080 spring: application: name: api-gateway cloud: gateway: discovery: locator: enabled: true lower-case-service-id: true routes: - id: employee-service uri: lb://EMPLOYEE-SERVICE predicates: - Path=/employees/** - id: department-service uri: lb://DEPARTMENT-SERVICE predicates: - Path=/departments/** eureka: client: service-url: server: port: 8080 spring: application: name: api-gateway cloud: gateway: discovery: locator: enabled: true lower-case-service-id: true routes: - id: employee-service uri: lb://EMPLOYEE-SERVICE predicates: - Path=/employees/** - id: department-service uri: lb://DEPARTMENT-SERVICE predicates: - Path=/departments/** eureka: client: service-url: Step 6 — Run the Services (Order Matters) Step 6 — Run the Services (Order Matters) # 1. Start the Eureka server Run As 🡪 EurekaServerApplication Run As 🡪 EurekaServerApplication # 2. Start Department service Run As 🡪 DepartmentServiceApplication Run As 🡪 DepartmentServiceApplication # 3. Start Employee service Run As 🡪 EmployeeServiceApplication Run As 🡪 EmployeeServiceApplication # 4. Start API Gateway Run As 🡪 GatewayApplication Run As 🡪 GatewayApplication Check the Eureka dashboard: http://localhost:8761All three clients should show up as REGISTERED. http://localhost:8761 http://localhost:8761 REGISTERED. Step 7 — Test the APIs Step 7 — Test the APIs Through Gateway Through Gateway GET http://localhost:8080/departments GET http://localhost:8080/employees GET http://localhost:8080/employees/1 GET http://localhost:8080/departments GET http://localhost:8080/departments GET http://localhost:8080/employees GET http://localhost:8080/employees GET http://localhost:8080/employees/1 GET http://localhost:8080/employees/1 Output: Output: { "employee": { "id": 1, "name": "Alice", "departmentId": 1 }, "department": { "id": 1, "name": "Engineering" } } { "employee": { "id": 1, "name": "Alice", "departmentId": 1 }, "department": { "id": 1, "name": "Engineering" } } Step 8 — Troubleshooting Step 8 — Troubleshooting Issue

Cause

Solution

Duplicate Key Exception: found duplicate key spring

Two top-level spring blocks in YAML

Merge them into one

Eureka dashboard empty

Clients not registered

Check eureka.client.service-url.defaultZone and network

Feign 404

Wrong path or service name

Ensure @FeignClient(name="department-service") matches

Port conflict

Already in use

Change server. port

Gateway 404

Wrong route predicates

Check Path and ensure /departments/** is correct Issue

Cause

Solution

Duplicate Key Exception: found duplicate key spring

Two top-level spring blocks in YAML

Merge them into one

Eureka dashboard empty

Clients not registered

Check eureka.client.service-url.defaultZone and network

Feign 404

Wrong path or service name

Ensure @FeignClient(name="department-service") matches

Port conflict

Already in use

Change server. port

Gateway 404

Wrong route predicates

Check Path and ensure /departments/** is correct Issue

Cause

Solution Issue Issue Issue Cause Cause Cause Solution Solution Solution Duplicate Key Exception: found duplicate key spring

Two top-level spring blocks in YAML

Merge them into one Duplicate Key Exception: found duplicate key spring Duplicate Key Exception: found duplicate key spring Two top-level spring blocks in YAML Two top-level spring blocks in YAML Two top-level blocks in YAML Merge them into one Merge them into one Merge them into one Eureka dashboard empty

Clients not registered

Check eureka.client.service-url.defaultZone and network Eureka dashboard empty Eureka dashboard empty Clients not registered Clients not registered Check eureka.client.service-url.defaultZone and network Check eureka.client.service-url.defaultZone and network Check and network Feign 404

Wrong path or service name

Ensure @FeignClient(name="department-service") matches Feign 404 Feign 404 Wrong path or service name Wrong path or service name Ensure @FeignClient(name="department-service") matches Ensure @FeignClient(name="department-service") matches Ensure matches Port conflict

Already in use

Change server. port Port conflict Port conflict Already in use Already in use Change server. port Change server. port Change Gateway 404

Wrong route predicates

Check Path and ensure /departments/** is correct Gateway 404 Gateway 404 Wrong route predicates Wrong route predicates Check Path and ensure /departments/** is correct Check Path and ensure /departments/** is correct Check and ensure is correct Conclusion Conclusion You’ve just built a fully functioning microservices system from scratch using Spring Boot 3.2and Spring Cloud.Each service isindependent, discoverable, and communicatesvia Feign through Eureka.The API Gateway provides a single unified entry point. fully functioning microservices system Spring Boot 3.2 independent, discoverable, communicates This same architecture is used by real enterprise systems — what you’ve built here is a production-grade foundation.