https://github.com/rbiedrawa/spring-hexagonal-architecture-poc
Hexagonal architecture implementation in Java/Spring world.
https://github.com/rbiedrawa/spring-hexagonal-architecture-poc
adminer architectural-patterns architecture clean-architecture docker-compose gradle graphql h2-database hexagonal-architecture java junit5 ports-and-adapters postgresql spring-boot spring-data-jpa swagger-ui
Last synced: 7 months ago
JSON representation
Hexagonal architecture implementation in Java/Spring world.
- Host: GitHub
- URL: https://github.com/rbiedrawa/spring-hexagonal-architecture-poc
- Owner: rbiedrawa
- Created: 2021-04-01T17:30:39.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-01-31T02:05:51.000Z (over 3 years ago)
- Last Synced: 2025-01-26T18:17:20.660Z (8 months ago)
- Topics: adminer, architectural-patterns, architecture, clean-architecture, docker-compose, gradle, graphql, h2-database, hexagonal-architecture, java, junit5, ports-and-adapters, postgresql, spring-boot, spring-data-jpa, swagger-ui
- Language: Java
- Homepage:
- Size: 1.1 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Hexagonal Architecture / Ports & Adapters Pattern (PoC)
This repository demonstrates how to implement Hexagonal architecture in Java/Spring Boot application.
## Table of Content
- [Ports & Adapters Pattern](#ports--adapters-pattern)
- [Order Service](#order-service)
* [Application Diagram](#application-diagram)
- [Project package structure](#project-package-structure)
- [Getting Started](#getting-started)
* [Prerequisites](#prerequisites)
* [Installation](#installation)
- [Important Endpoints](#important-endpoints)
- [References](#references)
- [License](#license)
## Ports & Adapters Pattern
> Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.
>
> As events arrive from the outside world at a port, a technology-specific adapter converts it into a usable procedure call or message and passes it to the application. The application is blissfully ignorant of the nature of the input device. When the application has something to send out, it sends it out through a port to an adapter, which creates the appropriate signals needed by the receiving technology (human or automated). The application has a semantically sound interaction with the adapters on all sides of it, without actually knowing the nature of the things on the other side of the adapters.
>
> -- [Alistair Cockburn][1]
[1]: https://alistair.cockburn.us/hexagonal-architecture/
## Order Service
Order Service is a simple microservice that allows customers to manage orders via REST or GraphqlQL API.
### Application Diagram
## Project package structure
```shell
+-- api: # Application Provider Interface - contains primary/driving adapters.
| +-- graphql # GraphQL primary adapter classes.
| +-- rest # Rest primary adapter classes.
+-- business # core of our application. Contains pure domain business logic, doesn't have any external dependencies. All communications goes through ports.
| +-- common # shared configuration.
| +-- customers # customers feature.
| +-- notifications # notifications feature.
| +-- orders # orders feature.
+-- config # common Spring configuration.
+-- spi # Service Provider Interface - contains secondary/driven adapters.
| +-- grpc # fake gRPC client adapter.
| +-- customers # customers feature.
| +-- postgres # PostgreSQL adapter.
| +-- config # postgres configuration classes.
| +-- orders # orders feature.
| +-- sendgrid # fake Sendgrid adapter.
| +-- twilio # fake Twilio adapter.
```
*** *One of many ways to structure your packages, always discuss and agree inside Your team;)*
## Getting Started
### Prerequisites
* Java 11
* PostgreSQL
* Docker
### Installation
* **H2:**
```shell
./gradlew bootRun
```
* **PostgreSQL:**
```shell
# Start docker compose with PostgresSQL and Adminer
docker-compose -f ./docker/docker-compose.yml up -d
# Start order service with 'docker' profile
./gradlew bootRun --args='--spring.profiles.active=docker'
```
## Important Endpoints
| Name | Endpoint |
| -------------:|:--------:|
| `Order Service - GraphiQL` | http://localhost:8080/graphiql |
| `Order Service - Swagger UI` | http://localhost:8080/swagger-ui.html |
| `Order Service - H2 console` | http://localhost:8080/h2-console |
| `Adminer` | http://localhost:7775/ |
## References
* [Alistair Cockburn - Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture/)
* [Netflix Blog - Ready for changes with Hexagonal Architecture](https://netflixtechblog.com/ready-for-changes-with-hexagonal-architecture-b315ec967749)
* [More Testable Code with the Hexagonal Architecture](https://www.youtube.com/watch?v=ujb_O6myknY)
* [How to implement equals and hashCode using the JPA entity identifier (Primary Key)](https://vladmihalcea.com/how-to-implement-equals-and-hashcode-using-the-jpa-entity-identifier/)
* [SPI - Service Provider Interface](https://en.wikipedia.org/wiki/Service_provider_interface)
## License
Distributed under the MIT License. See `LICENSE` for more information.