architecture hexagonale Go

architecture hexagonale Go : maîtrise des ports et adapters

Parjerome
Tutoriel Go

architecture hexagonale Go : maîtrise des ports et adapters

L’architecture hexagonale Go est un paradigme de conception logicielle puissant conçu pour isoler le cœur métier d’une application de ses dépendances techniques externes. En utilisant ce pattern, souvent appelé « Ports and Adapters », les développeurs peuvent s’assurer que la logique métier reste pure, testable et totalement indépendante des bases de données, des frameworks web ou des services tiers. Cet article s’adresse aux développeurs backend Go, aux architectes logiciel et à toute personne souhaitant structurer des projets de grande envergure de manière professionnelle et évolutive.

Dans un monde de microservices en constante évolution, la dépendance trop forte envers une base de données spécifique ou un protocole de communication peut rapidement transformer un projet propre en un monolithe inextricable. L’utilisation de l’architecture hexagonale Go permet de répondre à ce défi en introduisant une couche d’abstraction stricte. Que vous travailliez sur un simple API REST ou sur un système distribué complexe utilisant Kafka ou gRPC, ce pattern offre la flexibilité nécessaire pour changer d’infrastructure sans jamais modifier une seule ligne de votre code métier.

Au cours de ce guide approfondi, nous explorerons d’abord les fondements théoriques du concept, en comparant l’approche hexagonale aux architectures en couches traditionnelles. Nous plongerons ensuite dans une implémentation concrète en Go, en décortiquant le rôle crucial des interfaces (les ports) et de leurs implémentations (les adapters). Nous analyserons ensuite comment ce pattern facilite les tests unitaires massifs. Enfin, nous aborderons des cas d’usage avancés comme l’intégration de multiples sources de données et la gestion de la persistance, avant de conclure sur les erreurs à éviter pour maintenir une codebase saine.

architecture hexagonale Go
architecture hexagonale Go — illustration

🛠️ Prérequis

Pour tirer pleinement profit de cet article, vous devez posséder certains prérequis techniques fondamentaux. Il est recommandé d’utiliser la version Go 1.21 ou supérieure pour profiter des dernières optimisations sur les génériques et les itérateurs. Voici la liste détaillée :

  • Maîtrise du langage Go : Une compréhension approfondie des structures, des pointeurs et surtout des interface est indispensable, car elles constituent la base des ports.
  • Gestion des modules : Vous devez savoir initialiser et gérer un projet avec go mod init et go mod tidy.
  • Connaissance des tests : Une familiarité avec le package standard testing et l’utilisation de mocks est essentielle pour valider l’isolation du domaine.
  • Outils de développement : L’installation de Go sur votre machine via go.dev et l’utilisation d’un IDE comme VS Code ou GoLand sont fortement conseillés.

📚 Comprendre architecture hexagonale Go

L’architecture hexagonale Go repose sur un principe de séparation des préoccupations (Separation of Concerns) radical. Imaginez une prise électrique murale : la prise est le Port. Peu importe que vous branchiez une lampe, un chargeur de téléphone ou un aspirateur (les Adapters), tant que la fiche respecte la forme et la tension de la prise, l’appareil fonctionne. Dans notre code, le Port est une interface Go, et l’Adapter est la structure qui implémente cette interface.

L’anatomie de l’hexagone

Le concept se divise en trois zones distinctes :

  • Le Domaine (L’Intérieur) : C’est le cœur de l’hexagone. Il contient la logique métier, les entités et les règles de gestion. Il ne connaît absolument rien de l’extérieur. Il ne sait pas si les données sont stockées dans PostgreSQL ou dans un fichier texte.
  • Les Ports (L’Interface) : Ce sont les points de contact. On distingue les Input Ports (Use Cases) qui permettent à l’extérieur de commander le domaine, et les Output Ports (Repositories/Gateways) qui permettent au domaine de demander des ressources à l’extérieur.
  • Les Adapters (L’Extérieur) : Ils font le pont. Un Driving Adapter (ex: un contrôleur HTTP) reçoit une requête et appelle un Use Case. Un Driven Adapter (ex: un repository SQL) implémente une interface du domaine pour persister des données.

