search

mehdihadeli / food-delivery-microservices

🍔 A practical and imaginary food delivery microservices, built with .Net 8, MassTransit, Domain-Driven Design, CQRS, Vertical Slice Architecture, Event-Driven Architecture, and the latest technologies.
MIT License
788 stars 144 forks source link
aspnetcore clean-architecture cqrs ddd ddd-architecture ddd-example distributed-systems domain-driven-design dotnet dotnetcore event-driven-architecture masstransit message-broker message-bus microservice microservice-example microservices microservices-architecture vertical-slice-architecture

readme

🍔 Food Delivery Microservices

Coverage Status Commitizen friendly semantic-release: angular

Open in GitHub Codespaces

Food Delivery Microservices is a fictional food delivery microservices, built with .Net Core and different software architecture and technologies like Microservices Architecture, Vertical Slice Architecture , CQRS Pattern, Domain Driven Design (DDD), Event Driven Architecture. For communication between independent services, we use asynchronous messaging with using rabbitmq on top of MassTransit library, and sometimes we use synchronous communication for real-time communications with using REST and gRPC calls.

💡 This application is not business oriented and my focus is mostly on technical part, I just want to implement a sample with using different technologies, software architecture design, principles and all the thing we need for creating a microservices app.

Warning This project is in progress. I add new features over the time. You can check the Release Notes.

🎯 This Application ported to modular monolith approach in food-delivery-modular-monolith repository, we can choose best fit architecture for our projects based on production needs.

Other versions of this project are available in these repositories, We can choose best fit architecture for our projects based on production needs:

For your simplest .net core projects, you can use my vertical-slice-api-template project template:

⭐ Support

If you like feel free to ⭐ this repository, It helps out :)

Thanks a bunch for supporting me!

Table of Contents

Features

Plan

This project is in progress, new features will be added over time.

Feature Architecture Pattern Status CI-CD

Technologies - Libraries

Setup

Dev Certificate

This application uses Https for hosting apis, to setup a valid certificate on your machine, you can create a Self-Signed Certificate, see more about enforce certificate here and here.

dotnet dev-certs https --clean
dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust
dotnet dev-certs https --clean
dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

dotnet dev-certs https --trust is only supported on macOS and Windows. You need to trust certs on Linux in the way that is supported by your distribution. It is likely that you need to trust the certificate in your browser(with this certificate we don't get an exception for https port because of not found certificate but browser shows us this certificate is not trusted).

Conventional Commit

In this app I use Conventional Commit and for enforcing its rule I use conventional-changelog/commitlint and typicode/husky with a pre-commit hook. For read more about its setup see commitlint docs and this article and this article.

Here I configured a husky hook for conventional commits:

  1. Install NPM:
npm init
  1. Install Husky:
npm install husky --save-dev
  1. Add prepare and install-dev-cert-bash commands for installing and activating husky hooks and dotnet tools in the package.json file:
npm pkg set scripts.prepare="husky && dotnet tool restore"

npm pkg set scripts.install-dev-cert-bash="curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v vs2019 -l ~/vsdbg"
{
  "scripts": {
    "prepare": "husky && dotnet tool restore",
    "install-dev-cert-bash": "curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v vs2019 -l ~/vsdbg"
  }
}
  1. Install CommitLint:
npm install --save-dev @commitlint/config-conventional @commitlint/cli
  1. Create the commitlint.config.js file with this content:
module.exports = { extends: '@commitlint/config-conventional']};
  1. Create the Husky folder:
mkdir .husky
  1. Link Husky and CommitLint:
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'
  1. Activate and installing all husky hooks with this command:
npm run prepare

# this command should run in git-bash on the windows or bash in the linux
npm run install-dev-cert-bash

Formatting

For formatting, I use mix of belav/csharpier and dotnet format.

Advanced (Options) Disabled all advanced option checkboxes. All other values were left default


Here I configured a husky hook for formatting:

1. Install NPM:

```bash
npm init
  1. Install Husky:
npm install husky --save-dev
  1. Install manifest file with dotnet new tool-manifest because it doesn't exist at first time and then install our required packages as dependency with dotnet tool install, that will add to dotnet-tools.json file in a .config directory:
dotnet new tool-manifest

dotnet tool install csharpier
  1. Add prepare command for installing and activating husky hooks and restoring our dotnet tools in the previous step to the package.json file:
npm pkg set scripts.prepare="husky && dotnet tool restore"
  1. Create the Husky folder:
mkdir .husky
  1. Link Husky and formatting tools:
npx husky add .husky/pre-commit "dotnet format --verbosity diagnostic"
npx husky add .husky/pre-commit "dotnet csharpier . && git add -A ."
  1. Activate and installing all husky hooks with this command:
npm run prepare

Analizers

For roslyn analizers I use serveral analyzers and config the in .editorconfig file:

The Domain And Bounded Context - Service Boundary

TODO

Application Architecture

The bellow architecture shows that there is one public API (API Gateway) which is accessible for the clients and this is done via HTTP request/response. The API gateway then routes the HTTP request to the corresponding microservice. The HTTP request is received by the microservice that hosts its own REST API. Each microservice is running within its own AppDomain and has directly access to its own dependencies such as databases, files, local transaction, etc. All these dependencies are only accessible for that microservice and not to the outside world. In fact microservices are decoupled from each other and are autonomous. This also means that the microservice does not rely on other parts in the system and can run independently of other services.

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.

In this architecture we use CQRS Pattern for separating read and write model beside of other CQRS Advantages. Here for now I don't use Event Sourcing for simplicity but I will use it in future for syncing read and write side with sending streams and using Projection Feature for some subscribers to syncing their data through sent streams and creating our Custom Read Models in subscribers side.

Here I have a write model that uses a postgres database for handling better Consistency and ACID Transaction guaranty. beside o this write side I use a read side model that uses MongoDB for better performance of our read side without any joins with suing some nested document in our document also better scalability with some good scaling features of MongoDB.

For syncing our read side and write side we have 2 options with using Event Driven Architecture (without using events streams in event sourcing):

All of this is optional in the application and it is possible to only use what that the service needs. Eg. if the service does not want to Use DDD because of business is very simple and it is mostly CRUD we can use Data Centric Architecture or If our application is not Task based instead of CQRS and separating read side and write side again we can just use a simple CRUD based application.

Here I used Outbox for Guaranteed Delivery and can be used as a landing zone for integration events before they are published to the message broker .

Outbox pattern ensures that a message was sent (e.g. to a queue) successfully at least once. With this pattern, instead of directly publishing a message to the queue, we put it in the temporary storage (e.g. database table) for preventing missing any message and some retry mechanism in any failure (At-least-once Delivery). For example When we save data as part of one transaction in our service, we also save messages (Integration Events) that we later want to process in another microservices as part of the same transaction. The list of messages to be processed is called a StoreMessage with Message Delivery Type Outbox that are part of our MessagePersistence service. This infrastructure also supports Inbox Message Delivery Type and Internal Message Delivery Type (Internal Processing).

Also we have a background service MessagePersistenceBackgroundService that periodically checks the our StoreMessages in the database and try to send the messages to the broker with using our MessagePersistenceService service. After it gets confirmation of publishing (e.g. ACK from the broker) it marks the message as processed to avoid resending. However, it is possible that we will not be able to mark the message as processed due to communication error, for example broker is unavailable. In this case our MessagePersistenceBackgroundService try to resend the messages that not processed and it is actually At-Least-Once delivery. We can be sure that message will be sent once, but can be sent multiple times too! That’s why another name for this approach is Once-Or-More delivery. We should remember this and try to design receivers of our messages as Idempotents, which means:

In Messaging this concepts translates into a message that has the same effect whether it is received once or multiple times. This means that a message can safely be resent without causing any problems even if the receiver receives duplicates of the same message.

For handling Idempotency and Exactly-once Delivery in receiver side, we could use Inbox Pattern.

This pattern is similar to Outbox Pattern. It’s used to handle incoming messages (e.g. from a queue) for unique processing of a single message only once (even with executing multiple time). Accordingly, we have a table in which we’re storing incoming messages. Contrary to outbox pattern, we first save the messages in the database, then we’re returning ACK to queue. If save succeeded, but we didn’t return ACK to queue, then delivery will be retried. That’s why we have at-least-once delivery again. After that, an inbox background process runs and will process the inbox messages that not processed yet. also we can prevent executing a message with specific MessgaeIdmultiple times. after executing our inbox message for example with calling our subscribed event handlers we send a ACK to the queue when they succeeded. (Inbox part of the system is in progress, I will cover this part soon as possible)

Also here I used RabbitMQ as my Message Broker for my async communication between the microservices with using eventually consistency mechanism, for now I used MassTransit tools for doing broker communications. beside of this eventually consistency we have a synchronous call with using REST (in future I will use gRpc) for our immediate consistency needs.

We use a Api Gateway and here I used YARP that is microsoft reverse proxy (we could use envoy, traefik, Ocelot, ...), in front of our services, we could also have multiple Api Gateway for reaching BFF pattern. for example one Gateway for mobile apps, One Gateway for web apps and etc. With using api Gateway our internal microservices are transparent and user can not access them directly and all requests will serve through this Gateway. Also we could use gateway for load balancing, authentication and authorization, caching ,...

Application Structure

In this project I used vertical slice architecture or Restructuring to a Vertical Slice Architecture also I used feature folder structure in this project.

Also here I used CQRS for decompose my features to very small parts that makes our application:

With using CQRS, our code will be more aligned with SOLID principles, especially with:

Here instead of some Technical Splitting for example a folder or layer for our services, controllers and data models which increase dependencies between our technical splitting and also jump between layers or folders, We cut each business functionality into some vertical slices, and inner each of these slices we have Technical Folders Structure specific to that feature (command, handlers, infrastructure, repository, controllers, data models, ...).

Usually, when we work on a given functionality we need some technical things for example:

Now we could all of these things beside each other and it decrease jumping and dependencies between some layers or folders.

Keeping such a split works great with CQRS. It segregates our operations and slices the application code vertically instead of horizontally. 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.

High Level Structure

TODO

Vertical Slice Flow

TODO

Prerequisites

  1. This application uses Https for hosting apis, to setup a valid certificate on your machine, you can create a Self-Signed Certificate, see more about enforce certificate here.
  2. Install git - https://git-scm.com/downloads.
  3. Install .NET Core 7.0 - https://dotnet.microsoft.com/download/dotnet/7.0.
  4. Install Visual Studio, Rider or VSCode.
  5. Install docker - https://docs.docker.com/docker-for-windows/install/.
  6. Make sure that you have ~10GB disk space.
  7. Clone Project https://github.com/mehdihadeli/food-delivery-microservices-sample, make sure that's compiling
  8. Run the docker-compose.infrastructure.yaml file, for running prerequisites infrastructures with docker-compose -f ./deployments/docker-compose/docker-compose.infrastructure.yaml up -d command.
  9. Open food-delivery-microservices.sln solution.

How to Run

For Running this application we could run our microservices one by one in our Dev Environment, for me, it's Rider, Or we could run it with using Docker-Compose or we could use Kubernetes.

For testing apis I used REST Client plugin of VSCode its related file scenarios are available in _httpclients folder. also after running api you have access to swagger open api for all microservices in /swagger route path.

In this application I use a fake email sender with name of ethereal as a SMTP provider for sending email. after sending email by the application you can see the list of sent emails in ethereal messages panel. My temp username and password is available inner the all of appsettings file.

Using PM2

For ruining all microservices and control on their running mode we could use PM2 tools. for installing pm2 on our system globally we should use this command:

npm install pm2 -g

After installing pm2 on our machine, we could run all of our microservices with running bellow command in root of the application with using pm2.yaml file.

pm2 start pm2.yaml

Some PM2 useful commands:

pm2 -h

pm2 list

pm2 logs

pm2 monit

pm2 info pm2.yaml

pm2 stop pm2.yaml

pm2 restart pm2.yaml

pm2 delete pm2.yaml

Using Docker-Compose

dotnet dev-certs https --clean
dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p $CREDENTIAL_PLACEHOLDER$
dotnet dev-certs https --trust

This local certificate will mapped to our containers in docker-compose file with setting ~/.aspnet/https:/https:ro volume mount

Some useful docker commands:

// start dockers
docker-compose -f .\docker-compose.yaml up

// build without caching
docker-compose -f .\docker-compose.yaml build --no-cache

// to stop running dockers
docker-compose kill

// to clean stopped dockers
docker-compose down -v

// showing running dockers
docker ps

// to show all dockers (also stopped)
docker ps -a

Using Tye

We could run our microservices with new microsoft tools with name of Project Tye.

Project Tye is an experimental developer tool that makes developing, testing, and deploying microservices and distributed applications easier.

For installing Tye globally on our machine we should use this command:

dotnet tool install -g Microsoft.Tye --version "0.11.0-alpha.22111.1"

OR if you already have Tye installed and want to update:

dotnet tool update -g Microsoft.Tye

After installing tye, we could run our microservices with following command in the root of our project:

tye run

One of key feature from tye run is a dashboard to view the state of your application. Navigate to http://localhost:8000 to see the dashboard running.

Also We could run some docker images with Tye and Tye makes the process of deploying your application to Kubernetes very simple with minimal knowledge or configuration required.

Using Kubernetes

For using kubernetes we can use multiple approach with different tools like plain kubernetes, kustomize and helm and here I will use show use of all of them.

Plain Kubernetes

Prerequisites

Here I uses plain kubernetes command and resources for applying kubernetes manifest to the cluster. If you're a Docker/Compose user new to Kubernetes, you might have noticed that you can’t substitutes and replace the environment variables in your kubernetes manifest files (exception is substitutes and replace environment variables in env attribute, with using environment dependent variable). we often have some personal .env files for projects that we use to store credentials and configurations.

For substitutes and replace environment variables in our kubernetes manifest or resource files we can use envsubst tools, and we can even pipe it into other commands like Kubernetes kubectl, read more in this and this articles.

So here we should first install this tools on our OS with this guid.

Now for running manifest files, firstly we should load our environment variables inner .env file in our current shell session by using source .env command (after closing our shell environments will destroy).

Make sure to use export, otherwise our variables are considered shell variables and might not be accessible to envsubst

Here is a example of .env file:

export ASPNETCORE_ENVIRONMENT=docker
export REGISTRY=ghcr.io

After loading environment variables to the our shell session we can run manifests with using envsubst and pipe envsubst output to kubectl command as a input like this example:

# pipe a deployment "deploy.yml" into kubectl apply
envsubst < deploy.yml | kubectl apply -f -

Also it is also possible to write our substitution to a new file (envsubst < input.tmpl > output.text):

envsubst < deploy.yml > compiled_deploy.yaml

I've create a shell script kubectl, we can call this script just like we would kubectl. This script sources any .env file in the manifests directory , If we're running ./kubectl apply or ./kubectl delete with kubectl script, it calls envsubst to swap out your environment variables, then it passes the code on to the real kubectl.

#!/bin/bash
ENV_FILE=.env

source $ENV_FILE

if [[ "$1" == "apply" ]] || [[ "$1" == "delete" ]]; then
    envsubst < $3 | kubectl $1 $2 -
else
    kubectl "$@"
fi
Installation
./kubectl apply -f ./deployments/k8s/kubernetes/infrastructure.yaml

Contribution

The application is in development status. You are feel free to submit pull request or create the issue.

Project References

License

The project is under MIT license.

Star History

Star History Chart