Onion Architecture Boilerplate
DESCRIPTION
This repository is a real life example of Onion Architecture with use of Node.js / Express
and Typescript
Diagram available here
This diagram has some copyrights, if you want to use it on larger scale, feel free to contact me.
Technologies used
Typescript
(v3.7.5
)Inversify.js
TypeOrm
Express.js
Mocha / Chai
for testing
Structure
-
core (
Application Core
)Contains application core related layers like application services, domain and domain services
-
dependency (
Dependency injection layer
)Contains definition for Container and whole project dependencies
-
infrastructure
Contains definition of data sources in case of this boilerplate - database
-
ui
Contains definition of presentation layer like controller, express setup etc
What is supported?
- Multiple environment setup
- DB Agnostic setup, supports multiple datasource
- Infrastructure -> Domain Mapping -> UI Mapping
- Migrations, Fixtures, Seeds
- Multiple API versions support ( REST implementation )
- Global Error Handling
- Test Parallelization
Reference
Inspired by following articles:
https://www.slideshare.net/matthidinger/onion-architecture
PREREQUISITIES
-
Yarn
-
NVM
( tested onv10.13.0+
)wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash`
-
PostgreSQL
( tested onv11+
)
SETUP
- Database
- Look at the
ormconfig.sample.js
file. It's a sample setup of database connection, you can provide your own data for database if needed. From app perspective you have to manually create database for development ( in sample with nameonion_dev
) and for testingonion_test
. - Migrations will autorun on application start
- Look at the
- Env Variables
-
.env.example
contains example env config - for local / dev use you can use same values as provided in sample -
for production use generate token with following command
node -e "console.log(require('crypto').randomBytes(256).toString('base64'));"
-
HOW TO RUN LOCALLY
- Follow
SETUP
section first and installPREREQUISITIES
Yarn install
- installing dependenciesYarn dev
- run app with watch and rebuild
WORKING WITH DATABASE
- To prepare database with latest migrations run
yarn db:reload
, it also removes all data from db and recreates it. Useful when playing with seed data. - To seed database run
yarn db:seed
- To generate migration based on changes in entity object run
yarn db:generate <my_migration_name>
SWAGGER
When there is a swagger host provided in .env
file then you can navigate to http://localhost:3000/api-docs/
Update swagger.json
file located at ui > config
every time you apply changes to api.
TESTING
- Prepare tests database first (
SETUP SECTION
) - Run
yarn test
- should run mocha tests in parallel
Mutational Testing
- Read guide here to setup global dependencies
- Run
yarn test:mutate
command
APPLIED CONCEPTS
There are some universal concepts in programming ( designed patterns ) which are common for general engineering but it's not always obvious how to use environment specific concepts. In this boilerplate I'm going to show how to handle that.
Request Object
Request object defines parameters / input to specific module input ( domain / infrastructure ), and holds required data which cannot be changed on the fly.
Unit Of Work
Unit Of Work is simply speaking - a wrapper. It wraps repositories and performs required operations usually in transaction. It solves issue related to circular repository dependency in ioc, or nested repository dependency on each other. With unit of work specific repository methods don't have any reference to external repositories which makes them more atomic.
Mapper
Simple concept where one module data structure is translated to another module
Infrastructure -> Domain Mapper
This mapper is prepared for mapping data source format data into domain format. Simplest example would be that, in
database we store first_name
and last_name
in separate columns, but in domain we need to have field name
which
is combined value of previously mentioned columns. In that case we define domain model with required fields and new name
field.
In Mapper we can perform merging of those 2 values. Thanks to that we can have separation
between definition of Entity and Domain, and also we have just plain values in domain object instance without
any overhead related to persistence data etc, which for sure would be stored by Entity object instance. We can also calculate
simple values in mappers etc.
Domain -> UI Mapper
This mapper is for preparing Domain data format into specific ui data format. Sometimes we may need to perform
some logic in domain services on domain object format but we would like to make a response in totally different format.
For example we may fetch data as array from database, perform operations in services on array but on ui, we would like to
group array elements into map structure in different format. In repository, we mapped User
domain object into User
ui object
where UI
object do not contain password field and contains only required fields for authentication purposes.
Migrations
Used for managing database changes. In repository, we generate migrations based on entity changes. So we can
add new column on entity and then just use one command to generate required migration. It's recommended to split database related
changes into multiple migrations instead creating one migration for all related feature changes. For example it's better to
have separate migration for creating x
table and separate migration for adding / updating table columns definition to
table y
.
Seeds
Used for local development or testing - it's just data for specific use cases which can be also used for dev environment where QA's can test specific endpoints or screens. It's also useful as start data for local development especially when you are working as a full stack.
Tests parallelization
Every test runs on it's separate database, and we can spawn multiple tests at the same time, and run in transaction specific test cases, thanks to which we don't have to clear db after running every test.
Mutational testing
Mutational testing is integrated with Mocha
test runner and shows how many mutations are still available in
system, and where we should apply additional test coverage.
Integration testing
We are testing whole layers data flow - from UI
layer up to Infrastructure
. We are testing
not only responses but also saved data in database and authentication context.
STILL TODO
- Prepare FP version of architecture - separate repo
- Introduce Graphql and integration with inversify-graphQL - separate repo
KNOWN ISSUES
-
To authenticate provide token this way as swagger 2.0 do not support bearer strategy
https://github.com/OAI/OpenAPI-Specification/issues/583#issuecomment-267554000
-
http context is empty in controllers, looks like http context is incorrectly injected into controller, everything is fine though in middlewares - applied workaround take a look at
getCurrentUser
helper