Practical microservices, built with .Net 8, DDD, CQRS, Event Sourcing, Vertical Slice Architecture, Event-Driven Architecture, and the latest technologies.
MIT License
π A practical and imaginary microservices for implementing an infrastructure for up and running distributed system with the latest technology and architecture like Vertical Slice Architecture, Event Sourcing, CQRS, DDD, gRpc, MongoDB, RabbitMq, Masstransit in .Net 8.
π‘ This project is not business-oriented and most of my focus was in the thechnical part for implement a distributed system with a sample project. In this project I implemented some concept in microservices like Messaging, Tracing, Event Driven Architecture, Vertical Slice Architecture, Event Sourcing, CQRS, DDD and gRpc.
Vertical Slice Architecture
for architecture
level.Domain Driven Design (DDD)
to implement all business processes
in microservices.Rabbitmq
on top of Masstransit
for Event Driven Architecture
between our microservices.gRPC
for internal communication
between our microservices.CQRS
implementation with MediatR
library.Postgres
for write side
of some microservices.MongoDB
for read side
of some microservices.Event Store
for write side
of Booking-Microservice to store all historical state
of aggregate.Inbox Pattern
for ensuring message idempotency for receiver and Exactly once Delivery
.Outbox Pattern
for ensuring no message is lost and there is at At Least One Delivery
.Unit Testing
for testing small units and mocking our dependencies with Nsubstitute
.End-To-End Testing
and Integration Testing
for testing features
with all dependencies using testcontainers
.Fluent Validation
and a Validation Pipeline Behaviour
on top of MediatR
.Minimal API
for all endpoints.Health Check
for reporting
the health
of app infrastructure components.Docker-Compose
and Kubernetes
for our deployment mechanism.Kibana
on top of Serilog
for logging
.OpenTelemetry
for distributed tracing on top of Jaeger
.OpenTelemetry
for monitoring on top of Prometheus
and Grafana
.IdentityServer
for authentication and authorization base on OpenID-Connect
and OAuth2
.Yarp
as a microservices gateway
.Kubernetes
to achieve efficient scaling
and ensure high availability
for each of our microservices.Nginx Ingress Controller
for load balancing
between our microservices top of Kubernetes
.cert-manager
to Configure TLS
in kubernetes cluster
.πThis project is a work in progress, new features will be added over time.π
I will try to register future goals and additions in the Issues section of this repository.
High-level plan is represented in the table
Feature | Status |
---|---|
API Gateway | Completed βοΈ |
Identity Service | Completed βοΈ |
Flight Service | Completed βοΈ |
Passenger Service | Completed βοΈ |
Booking Service | Completed βοΈ |
Building Blocks | Completed βοΈ |
.NET 7
- .NET Framework and .NET Core, including ASP.NET and ASP.NET CoreMVC Versioning API
- Set of libraries which add service API versioning to ASP.NET Web API, OData with ASP.NET Web API, and ASP.NET CoreEF Core
- Modern object-database mapper for .NET. It supports LINQ queries, change tracking, updates, and schema migrationsMasstransit
- Distributed Application Framework for .NET.MediatR
- Simple, unambitious mediator implementation in .NET.FluentValidation
- Popular .NET validation library for building strongly-typed validation rulesSwagger & Swagger UI
- Swagger tools for documenting API's built on ASP.NET CoreSerilog
- Simple .NET logging with fully-structured eventsPolly
- Polly is a .NET resilience and transient-fault-handling library that allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback in a fluent and thread-safe mannerScrutor
- Assembly scanning and decoration extensions for Microsoft.Extensions.DependencyInjectionOpentelemetry-dotnet
- The OpenTelemetry .NET ClientDuendeSoftware IdentityServer
- The most flexible and standards-compliant OpenID Connect and OAuth 2.x framework for ASP.NET CoreEasyCaching
- Open source caching library that contains basic usages and some advanced usages of caching which can help us to handle caching more easier.Mapster
- Convention-based object-object mapper in .NET.Hellang.Middleware.ProblemDetails
- A middleware for handling exception in .Net CoreNewId
- NewId can be used as an embedded unique ID generator that produces 128 bit (16 bytes) sequential IDsYarp
- Reverse proxy toolkit for building fast proxy servers in .NETTye
- Developer tool that makes developing, testing, and deploying microservices and distributed applications easiergRPC-dotnet
- gRPC functionality for .NET.EventStore
- The open-source, functional database with Complex Event Processing.MongoDB.Driver
- .NET Driver for MongoDB.xUnit.net
- A free, open source, community-focused unit testing tool for the .NET Framework.Respawn
- Respawn is a small utility to help in resetting test databases to a clean state.Testcontainers
- Testcontainers for .NET is a library to support tests with throwaway instances of Docker containers.K6
- Modern load testing for developers and testers in the DevOps era.Identity Service
: The Identity Service is a bounded context for the authentication and authorization of users using Identity Server. This service is responsible for creating new users and their corresponding roles and permissions using .Net Core Identity and Jwt authentication and authorization.
Flight Service
: The Flight Service is a bounded context CRUD
service to handle flight related operations.
Passenger Service
: The Passenger Service is a bounded context for managing passenger information, tracking activities and subscribing to get notification for out of stock products.
Booking Service
: The Booking Service is a bounded context for managing all operation related to booking ticket.
In this project I used a mix of clean architecture, vertical slice architecture and I used feature folder structure to structure my files.
I used yarp reverse proxy to route synchronous and asynchronous requests to the corresponding microservice. Each microservice has its dependencies such as databases, files etc. Each microservice is decoupled from other microservices and developed and deployed separately. Microservices talk to each other with Rest or gRPC for synchronous calls and use RabbitMq or Kafka for asynchronous calls.
We have a separate microservice (IdentityServer) for authentication and authorization of each request. Once signed-in users are issued a JWT token. This token is used by other microservices to validate the user, read claims and allow access to authorized/role specific endpoints.
I used RabbitMQ as my MessageBroker for async communication between microservices using the eventual consistency mechanism. Each microservice uses MassTransit to interface with RabbitMQ providing, messaging, availability, reliability, etc.
Microservices are event based
which means they can publish and/or subscribe to any events occurring in the setup. By using this approach for communicating between services, each microservice does not need to know about the other services or handle errors occurred in other microservices.
After saving data in write side, I save a Internal Command record in my Persist Messages storage (like something we do in outbox pattern) and after committing transaction in write side, trigger our command handler in read side and this handler could save their read models in our MongoDB database.
I treat each request as a distinct use case or slice, encapsulating and grouping all concerns from front-end to back.
When adding or changing a feature in an application in n-tire architecture, we are typically touching many "layers" in an application. We are changing the user interface, adding fields to models, modifying validation, and so on. Instead of coupling across a layer, we couple vertically along a slice. We minimize coupling
between slices
, and maximize coupling
in a slice
.
With this approach, each of our vertical slices can decide for itself how to best fulfill the request. New features only add code, we're not changing shared code and worrying about side effects.
Instead of grouping related action methods in one controller, as found in traditional ASP.net controllers, I used the REPR pattern. Each action gets its own small endpoint, consisting of a route, the action, and an IMediator
instance (see MediatR). The request is passed to the IMediator
instance, routed through a Mediatr pipeline
where custom middleware can log, validate and intercept requests. The request is then handled by a request specific IRequestHandler
which performs business logic before returning the result.
The use of the mediator pattern in my controllers creates clean and thin controllers. By separating action logic into individual handlers we support the Single Responsibility Principle and Don't Repeat Yourself principles, this is because traditional controllers tend to become bloated with large action methods and several injected Services
only being used by a few methods.
I used CQRS to decompose my features into small parts that makes our application:
Using the CQRS pattern, we cut each business functionality into vertical slices, for each of these slices we group classes (see technical folders structure) specific to that feature together (command, handlers, infrastructure, repository, controllers, etc). In our CQRS pattern each command/query handler is a separate slice. This is where you can reduce coupling between layers. Each handler can be a separated code unit, even copy/pasted. Thanks to that, we can tune down the specific method to not follow general conventions (e.g. use custom SQL query or even different storage). In a traditional layered architecture, when we change the core generic mechanism in one layer, it can impact all methods.
For installing our requirement packages with .NET cli tools, we need to install dotnet tool manifest
.
dotnet new tool-manifest
And after that we can restore our dotnet tools packages with .NET cli tools from .config
folder and dotnet-tools.json
file.
dotnet tool restore
Here we use husky
to handel some pre commit rules and we used conventional commits
rules and formatting
as pre commit rules, here in package.json. of course, we can add more rules for pre commit in future. (find more about husky in the documentation)
We need to install husky
package for manage
pre commits hooks
and also I add two packages @commitlint/cli
and @commitlint/config-conventional
for handling conventional commits rules in package.json.
Run the command bellow in the root of project to install all npm dependencies related to husky:
npm install
Note: In the root of project we have
.husky
folder and it hascommit-msg
file for handling conventional commits rules with provide user friendly message andpre-commit
file that we can run ourscripts
as apre-commit
hooks. that here we callformat
script from package.json for formatting purpose.
For upgrading our nuget packages to last version, we use the great package dotnet-outdated. Run the command below in the root of project to upgrade all of packages to last version:
dotnet outdated -u
Config Certificate
Run the following commands to Config SSL in your system:
dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p password
dotnet dev-certs https --trust
Note: for running this command in powershell
use $env:USERPROFILE
instead of %USERPROFILE%
dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p $CREDENTIAL_PLACEHOLDER$
dotnet dev-certs https --trust
Docker Compose
To run this app in Docker
, use the docker-compose.yaml and execute the below command at the root
of the application:
docker-compose -f ./deployments/docker-compose/docker-compose.yaml up -d
Kubernetes
To configure TLS
in the Kubernetes cluster
, we need to install cert-manager
based on the docs and run the following commands to apply TLS in our application. Here, we use Let's Encrypt to encrypt our certificate.
kubectl apply -f ./deployments/kubernetes/booking-cert-manager.yml
To apply all necessary deployments
, pods
, services
, ingress
, and config maps
, please run the following command:
kubectl apply -f ./deployments/kubernetes/booking-microservices.yml
Build
To build
all microservices, run this command in the root
of the project:
dotnet build
Run
To run
each microservice, run this command in the root of the Api
folder of each microservice where the csproj
file is located:
dotnet run
Test
To test
all microservices, run this command in the root
of the project:
dotnet test
Documentation Apis
Each microservice has a Swagger OpenAPI
. Browse to /swagger
for a list of endpoints.
As part of API testing, I created the booking.rest file which can be run with the REST Client VSCode plugin
.
If you like my work, feel free to:
Thanks a bunch for supporting me!
Thanks to all contributors, you're awesome and this wouldn't be possible without you! The goal is to build a categorized, community-driven collection of very well-known resources.
Please follow this contribution guideline to submit a pull request or create the issue.
This project is made available under the MIT license. See LICENSE for details.