Hello everyone i recenlty written a TODO System with Hexagonal Architecture written in Go, with test and uses cases examples, docker ready, heroku ready, basic CI integration and you can use it how template for your projects.
I appreciate feedback!
✔️ A TODO System with hexagonal architecture / clean architecture what you can use how template for your projects
✔️ Includes a simple CI.yml that you can use to get started with continuous integration in Github Actions
✔️ DB and Tests Implemented with CockRoachDB but you can run with another, for example MySQL
✔️ It have use cases and test examples for that use cases
✔️ Unit tests models and integration test models
✔️ API REST with Echo MicroFramework
✔️ Simple error logs system
✔️ Docker and Heroku ready
✅ Install
First clone the repo
git clone https://github.com/prinick96/hex-arch-go.git
⚠️ Now, the system need connect to a database, by default you can use Postgres or CockroachDB
- Just create a database
- Upload the schema on your DB
/db/schema.sql
- Change the enverioment variables located in .env.development
DB_ENGINE = "postgres or mysql"
DB_HOST = "host"
DB_PORT = 1234
DB_DATABASE = "db name"
DB_USERNAME = "user name"
DB_PASSWORD = "your secret password"
# For cockroach
DB_OPTIONS = "--cluster=cockroach-cluser-id"
# For postgres
DB_OPTIONS = "sslmode=disable timezone=UTC connect_timeout=5"
# For mysql
DB_OPTIONS = ""
✅ Run
If you want run in local, simply
go get
go run main.go
If you want run with Docker, simply
make docker-up
If you want run with Heroku local, simply
# For Linux/MacOS
make heroku-run
# For Windows
heroku-run-win
⚠️ If you use Windows, you need change Procfile in the root of project for
# For windows use
web: bin\hex-arch-go.exe
# web: bin/hex-arch-go
And now you can run Heroku local for Windows
✅ Test
For unit tests, simply
make unit-test
⚠️For integration tests, first need configure the .env.test vars adding the database test connection, after, simply
make integration-test
Or both of them
make test
🌳 Understanding the folder structure
.
├── /.github/workflows # Github Actions!
├── /cmd # Start the application with server and database
├── /core # The CORE of hexagonal architecture: infrastructure, application and domain
│ ├── /application # Handlers and the entry point of data
│ ├── /entities # The entities what conform the domain
│ └── /infrastructure # Gateways for the domain logic and Storage/Repository for the implementation of database
├── /db # Simply the schema of DB for you first run
├── /env # .env loader
├── /internal # Elemental logic common for all the system
│ ├── /database # Connection with database implemented
│ └── /helpers # Reusable functions around the app, like a UUID generation
│ └── tests # Unit tests for helpers
└── /server # The server listener and endpoints of API REST
Top comments (6)
Justify why hexagonal is a good fit for the requirements and goals you have in mind? What alternatives could achieve the same goals and why are they less desirable?
Hi! thanks for comment.
I will try to explain me, although my English is bad.
In the classic 3 layer architecture, the main problem is that the app is not focus in the domain, the domain layer has dependencies with the data layer for example, and that make it less scalable.
The clean architectures is a set of principles whose main purpose is to hide the implementation details from the domain logic of the application.
And.. the Hexagonal is a model of clean architecture, is better for be independent from frameworks, more testeable, independent of the data base and focus the domain.
If you need maintain an application, this propose is nice because you have lose coupling between the elements of your app.
If you need change the implementation of your database engine for example, you can do it without affect the domain business logic, for example.
If you want your app work with CLI Command line instead of API REST, you can do it without affect the domain business logic and infrastructure implementation.
Is the SOLID principles in macro scale.
Thanks. I should have said I am familiar with hexagonal and have implemented, just curious as to why you think it's the best choice in your current vision for requirements? Do you want to be able to change databases, etc?
Maybe, change the database engine is not for all cases, but a big change in version can be an example, or the update of API REST framework library use in the upper layer of the app.
Simply is more easy make small and big changes.
Could you expand on why you think hexagonal architecture is a bad fit for go? I'm still relatively new to Go and come from an OOP background, so just trying to learn.
Awesome!, thanks