The purpose of this template is to avoid repeating, over and over again, the same basic packages structure, gradle and configurations. Note: this is just a skeleton with a silly example. Is good to start a project with it, but if you want to see a production ready and fully tested project with a lot of examples, please visit my friend Albert Llousas Team Management repository.
The current packages structure has been popularized by Vaughn Vernon, the author of Implementing Domain-Driven Design
and Domain-Driven Design Distilled and you can see an example in
his Github Repository.
The structure is a mix of Alistair Cockburn's Ports & Adapters Pattern and DDD concepts. In fact, if you know the original Hexagonal Architecture article,
you will see that the packages structure is not familiar to you, but you may recognize the concepts embedded (Ports & Adapters).
In the src directory you will see the following packages:
.
├── application
├── domain
└── infrastructure
The application package is the place where we will put all the Application Services (aka Use Cases) classes.
The domain package will host all the pure Domain classes, such as Aggregates, Value Objects, Entities, Domain Events, Repositories etc. Usually this package also hosts PORTS (CustomerRepository is an example of a Port).
The infrastructure package instead, is the place were we put all the infrastructure concerns, such as framework, configurations and concrete implementations. You will see an adapters package
that contains Inbound and Outbound Adapters, that are concrete implementations of Ports, defined in the domain package.
The silly example provided is, of course, tested (using Outside-In TDD).
This project is following the typical Testing Pyramid, but adapted to (Micro)services.
You will see that there are three different types of tests and each one of them has a concrete scope.
-
End-To-End Tests have been excluded on purpose, since their scope is broader than a single service.
-
Component Tests: this is a kind of test that have been popularized in Microservices Patterns (See Service Component Tests), but at the end is just another name for the well known Acceptance Tests. The scope is to test the service itself, in isolation, "mocking" external dependencies such as database (using TestContainers for instance) and external services (using Wiremock for instance).
-
Integration Tests: this kind of tests are run in isolation, there is no real call to an external service or a real database. Here we include repositories, clients, controllers, consumers, producers tests etc. We can also include Contract Tests (extending Controller tests, for instance, to check contract with Consumers using some kind of tool like Pact.io).
-
Unit Tests: and finally we "unit test" what's the most important part of the service: the Domain. Here we include all the tests for Aggregates, Value Objects, Entities, Domain Events, Application Services (aka Use Cases), Domain Services etc.
For a full overview, have a look at my article on Medium.
First you will need to install Copier on your local machine.
This is an open-source tool to copy directories and files from one place to another also using templates.
To install it, run in your console: pip install copier
Then to copy this template, run the following command:
copier https://github.com/Hyunk3l/hexagonal-architecture-kotlin-template.git put-your-directory-here
you will be asked about a few configurations (name of the package, project etc.).
Once done, open your put-your-directory-here.
As you already know, there are three type of tests. You can run them separately or together:
- Component:
./gradlew componentTest - Integration:
./gradlew integrationTest - Unit:
./gradlew unitTest
To run them together: ./gradlew test
If you really want to run your service locally (why would you? It's fully covered with multiple layers of tests), run the following commands:
- Run containers
docker-compose up - Run the service
./gradlew bootRun
- Domain is anemic: just a silly example :)
- Not publishing Domain Events: maybe in the future I will.
- In memory repository has not been tested (on purpose). Maybe in the future I'll add a real db repository implementation.