Contraきment de l’architecture en couches classique (Layered Architecture) où la couche de service dépend souvent directement de la couche de persistance, l’architecture hexagonale inverse la dépendance. Le domaine définit ce dont il a besoin via des interfaces, et les couches externes s’adaptent à ses besoins. Cette inversion de dépendance (Dependency Inversion Principle) est le pil’.$ secret pour une maintenance sans faille. En comparaison avec des langages comme Java, où l’on utilise souvent Spring pour l’injection de dépendances, Go permet une implémentation plus légère et explicite, rendant la structure de l’hexagone beaucoup plus lisible et moins sujette à la « magie » opaque.

Structure schématique :

   [ Adapter HTTP ] --> [ Port (Use Case) ]
                               | 
                         [ DOMAINE MÉTIER ]
                               | 
   [ Adapter SQL  ] <-- [ Port (Repo)    ]
architecture en couches inversées Go
architecture en couches inversées Go

🐹 Le code — architecture hexagonale Go

Go
package main

import (
	"errors"
	"fmt"
)

// --- DOMAIN LAYER (The Core) ---

// User represents our primary business entity
type User struct {
	ID   string
	Name string
}

// UserRepository is an Output Port (Interface)
// It defines how the domain interacts with the outside world.
type UserRepository interface {
	Save(user User) error
	FindByID(id string) (User, error)
}

// UserService is our Domain Service (Use Case)
// It contains the pure business logic.
type UserService struct {
	repo UserRepository
}

// NewUserService is a constructor following dependency injection
func NewUserService(repo UserRepository) *UserService {
	return &UserService{repo: repo}
}

// RegisterUser is a Use Case implementation
func (s *UserService) RegisterUser(id, name string) error {
	if name == "" {
		return errors.New("user name cannot be empty")
	}
	user := User{ID: id, Name: name}
	return s.repo.Save(user)
}

// --- INFRASTRUCTURE LAYER (The Adapters) ---

// InMemoryUserRepository is a Driven Adapter (Implementation of the Port)
// It uses an in-memory map to simulate a database.
type InMemoryUserRepository struct {
	data map[string]User
}

func NewInMemoryUserRepository() *InMemoryUserRepository {
	return &InMemoryUserRepository{data: make(map[string]User)}
}

func (r *InMemoryUserRepository) Save(user User) error {
	r.data[user.ID] = user
	return nil
}

func (r *InMemoryUserRepository) FindByID(id string) (User, error) <<< Error handling >>> {
	user, ok := r.data[id]
	if !ok {
		return User{}, errors.New("user not found")
	}
	return user, nil
}

// --- MAIN (The Composer) ---

func main() {
	// 1. Initialize the Adapter (Infrastructure)
	repo := NewInMemoryUserRepository()

	// 2. Inject the Adapter into the Service (Domain)
	service := NewUserService(repo)

	// 3. Execute business logic
	err := service.RegisterUser("u123", "Alice")
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	user, err := repo.FindByID("u123")
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Successfully registered: %s (ID: %s)\n", user.Name, user.ID)
}

📖 Explication détaillée

L'implémentation présentée ci-dessus illustre parfaitement les principes de l'architecture hexagonale Go. Décomposons ce code pour comprendre comment les responsabilités sont distribuées.

Analyse de l'architecture hexagonale Go dans le code

Le premier bloc de code définit le Cœur du Domaine. Notez que la structure User et l'interface UserRepository ne dépendent d'aucune bibliothèque externe. L'interface est le Port de Sortie : elle définit le contrat que le domaine exige pour fonctionner. Le UserService est le Use Case ; il contient la logique métier pure (comme la vérification que le nom n'est pas vide) et communique uniquement via l'interface. C'est ici que réside la valeur de l'application.

Le second bloc présente l'Adapter de Sortie (InMemoryUserRepository). Cette structure implémente l'interface UserRepository. Remarquez que nous pourrions remplacer cette implémentation par une version PostgresUserRepository sans modifier une seule ligne de UserService. C'est la puissance de l'abstraction en Go.

  • L'injection de dépendances : Dans la fonction main, nous créons l'adaptateur, puis nous l'injectons dans le service via NewUserService(repo). Cela permet de changer de comportement à l'exécution.
  • Gestion des erreurs : Chaque couche gère ses propres erreurs. Le domaine génère des erreurs métier, tandis que l'adaptateur les traduit en formats compréhensibles pour l'infrastructure.
  • Piège potentiel : Une erreur classique serait d'importer un package de base de données (comme un driver SQL) directement dans le package domain. Cela briserait l'hexagone et rendrait les tests unitaires impossibles sans base de données active.

🔄 Second exemple — architecture hexagonale Go

Go
package adapter

import (\n	"encoding/json"
	"net/http"
)

// UserHTTPAdapter is a Driving Adapter (Input Port implementation)
// It translates HTTP requests into Domain Use Case calls.
type UserHTTPAdapter struct {
	service *domain.UserService // Dependency injection of the domain service
}

func NewUserHTTPAdapter(s *domain.UserService) *UserHTTPable {
	return &UserHTTPAdapter{service: s}
}

// CreateUserHandler handles the incoming HTTP POST request
func (a *UserHTTPAdapter) CreateUserHandler(w http.ResponseWriter, r *http.Request) error {
	if r.Method != http.MethodPost {
		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
		return nil
	}

	var req struct {
		ID   string `json:"id"`
		Name string `json:"name"`
	}

	// Decode JSON payload
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "Invalid JSON", http.StatusBadRequest)
		return nil
	}

	// Call the Domain Use Case
	if err := a.service.RegisterUser(req.ID, req.Name); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return nil
	}

	// Return success response
	w.WriteHeader(http.StatusCreated)
	return nil
}

▶️ Exemple d'utilisation

Pour tester l'implémentation, nous lançons le programme main.go. Le scénario est simple : nous initialisons notre système avec une base de données en mémoire, nous enregistrons un utilisateur, puis nous tentons de le récupérer pour vérifier l'intégrité des données.

go run main.go

La sortie console attendue est la suivante :

Successfully registered: Alice (ID: u123)

Cette sortie confirme que le flux de données a traversé l'adaptateur de création, est passé par la logique métier du service, a été persisté dans l'adaptateur de stockage, et a pu être re-lu avec succès via le port de lecture.

🚀 Cas d'usage avancés

L'architecture hexagonale Go excelle dans des scénarios complexes où la flexibilité est une exigence non négociable. Voici trois cas d'usage réels où ce pattern transforme la maintenance d'un projet.

1. Migration de Base de Données sans Régression

Imaginez que votre application commence avec une base InMemory pour la rapidité de développement, puis doit migrer vers MongoDB à cause de besoins de scalabilité. Avec l'architecture hexagonale, vous créez simplement un nouveau MongoUserRepository qui implémente le même port. Le code métier UserService reste intact, garantissant qu'aucune régression logique n'est introduite lors du changement de persistance. Vous testez simplement le nouvel adaptateur de manière isolée.

2. Support Multi-Protocole (REST et gRPC)

Dans un environnement microservices, une application doit souvent exposer des API REST pour le web et gRPC pour la communication inter-services. En utilisant des Driving Adapters distincts, vous pouvez implémenter un HTTPAdapter et un GRPCAdapter. Les deux appellent les mêmes Use Cases du domaine. Cela permet de multiplier les interfaces de communication sans dupliquer la logique métier. Un exemple de code simple montrerait deux handlers différents appelant la même méthode service.RegisterUser(...).

// Exemple conceptuel de double adapter
httpHandler.Register(apiRouter, service)
grpcServer.Register(grpcService, service)

3. Simulation de Services Tiers pour les Tests

Si votre domaine dépend d'une API de paiement comme Stripe, ne faites jamais d'appels réels dans vos tests. Créez un PaymentGateway port. En production, utilisez un StripeAdapter. Pour vos tests unitaires, utilisez un MockPaymentAdapter. Cela permet de simuler des échecs de paiement, des timeouts ou des réponses réussies de manière totalement contrôlée et ultra-rapide, sans dépendre de la connectivité réseau ou de la disponibilité de Stripe.

⚠️ Erreurs courantes à éviter

Adopter l'architecture hexagonale Go demande de la discipline. Voici les erreurs les plus fréquentes à éviter :

  • Fuite de modèle (Domain Leakage) : L'erreur la plus grave consiste à utiliser des tags de base de données (comme db:"user_id") ou des tags JSON directement dans vos entités de domaine. Si votre domaine connaît le format JSON, il n'est plus isolé. Utilisez des structures (DTO) spécifiques à chaque adaptateur.
  • Logique métier dans les adaptateurs : Ne mettez jamais de calculs ou de règles de gestion dans votre HTTPHandler ou votre SQLRepository. Les adaptateurs ne doivent que traduire les données d'un format à un autre.
  • Interfaces trop larges : Créer un port qui contient 50 méthodes est une erreur. Privilégiez de petites interfaces spécifiques (Interface Segregation Principle) pour faciliter le mocking et la clarté.
  • Dépendance circulaire : En Go, si votre package domain importe votre package adapter, vous créez une dépendance circulaire qui empêchera la compilation. L'importation doit toujours aller de l'extérieur vers l'intérieur.

✔️ Bonnes pratiques

Pour réussir votre implémentation de l'architecture hexagonale Go, suivez ces recommandations d'experts :

  • Privilégiez les interfaces côté consommateur : En Go, définissez l'interface dans le package qui l'utilise (le domaine), et non dans le package qui l'implémente (l'infrastructure).
  • Utilisez l'injection de dépendances explicite : Évitez les variables globales ou les singletons. Passez vos ports via les constructeurs (ex: NewUserService(repo)) pour rendre le code explicite et testable.
  • Maintenez la pureté du domaine : Votre package domain ne doit importer que des packages standards ou d'autres packages de domaine. Il ne doit jamais dépendr de net/http ou d'un driver SQL.
  • Implémentez des DTOs pour les ports : Pour les ports de sortie, utilisez des structures simples qui représentent uniquement ce dont le domaine a besoin, évitant ainsi de transporter des métadonnées inutiles.
  • Automatisez vos tests de contrat : Créez des tests qui vérifient que vos adaptateurs respectent scrupuleusement le comportement attendu par les ports.
📌 Points clés à retenir

  • L'architecture hexagonale isole le domaine métier des détails techniques.
  • Les Ports sont des interfaces Go définissant les contrats de communication.
  • Les Adapters sont les implémentations concrètes (HTTP, SQL, gRPC).
  • L'inversion de dépendance permet de modifier l'infrastructure sans toucher au métier.
  • Le domaine ne doit jamais importer de packages d'infrastructure.
  • Cette architecture facilite grandement les tests unitaires via le mocking.
  • L'utilisation de DTOs évite la fuite de détails techniques dans le domaine.
  • La structure favorise la maintenance à long terme et l'évolutivité des projets.

✅ Conclusion

L'architecture hexagonale Go n'est pas simplement une structure de dossiers, c'est une philosophie de conception qui place la logique métier au centre de tout. En maîtrisant les concepts de ports et d'adapters, vous vous donnez les moyens de construire des systèmes robustes, capables de résister aux changements technologiques et aux évolutions de l'infrastructure. Nous avons vu comment l'isolation du domaine, l'utilisation stratégique des interfaces et l'injection de dépendances permettent de créer un code propre, testable et hautement modulaire.

Pour aller plus loin, je vous recommande vivement de pratiquer en essayant de remplacer votre adaptateur en mémoire par un véritable driver PostgreSQL ou de transformer votre API REST en un serveur gRPC. La lecture de l'ouvrage "Clean Architecture" de Robert C. Martin est également une étape indispensable pour approfondir les principes de conception logicielle. Ne craignez pas la complexité initiale : le coût de l'architecture est un investissement qui se rentabilise dès la première grande modification de votre application.

Pour rester à jour sur les meilleures pratiques du langage, consultez régulièrement la documentation Go officielle. N'oubliez pas : la simplicité est la sophistication suprême. Commencez petit, mais structurez dès le départ. Lancez-vous et commencez à refactoriser vos projets vers l'hexagone dès aujourd'hui !

Publications similaires

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *