Discover how the , a clean architecture pattern also known as Ports and Adapters, can help! Did you ever face problems when comes the time to upgrade the stack of your software? Are you able to distinguish your functional tests from your integration ones? Migrating your legacy means rewriting everything from scratch? Hexagonal Architecture Business logic overboard! In a previous experience, my team had to port an old application on a brand-new stack. The software was moving from an EAR/SQL app to a self-contained JAR using NoSQL. By studying it, we quickly realized that we had to redo the entire infrastructure. In fact, the only thing that didn’t have to change was the business logic. So, it makes sense to reuse it, right? After a deeper look, the maven module named model was POJOs with only getters and setters, totally … Although there is also service module, the business logic is shared across all the layers. It was drowned in a lot of technical code such as DAOs creation, Serialization, etc. There were no ways to extract the business logic! Some parts of it were relying on the technical behavior of the old framework we tried to remove. And why? Because there was no clean separation between the business logic and the technical code. anemic Separation of concerns: isolating the business logic The Hexagonal Architecture created by ensures the re-usability of the business logic by making it technical-agnostic. So, changing the stack will have no impact on the domain code. Alistair Cockburn One key concept of this architecture is to put named the Domain. Let’s update the previous schema: all the business logic into a single place Important constraint: ; this is the only way to ensure that the business logic is decoupled from the technical layers. How do we achieve that on the previous schema? The domain clearly depends on the persistence layer! Well, by using a pattern you may know: the inversion of control. By calling the domain the Hexagon, it will look like this: the domain depends on nothing but itself The inversion of control was pretty magic, let’s see later how it works. Now you got an overview of what is the Hexagonal Architecture: Only two worlds, inside and outside the Hexagon. , meaning all your technical code. Inside: all the business logic Outside: the infrastructure — . It ensures the isolation of the business domain from the technical part. The dependencies always go from outside toward the inside of the Hexagon One corollary of this is . And not only regarding your own layers: . That includes external annotations like Jackson or JPA. the Hexagon depends on nothing but itself It must not depend on any technical framework No frameworks allowed in the domain (almost) Let me explain you a bit more the last point, which is a really important one. In another experience, my team had to port an application from the “classic” Spring framework to Spring Boot. The main (painful) problem we had: leveraging too much on the Spring Integration Tests to validate our functionalities. Furthermore, those functionalities were also too coupled with Spring. At the first try of our Spring Boot migration, all functional tests were failing. We were not able to determine if the business logic was broken somewhere or if the reason was purely technical. We eventually figured out that it was an integration problem at test level. So we fixed all the tests one by one by crossing our fingers… Hoping the domain was still correct. No framework used in the Hexagon means . It will as well since you no longer mix it with integration issues. And at the end, you’ll do thanks to this constraint of the Hexagonal Architecture. This way the functional tests will directly interact with the Hexagon and only with it. the business domain can be reused regardless the change of the technical stack increase the testability of your domain real functional tests NOTE: In Maven, you can ensure this constraint using the . enforcer plugin The Hexagonal Architecture Inversion of Control Remember the inversion of control? To ensure the isolation of the Hexagon, the dependencies on downstream layers have been inverted. The trick is in fact pretty simple as you can see: The outside of the Hexagon (the infrastructure) is divided in two virtual parts, the left side and the right side. On the left, you got everything that will query the domain (the controller, the REST layer, etc.). And on the right, everything that will provide some information/services to the domain (persistence layer, third party services, etc.). Protecting the domain with an anti-corruption layer To let the outside to interact with the domain, the Hexagon provides divided in two categories: business interfaces The gathers all the interfaces for everything that needs to query the domain. Those interfaces are implemented by the Hexagon. API The (Service Provider Interface) gathers all the interfaces required by the domain to retrieve information from third parties. Those interfaces are defined in the Hexagon and implemented by the right side of the infrastructure. We will see that on some circumstances, the Hexagon can also implement the SPI. SPI There are two important facts here: The API and the SPI only manipulate domain objects of the Hexagon. It indeed ensures the isolation. The API and the SPI are parts of the Hexagon. In a layered architecture, . In the Hexagonal Architecture, the domain only handles domain objects. Consequently, the persistence is in charge to translate the domain objects into any “DAOs” to be persisted. This is what we call an adaptation. the Business Object or the service usually creates the DAOs In a layered architecture, . In the Hexagonal Architecture, the domain only handles domain objects. Consequently, the persistence is in charge to translate the domain objects into any “DAOs” to be persisted. This is what we call an adaptation. the Business Object or the service usually creates the DAOs The modularity strength of the Hexagonal Architecture As mentioned above, the architecture is another name of the Hexagonal Architecture. It comes from . Because everything is decoupled, you can have a REST and JMS layers in front of your domain at the same time without having any impacts on it. Ports and Adapters the power of the modularity of this architecture On the SPI side, you can change from a MongoDB driver implementation to Cassandra if needed. Since the SPI won’t change because you change the persistence module, the rest of your software won’t be impacted. The API and the SPI are the Ports and the infrastructure modules using or implementing them are the adapters. How to implement the Hexagonal Architecture? One more rule here: . This will bring you a lot of advantages: always start with the inside of the Hexagon instead of the technical details. Because only the feature brings value to your company. A developer working on another business domain is able to put in place a Spring Controller. But the double declining balance method will sound like Wookiee for him unless he worked for an accountancy company. Focus on the feature Sometimes it’s really hard to know which technical implementation you really need at the beginning. Consequently, delaying this choice helps you to focus on what brings the primary values to your company — the feature. Furthermore, after the implementation of the business logic, some new elements can help you to make the best choice regarding your infrastructure. You can discover that the domain is more relational than expected, so SQL is a good choice for your database. Delay choices on technical implementation. One corollary is it ensures the . Since you should never write code without tests, it means that the . Furthermore, we got here real functional tests focusing on the business only. Hexagon is a stand-alone Hexagon is self-tested A Test-Driven implementation With the Hexagonal Architecture, you put your functional tests in your domain. Those tests will call directly the domain API while avoiding any disturbance from the technical part. In a way you are creating an adapter simulating the Controller to test the features of the domain. My advice is writing your functional scenario first using the to describe your feature. Starting with the functional tests of the Domain Behavior-Driven Development The first step of the . And write the API interface which will be the entry point of your feature. Then implement your tests with TDD and finally implement your business logic. While writing it, you might need to retrieve some data from the database for example, so create an SPI. Since the right side is not yet implemented, create a stubbed implementation of this SPI inside your Hexagon. That can be achieved using an in-memory database implemented with a Map. “double-loop” will produce your functional test using ATDD You can choose to keep the Stubs in the test scope of your application. But you can as well temporarily ship it if needed. For example, once we made the first feature on the Hexagon, we stubbed an external service and the database. Because our client needed us to provide an interface contract, we secondly exported the domain through a REST controller. So we shipped a first version with stubbed data on the right side of the infrastructure. This way, the client was able to see the structure of our data and the expected behavior of the feature. It was much more reliable than creating by hand some JSON samples of our requests and responses because it actually deals with real business constraints. Finishing with the adapters The next step is usually opening the left side first. This way you can put in place some integration tests on the feature. At this time you can provide and ensure an interface contract with your clients. some live documentation Finally, open on the right by implementing the SPI of your feature by taking advantage of the integration tests. I strongly recommend your tests to be stand-alone to avoid any instability during build time. You should always mock your third parties using something like for external services or to simulate a MongoDB. Wiremock Fongo Loop the same way for your other features. For more information, an is available on GitLab. Hexagonal Architecture Testing Strategy Hexagonal Architecture in a nutshell So, now we have seen what is Hexagonal Architecture! There is a real benefit in . It ensures your business domain is regarding the continuous evolution of the technology. decoupling the business logic from the technical code durable and robust The Hexagonal Architecture offers you a real means to achieve this by: Putting all the business logic in a .The domain is regarding the technical part because but itself. That’s why single place isolated and agnostic it depends on nothing the dependencies always go from outside to the inside of the Hexagon. The Hexagon module. Thus, It of your domain by writing which don’t have to deal with technical issues. is a stand-alone increases the testability real functional tests This architecture offers a . It helps you to write as many adapters as needed with a low impact on the rest of the software. And since the domain is agnostic from the stack . powerful modularity , the stack can be changed without any impact on the business By , you ensure to bring value to your customer by . This way you can to make the best choice at the right time. always starting with the domain focusing on the feature development delay choices on technical implementation Some feedbacks Hexagonal Architecture is not suitable for all situations. Like Domain-Driven Design, this is really applicable if you got a real business domain. For an application which transform a data to another format, that’s might be overkill. To finish on this, always be pragmatic when you adopt a new technology. As stated before, , but exceptionally you can. For example, in our case the Hexagon had three exceptions: Apache Commons Lang3 (StringUtils), SLF4J and the JSR305 of Findbugs. Because we didn’t want to create the wheel since those frameworks had very low impacts on the domain. One good side effect of the Hexagonal Architecture, is that you keep challenging yourself before integrating a new framework. By using this architecture, we reduced the number of dependencies from fifty to only three or four for the domain. And this is very good from a security perspective. the Hexagon must not depend on any technical framework Further readings Want to go further? Checkout those And if you to see some code, you can now find on GitLab a Kotlin/Spring Boot . Domain-Driven Design and Hexagonal Architecture tips&tricks series Hexagonal Application

Apache

Winner of Noonies 2020 for the award Software Testing Writer of the Year.

2020 - Software Testing Writer of the Year

Read My Stories

Too Long; Didn't Read

In your car, at home, or at work — Bosch technology shapes many areas of life.

Hexagonal Architecture: the practical guide for a clean architecture

Too Long; Didn't Read

Company Mentioned

Julien Topçu

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Hexagonal Architecture: the practical guide for a clean architecture

Too Long; Didn't Read

Company Mentioned

Julien Topçu

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES