Blog

You can find all the project code sources here https://github.com/techerjeansebastienpro/go-hexa-example

Understanding Hexagonal Architecture

What is Hexagonal Architecture?

Hexagonal Architecture, also known as the Ports and Adapters pattern, is an architectural style that aims to create loosely coupled application components that can be easily connected and disconnected. This architecture promotes a separation of concerns by isolating the core business logic from external systems such as databases, user interfaces, and third-party services. The core idea is to have a central « hexagon » or core, surrounded by various « adapters » that handle the communication with external entities through well-defined « ports. »

In Hexagonal Architecture, the core consists of the application’s domain logic, including entities and use cases. The ports define the interfaces through which the core interacts with the outside world. Adapters are the implementations of these interfaces, providing the necessary code to connect the core to external systems. This structure allows the core to remain independent of the technical details of external systems, making the application more modular, maintainable, and testable.

Benefits and Principles

Benefits:

1. Modularity: Hexagonal Architecture encourages the development of self-contained modules that are easier to manage and understand. Each module has a clear responsibility and can be developed and tested in isolation.
2. Testability: By isolating the core business logic from external dependencies, Hexagonal Architecture makes it easier to write unit tests. Mocking external systems becomes straightforward, allowing for comprehensive testing of the core logic without requiring the actual systems.
3. Flexibility and Maintainability: The clear separation between the core and external systems makes it simpler to replace or upgrade components. For instance, switching from one database to another or changing the user interface framework can be done with minimal impact on the core business logic.
4. Independence from Frameworks: Hexagonal Architecture reduces the reliance on specific frameworks or technologies. The core logic remains pure and free from framework-specific code, making it easier to adapt to new frameworks or technological advancements.
5. Enhanced Collaboration: This architecture facilitates better collaboration between different teams, such as front-end and back-end developers. Since the core logic is separated from the interfaces, different teams can work on their respective parts without interfering with each other.

Principles:

1. Separation of Concerns: Divide the application into distinct sections with clear responsibilities. The core should handle the business logic, while adapters should manage the technical details of interacting with external systems.
2. Dependency Inversion: Depend on abstractions (ports) rather than concrete implementations. This principle ensures that the core logic does not directly depend on external systems, but rather on interfaces that can be implemented by any external system.
3. Explicit Interfaces: Define clear and explicit interfaces (ports) for communication between the core and external systems. This approach makes the interactions well-defined and predictable.
4. Independence from External Systems: Ensure that the core logic is not tightly coupled with any external system. The core should be self-sufficient and able to function without relying on specific external technologies or frameworks.
5. Adaptability: Design the system in a way that makes it easy to replace or modify components without affecting the core logic. Adapters should be plug-and-play, allowing for seamless integration with different external systems.

Project Structure

Overview of the directory and file organization

cmd/
  api/
    api.go
internal/
  application/
    user_dto.go
    user_http_handler.go
  domain/
    user_entities.go
    user_ports.go
    user_service.go
  infrastructure/
    user_repository.go
    user_api.go
pkg/
  models/

Justification for the chosen structure

Hexagonal Architecture principles don’t impose structure or models. We should apply them according to language limits and paradigms.

This implementation is my interpretation of these principles according to my own experience with this language.

I’m open for advice – do not hesitate to comment this blog post.

Domain Layer Implementation

Defining entities (User)

internal/domain/user_entities.go

On the business side, we manipulate entities. These objects represent the logic of the business.

package domain

type User struct {
	ID    string
	Email string
}

type FindOneById struct {
	ID string
}

type FindOneByEmail struct {
	Email string
}

type FindOneRequest struct {
	FindOneById
	FindOneByEmail
}

type CreateUser struct {
	Email    string
	Password string
}

Creating domain services and interfaces (ports)

internal/domain/user_ports.go

Here, we define the interfaces of our application. That’s what are the resources we can retrieve or actions we can do.

package domain

type UsersInput interface {
	GetByID(ID string) (User, error)
	CreateOne(request CreateUser) (User, error)
}

type UsersOuput interface {
	FindOneById(request FindOneById) (User, error)
	FindOneByEmail(request FindOneByEmail) (User, error)
	InsertOne(request CreateUser) (User, error)
}

internal/domain/user_service.go

This part aims to group all the business logic. If we have to add control checking or business rules …, we can add them here. It does not depend on any kind of technology and environment.

package domain

import (
	"errors"
)

type UserService struct {
	output UsersOuput
}

func NewUserService(out UsersOuput) *UserService {
	return &UserService{output: out}
}

func (s *UserService) FindOne(request FindOneRequest) (User, error) {
	if request.ID != "" {
		return s.output.FindOneById(FindOneById{ID: request.ID})
	}
	if request.Email != "" {
		return s.output.FindOneByEmail(FindOneByEmail{Email: request.Email})
	}
	return User{}, errors.New("invalid request")
}

func (s *UserService) Insert(request CreateUser) (User, error) {
	return s.output.InsertOne(request)
}

Infrastructure: Implementing Interfaces

Repository to access data sources

internal/infrastructure/user_repository.go

The repository is an implementation of the Output port UserOutput. As the domain service uses an output via dependency inversion, that implementation can be updated without affecting the business logic. In some cases, automated testing, for example, we can use a mocked repository.

package infrastructure

import (
	"context"

	"github.com/techerjeansebastienpro/go-hexa-example/internal/domain"
	db "github.com/techerjeansebastienpro/go-hexa-example/pkg/models"
)

type UserRepository struct {
	prisma *db.PrismaClient
}

func NewUserRepository(prisma *db.PrismaClient) *UserRepository {
	return &UserRepository{
		prisma: prisma,
	}
}

func (r *UserRepository) FindOneById(request domain.FindOneById) (domain.User, error) {
	ctx := context.Background()
	foundUser, err := r.prisma.User.FindUnique(
		db.User.ID.Equals(request.ID),
	).Exec(ctx)

	return domain.User{
		ID: foundUser.ID,
	}, err
}

func (r *UserRepository) FindOneByEmail(request domain.FindOneByEmail) (domain.User, error) {
	ctx := context.Background()
	foundUser, err := r.prisma.User.FindUnique(
		db.User.Email.Equals(request.Email),
	).Exec(ctx)

	return domain.User{
		ID: foundUser.ID,
	}, err
}

func (r *UserRepository) InsertOne(request domain.CreateUser) (domain.User, error) {
	ctx := context.Background()
	createdUser, err := r.prisma.User.CreateOne(
		db.User.Email.Set(request.Email),
		db.User.Password.Set(request.Password),
	).Exec(ctx)

	return domain.User{
		ID:    createdUser.ID,
		Email: createdUser.Email,
	}, err
}

API to expose your service

internal/infrastructure/user_api.go

The UserApi implements an input, UserInput, and uses the domain service. This part of the code does not depend on the environment and can be used by multiple « adapters » such as REST API / GraphQL API / gRPC … . We can mock the API in case of automated tests on those adapters.

package infrastructure

import (
	"github.com/techerjeansebastienpro/go-hexa-example/internal/domain"
)

type UserApi struct {
	userService domain.UserService
}

func NewUserApi(userService domain.UserService) *UserApi {
	return &UserApi{
		userService: userService,
	}
}

func (a *UserApi) GetByID(ID string) (domain.User, error) {

	return a.userService.FindOne(domain.FindOneRequest{
		FindOneById: domain.FindOneById{
			ID: ID,
		},
	})
}

func (a *UserApi) CreateOne(request domain.CreateUser) (domain.User, error) {
	return a.userService.Insert(domain.CreateUser{
		Email:    request.Email,
		Password: request.Password,
	})
}

Application: configure your application

Create the first HTTP Handler

package application

import (
	"github.com/gin-gonic/gin"
	"github.com/techerjeansebastienpro/go-hexa-example/internal/domain"
)

type UserHttpHandler struct {
	userInput domain.UsersInput
	app       *gin.Engine
}

func NewUserHttpHandler(app *gin.Engine, userInput domain.UsersInput) *UserHttpHandler {
	return &UserHttpHandler{
		userInput: userInput,
		app:       app,
	}
}

func (u *UserHttpHandler) RegisterRoutes() {
	u.app.GET("/users/:id", u.GetByID)
	u.app.POST("/users", u.Create)
}

func (u *UserHttpHandler) GetByID(c *gin.Context) {
	id := c.Param("id")
	user, err := u.userInput.GetByID(id)
	if err != nil {
		c.JSON(500, gin.H{"error": err.Error()})
		return
	}

	c.JSON(200, user)
}

func (u *UserHttpHandler) Create(c *gin.Context) {
	var createUser domain.CreateUser
	if err := c.ShouldBindJSON(&createUser); err != nil {
		c.JSON(400, gin.H{"error": err.Error()})
		return
	}

	user, err := u.userInput.CreateOne(createUser)
	if err != nil {
		c.JSON(500, gin.H{"error": err.Error()})
		return
	}

	c.JSON(201, &UserDTO{
		ID:    user.ID,
		Email: user.Email,
	})
}

package application

type UserDTO struct {
	ID    string `json:"id"`
	Email string `json:"email"`
}

Complete Example

Putting it all together in api.go

cmd/api/api.go

The program needs an entry point to bootstrap services and core systems. We instantiate all the services we need to run a specific HTTP service to handle external requests.

package main

import (
	"fmt"

	"github.com/gin-gonic/gin"
	"github.com/spf13/viper"
	"github.com/techerjeansebastienpro/go-hexa-example/internal/application"
	"github.com/techerjeansebastienpro/go-hexa-example/internal/domain"
	"github.com/techerjeansebastienpro/go-hexa-example/internal/infrastructure"
	db "github.com/techerjeansebastienpro/go-hexa-example/pkg/models"
)

func main() {
	envConfig()
	fmt.Println(viper.GetString("DATABASE_URL"))
	prismaClient := db.NewClient(
		db.WithDatasourceURL(viper.GetString("DATABASE_URL")),
	)
	if err := prismaClient.Prisma.Connect(); err != nil {
		panic(err)
	}

	defer func() {
		if err := prismaClient.Prisma.Disconnect(); err != nil {
			panic(err)
		}
	}()
	userService := domain.NewUserService(infrastructure.NewUserRepository((prismaClient)))
	api := infrastructure.NewUserApi(*userService)

	app := gin.New()
	application.NewUserHttpHandler(app, api).RegisterRoutes()

	app.Run(":8080")

}

func envConfig() {
	viper.SetConfigFile(".env")
	viper.ReadInConfig()
}

Explanation of the overall flow

This article provides an implementation overview, illustrating how the Hexagonal Architecture principles are applied in our Go project. Hexagonal Architecture is based on the principles of modularity, separation of concerns, and independence from external systems, ensuring that the core business logic remains isolated from technical details. While Go is a powerful and efficient language for implementing these principles, it does have some limitations, particularly in its support for generics. The limited generics in Go can restrict the ability to encapsulate certain functionalities, which might be more seamlessly achieved in languages with more advanced generic capabilities, such as Java or C#. Nonetheless, Go’s simplicity and strong typing make it a suitable choice for many applications, providing a clear and maintainable structure that adheres to the core concepts of Hexagonal Architecture.

Conclusion

In this blog post, we explored the implementation of Hexagonal Architecture in a Go project through a user management system. We started by understanding the core principles and benefits of this architectural pattern. Then, we delved into the detailed structure of our project, from defining the domain layer to implementing adapters and configuring the infrastructure. By maintaining a clear separation of concerns, Hexagonal Architecture not only enhances the modularity and testability of applications but also makes them more adaptable to changes. Whether you’re working on a small project or a complex system, this architecture can provide a robust foundation. We encourage you to experiment with this architecture in your projects and experience the benefits firsthand. Feel free to share your thoughts and questions in the comments below – we’d love to hear from you! Happy coding!