I have decided create a white label Web API .NET Core solution and share it with you, and I would like to hear your comments about the code and especially your comments about the architecture chosen.
src - Main projects (the code of the project).
tests - All the test projects will be here.
docs - Documentation stuff (markdown files, help files and any other documentation etc.)
lib - Things that can NEVER exist in a nuget package
artifacts - Build outputs go here. Doing a build.cmd/build.sh generates artifacts here (nupkgs, dlls, pdbs, etc.)
packages - NuGet packages
build - Build customizations (custom msbuild files/psake/fake/albacore/etc) scripts
build.cmd - Bootstrap the build for windows
build.sh - Bootstrap the build for *nix
appsettings.json - ASP.NET Core configuration file
Based on David Fowler post: https://gist.github.com/davidfowl/ed7564297c61fe9ab814
This project is splitted in diferent layers using the Clean Architecture methodology described here (https://docs.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures). Here you can find an explanation of each layer:
In this layer we'll have all the business logic. According the Clean Architecture definition, this layer needs to be isolated from the others layers, the core must not know anything about any other dependency (Data, View, etc.).
In this project we'll add the classes/utilities which are common to all infrastructure projects.
The data layer, in this project I have used EF Code First and it's splitted in the following folders:
I don't like to use any DI framework like Autofac, Ninject, etc. that's why I have created a project in my solution to do it manually.
It's not a big thing and in this way I avoid use extra dependencies in my projects. If you are going to work with a very big project perhaps you should rething this solution and chose one of the DI frameworks that you can find in the market.
This project is optional, but I like to create a separated project to execute my migrations to avoid add extra dependencies to other projects.
These 3 nuget packages necessary to be able to execute EF are only added in this project, that's why we would need to add this project as startup project to be able to execute any migration.
To be able to execute the EF commands you will need to follow these steps:
1. Select project Infrastructure.Migrations as startup project in solution explorer.
2. Open console packet manager (PM) and select Website.Infrastructure.Data as default project.
3. Add-Migration <migration_name>
4. Update-Database
This is the main project, this project will contain the controllers and the swagger interface and it will be organized as follow:
Here you will add all the unit tests of your project. I have splitted the project in 3 folders:
What I have to tried to explain here it's a architecture to start to build a new Web API, but after that you will need to add hundreds or maybe thousand of lines of code. Remember you will be an author and you will have other readers who will read your code, so, you have to write a good code for your readers following the best pratices. Here you can find some of these practices: https://oscarchelo.blogspot.com/2020/04/hi-there-these-days-i-have-been-reading.html
Here you can find the code repository of this project https://github.com/racsus/WhiteLabelAPI
What would you change? any feedback?
Folder structure
The following structure is defined here:
src - Main projects (the code of the project).
tests - All the test projects will be here.
docs - Documentation stuff (markdown files, help files and any other documentation etc.)
lib - Things that can NEVER exist in a nuget package
artifacts - Build outputs go here. Doing a build.cmd/build.sh generates artifacts here (nupkgs, dlls, pdbs, etc.)
packages - NuGet packages
build - Build customizations (custom msbuild files/psake/fake/albacore/etc) scripts
build.cmd - Bootstrap the build for windows
build.sh - Bootstrap the build for *nix
appsettings.json - ASP.NET Core configuration file
Based on David Fowler post: https://gist.github.com/davidfowl/ed7564297c61fe9ab814
Project sctructure
This project is splitted in diferent layers using the Clean Architecture methodology described here (https://docs.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures). Here you can find an explanation of each layer:
Core project
In this layer we'll have all the business logic. According the Clean Architecture definition, this layer needs to be isolated from the others layers, the core must not know anything about any other dependency (Data, View, etc.).
This layer contains the following folders:
- Constants: Contains different classes to organize the different constants we use in the project.
- DTOs: Contains all the DTO classes organized by the different namespaces of the project.
- Entities: Contains all the Entity classes organized by namespace.
- Enums: Contains all the Enum classes organized by namespace.
- Exceptions: Contains the following custom HTTP exceptions to be able to manage the exception management (BadRequest, NotFound, etc.)
- Extensions: Contains any extension class organized by namespace.
- Factories: Contains any factory class organized by namespace.
- Interfaces: Contiains all the Interface classes from Core and any Infrastructure layer (to be able to see infrastructure layers without adding any dependency in the Core. SOLID DIP principle)
- Services: Contains all the application logic and it will be organized by namespace.
- Validators: Contains the logic to validate DTOs. It's organized by namespace. In this project I have used FluentValidation. Read this post https://oscarchelo.blogspot.com/2020/05/net-core-webapi-validation-with.html to check how I have done it.
Infrastructure project
In this project we'll add the classes/utilities which are common to all infrastructure projects.
Infrastructure.Data project
The data layer, in this project I have used EF Code First and it's splitted in the following folders:
- DbMapping: Instead of add all the database mapping in the context class I have decided to organize all the mappings in different classes organized by namespaces.
- Factories: Factory classes that are used exclusively by this project.
- Interfaces: Interface classes that are used exclusively by this project.
- Migrations: The standard folder where are stored all the executed migrations. https://docs.microsoft.com/en-us/ef/ef6/modeling/code-first/migrations/
- Repositories: The repository classes will be here. These classes will be implemented by the interfaces stored in Core/Interfaces.
Infrastructure.DependencyBuilder project
I don't like to use any DI framework like Autofac, Ninject, etc. that's why I have created a project in my solution to do it manually.
It's not a big thing and in this way I avoid use extra dependencies in my projects. If you are going to work with a very big project perhaps you should rething this solution and chose one of the DI frameworks that you can find in the market.
Infrastructure.Migrations project
This project is optional, but I like to create a separated project to execute my migrations to avoid add extra dependencies to other projects.
These 3 nuget packages necessary to be able to execute EF are only added in this project, that's why we would need to add this project as startup project to be able to execute any migration.
To be able to execute the EF commands you will need to follow these steps:
1. Select project Infrastructure.Migrations as startup project in solution explorer.
2. Open console packet manager (PM) and select Website.Infrastructure.Data as default project.
3. Add-Migration <migration_name>
4. Update-Database
WhileLabelAPI.WebAPI project
This is the main project, this project will contain the controllers and the swagger interface and it will be organized as follow:
- Authentication: Necessary classes to implement the basic authentication. This project is configured by basic auth, but remember this is the worse authentication, so, depending of the use of your project it is highly recommended to change this authentication method.
- AutoMapper: This folder contains the 2 classes necessary for automapper (DTO to Entity)
- Controllers: The controllers of the Web API. Please follow the good practises when you write any end point in your controllers. https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
- Extensions: Any extension class necessary in this project.
- Midlewares: Any custom midleware that you are going to use in the startup class. In my case I have added a custom midleware to manage the custom exceptions.
- connectonstrings.json: I used to create a separated file to store the connection string, but you can store it in the appsettings.json file.
- appsettings.json: Here you are going to store all your project configuration.
- apisecuritysettings.json: I used to create a separated file for the Basic Authentication configuration, but you can store all this data in the appsettings.json file as well.
WhiteLabelAPI.Test
Here you will add all the unit tests of your project. I have splitted the project in 3 folders:- Factories: Factory class per namespace.
- Mocks: Mock class per namespace.
- Services: Here you will add the classes for testing your code.
Good Practices
What I have to tried to explain here it's a architecture to start to build a new Web API, but after that you will need to add hundreds or maybe thousand of lines of code. Remember you will be an author and you will have other readers who will read your code, so, you have to write a good code for your readers following the best pratices. Here you can find some of these practices: https://oscarchelo.blogspot.com/2020/04/hi-there-these-days-i-have-been-reading.html
The code
Here you can find the code repository of this project https://github.com/racsus/WhiteLabelAPI
What would you change? any feedback?
Comentarios
Publicar un comentario