This is a Spring Microservices Back-End using Java and Spring Boot following Clean Architecture and SOLID Principles.
It serves as a template to demonstrate the implementation of microservices following some of the best development practices.
+----------------+
| Keycloak |
| (Auth Server) |
+-------+--------+
| Keycloak not yet implemented
v
+-------+--------+ +-------------------+
Client Request | API Gateway | ----------> | Discovery Server |<---
----------------------------> | (Spring) | <---------- | (EUREKA) |<- |
+-------+--------+ +-------------------+ | |
| | |
Authenticated | Request | |
| | |
v | |
Actuator +---------+---------+ AOP +-----------------+ | |
-------------------| Patient Service | ----------> | Audit Events | | |
| Prometheus | (RESTful API) | <---------- | Table | | |
v +---------+---------+ Aspect +--------+--------+ | |
+---------+--------+ | | ^ | |
| Grafana | | ------------ | | |
| Metrics & Logs | | | | Query | |
| Visualization | Write | | | | |
+---------+--------+ Logs | Write Logs | +--------+--------+ | |
| | --------------|-----| Audit Service |--- |
| Read Logs v v | +--------+--------+ |
| +-------+-------+ | |
--------------------> | Docker Volume | | |
+-------+-------+ ------------------------------
Register with Eureka
Uses Spring AOP to create Audit Events automatically whenever any API in any of the services are called and save it to persistence, allowing the controllers to be clutter-free and simple.
The API follows the modern best practices in RESTful services recommendations, like using ResponseEntity and returning ProblemDetail.
Command and Query Separation Principle to implement Business logic.
Implemented in API Gateway using Redis Rate Limiter.
Implements Transactional Outbox Pattern for sending events to guarantee 100% message delivery.
Validate architectural boundaries and verify adherence to best coding standards.
Use PMD to verify the coding style and Pitest for mutation testing.
Handle specific exceptions and return a unified and standard error response instead of an exception stack trace using Spring ProblemDetail. Example of API response for every error.
{
"type": "https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/RuntimeException.html",
"title": "Requested Patient Not Found",
"status": 404,
"detail": "Patient by the requested id not found",
"instance": "/patients/protected/v1/accounts/33bff7c7-77ee-4c51-9ee0-c870b437f82e",
"category": "Resource Not Found",
"timestamp": "2025-04-22T18:45:43.927431130Z"
}
Provides detailed documentation for all endpoints.
Decouples core business logic from presentation using request and response POJO.
Core entities have no association with JPA and are never annotated with @Entity.
// Create Patient Endpoint
{
"id": "6797e0215829937787277607",
"serviceName": "patient-service",
"location": "/patients/protected/v1/accounts",
"action": "Create",
"data": "CreatePatientRequest(firstName=Hayden, lastName=Ondricka, email=Helen21@gmail.com, dateOfBirth=977659882000, gender=MALE, address=Bernhard Cape)",
"creationDate": "2025-01-27T14:36:01.528",
"duration": "50ms",
"response": "CreatePatientResponse(id=9622e5ef-5ab7-4faf-89db-7dd970ea8ef0)"
}
// Delete Patient Endpoint
{
"id": "6797e0115829937787277605",
"serviceName": "patient-service",
"location": "/patients/protected/v1/accounts/{id}",
"action": "Delete",
"data": "e8cd23d1-4bad-44bb-9b58-a3ca89dbf793",
"creationDate": "2025-01-27T14:35:45.631",
"duration": "25ms",
"response": "Void"
},
// Read Patient by ID Endpoint
{
"id": "6797e0145829937787277606",
"serviceName": "patient-service",
"location": "/patients/protected/v1/accounts/{id}",
"action": "Read",
"data": "e8cd23d1-4bad-44bb-9b58-a3ca89dbf793",
"creationDate": "2025-01-27T14:35:48.66",
"duration": "14ms",
"response": "Error: Patient by the requested id not found"
}
- Microservices Architecture.
- Clean Architecture & Clean Code
- Command-Query Responsibility Separation (CQRS)
- SOLID Principles
- Outbox Pattern
- Mutation Testing
- Spring Dependency Injection
- Aspect-Oriented Programming (AOP)
- Rate Limiting API
- Automatic Audit Logs recording: Uses Spring AOP to store audit logs automatically.
- Event-Driven Communication: Using Kafka.
- Robust Monitoring: Real-time monitoring with Grafana, Loki, and Tempo.
- Centralized Logging & Distributed Tracing: Using Loki and Tempo.
- Database Migrations: Using Liquibase.
- Dockerized Deployment: Using Docker and Docker Compose.
- Discovery Server
- API Gateway
- Patient Service
- Audit Service
- Java 21
- Spring Boot
- Spring Cloud
- Eureka: Dynamic service registry.
- MySQL: Services data storage.
- Kafka: Event streaming for microservices.
- Keycloak: Authentication and SSO provider.
- Docker
- Grafana, Loki, Tempo: Observability stack for metrics, logging, and tracing.
- JUnit & Mockito: Unit testing and Mocking.
- ArchUnit: Architecture boundaries testing and coding standards validation.
- PMD: Validate coding standards and best practices.
- Pitest: Mutation testing.
- Swagger/OpenAPI: API documentation.
- Liquibase: Database Migrations.
- Lombok: Cleaner code with reduced boilerplate.
- Java 21
- Maven
- Docker & Docker Compose
-
Clone the Repository:
git clone https://github.com/arivan-amin/Spring-Clean-Microservices.git cd Spring-Clean-Microservices -
Build and deploy the services to Docker using JIB:
mvn clean install -
Set Environment Variables (Linux/MacOS):
export EUREKA_USER=admin export EUREKA_PASSWORD=admin*(For Windows, use `set` command)* -
Start the required backbone apps with Docker Compose:
docker compose up -d -
Start the services(Patient, Audit,...) manually or uncomment the section in docker compose file to run everything with Docker Compose:
docker compose up -d
http://localhost:8080/eureka/web
http://localhost:8080/swagger-ui.html
http://localhost:3000/dashboards
- Run Unit and Integration Tests:
mvn test
- Discovery Server: Dynamic service discovery and registry.
- API Gateway: Centralized entry point for routing and security.
- Core Module: Shared utilities and functionality.
- Storage Common Module: Contains classes related to storage and database handling shared with all modules.
- Patient Service: Manages patient data.
- Audit Service: Stores Audit Events, ensures compliance, and data integrity.
- SSO Service: Handles authentication and authorization using Keycloak.
We welcome contributions! Fork the repository, create a new branch, and submit a pull request.
This project is licensed under the MIT License. See the LICENSE file for more details.
For questions or inquiries:
- Name: Arivan Amin
- Email: arivanamin@gmail.com
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}