Si vous êtes développeur, architecte logiciel ou simplement curieux du monde du développement logiciel, vous avez sûrement déjà entendu parler de l’architecture hexagonale. Ce modèle, parfois appelé Ports & Adapters, est devenu un standard pour structurer des applications Web, des applications mobiles ou même des systèmes d’information complexes.
Dans cet article, je vous propose une vue complète : définition, histoire, principes, exemples concrets en Java/Python, comparaison avec d’autres architectures, avantages, limites, bonnes pratiques, et même une FAQ. Nous allons également aborder la modélisation UML, le logiciel métier, les tests unitaires, les frameworks et les design patterns. Bref, tout ce qu’il faut pour comprendre pourquoi cette architecture est aussi populaire.
Qu’est-ce que l’architecture hexagonale ?
Définition simple et claire
L’architecture hexagonale est un pattern d’architecture logicielle qui consiste à placer le code métier (ou logique applicative) au centre de l’application, puis à entourer ce cœur de ports (interfaces) et adaptateurs (implémentations). L’objectif est de séparer clairement la logique métier de l’infrastructure (base de données, framework web, UI, services externes, etc.).
Le but ?
Rendre l’application plus modulable, testable, maintenable et indépendante des technologies.
En pratique, le cœur métier ne connaît pas le framework, ni le langage de programmation, ni la base de données. Il ne dépend que d’interfaces.
Objectifs principaux
Les objectifs principaux de l’architecture hexagonale sont :
- Isoler la logique métier (domain / business logic) du reste du système.
- Rendre le système testable, notamment avec des tests unitaires et des tests d’intégration.
- Découpler les dépendances : framework, bases de données, UI, API externes.
- Faciliter la réutilisation du code métier dans plusieurs applications (web, mobile, microservices).
Histoire et origine de l’architecture hexagonale
Qui l’a inventée ?
L’architecture hexagonale a été inventée par Alistair Cockburn en 2005. À l’époque, beaucoup d’applications étaient développées en architecture en couches (MVC, trois tiers, etc.), et Cockburn a voulu proposer une approche plus flexible.
Contexte de création
Le constat était simple :
- Dans une architecture en couches, la logique métier finit souvent par dépendre fortement de la base de données (SQL, ORM, JDBC) ou du framework (Spring, Symfony, Django).
- Résultat : le code devient difficile à tester, à faire évoluer, et à migrer vers d’autres technologies.
Cockburn propose alors une architecture où :
- Le cœur métier est indépendant.
- Les dépendances vont vers l’intérieur (principe d’inversion de dépendance).
- Les composants externes se branchent via des ports.
Évolution dans le temps
Avec le temps, l’architecture hexagonale a influencé d’autres modèles comme :
- Clean Architecture
- Onion Architecture
- Domain Driven Design (DDD)
Aujourd’hui, elle est utilisée dans des projets modernes, notamment en Java, Python, PHP, Node.js, ou encore .NET, et dans des environnements microservices ou cloud.
Pourquoi elle est devenue populaire ?
Elle est devenue populaire parce qu’elle répond à des besoins réels :
- Testabilité : vous pouvez tester la logique métier sans base de données.
- Multiples interfaces : application web, API, CLI, interface utilisateur, systèmes embarqués.
- Projets évolutifs : vous pouvez changer de base de données (MySQL, PostgreSQL, MongoDB) ou de framework sans toucher au cœur métier.
- Architecture orientée domaine : la logique métier est le cœur du système.
Les principes fondamentaux de l’architecture hexagonale
Le cœur métier au centre
Le cœur métier contient :
- Les entités (domain model)
- Les cas d’utilisation (use cases)
- Les règles métier
- La logique applicative
Il est totalement indépendant du reste.
Ports (interfaces)
Les ports sont des interfaces (en Java, PHP, Python, etc.) qui définissent des contrats :
- Exemple : UserRepository, PaymentGateway, EmailService.
Les ports ne contiennent pas d’implémentation, seulement des spécifications.
Adaptateurs (implémentations)
Les adaptateurs sont les implémentations concrètes des ports :
- Adapter vers une base de données (MySQL, PostgreSQL, MongoDB)
- Adapter vers une API REST
- Adapter vers un framework (Spring, Symfony, Django)
- Adapter vers un système de queue (Kafka, RabbitMQ)
Dépendances vers l’intérieur
Dans une architecture hexagonale, les dépendances doivent aller vers le centre :
- Les adaptateurs dépendent du cœur métier
- Le cœur métier ne dépend pas des adaptateurs
Ce principe est crucial pour maintenir l’indépendance du code métier.
Architecture hexagonale vs autres architectures
Hexagonale vs architecture en couches
| Architecture en couches | Architecture hexagonale |
| UI → Service → DB | Cœur métier indépendant |
| Forte dépendance au framework | Dépendances inversées |
| Difficulté de tests unitaires | Tests faciles et isolés |
| Couplage élevé | Couplage faible |
Hexagonale vs Clean Architecture / Onion Architecture
Ces architectures sont très proches, mais :
- Hexagonale insiste sur les ports et adaptateurs
- Clean Architecture insiste sur les couches concentriques
- Onion Architecture met l’accent sur le domaine au centre
Dans tous les cas, le principe est le même : séparer le code métier de l’infrastructure.
Quand choisir l’architecture hexagonale ?
Elle est idéale pour :
- Applications Web complexes
- Systèmes d’information
- Microservices
- Projets nécessitant une forte maintenabilité
- Projets où la testabilité est essentielle
Elle est parfois surdimensionnée pour des projets simples (petits prototypes ou MVP très rapides).
Schéma & visualisation
Schéma de l’architecture hexagonale
Le schéma typique ressemble à un hexagone :
- Au centre : Domain / Business Logic
- Autour : Ports
- À l’extérieur : Adaptateurs (infrastructure)
Si vous souhaitez un diagramme UML, on peut le faire avec un diagramme de classes ou un diagramme de composants.
Exemple de flux (commande, paiement)
Imaginons un système de commande e-commerce :
- L’utilisateur passe une commande via une application Web
- Le contrôleur appelle un cas d’utilisation
- Le cas d’utilisation utilise un port OrderRepository
- L’adaptateur OrderRepositoryMySQL implémente le port et écrit dans la BDD
- Un adaptateur PaymentGatewayStripe gère le paiement
Ainsi, le code métier reste indépendant de MySQL, Stripe, ou du framework.
Exemple concret d’implémentation
Exemple en Java / Spring
Structure de répertoires (typique) :
src/main/java
├── domain
│ ├── model
│ ├── service
│ └── port
├── application
│ ├── usecase
└── infrastructure
├── adapter
└── configuration
Exemple de port :
public interface UserRepository {
User findById(String id);
void save(User user);
}
Exemple d’adaptateur :
@Repository
public class UserRepositoryMySQL implements UserRepository {
@Autowired
private JdbcTemplate jdbcTemplate;
@Override
public User findById(String id) {
// requête SQL
}
@Override
public void save(User user) {
// insert SQL
}
}
Exemple en Python
En Python, on peut faire un modèle similaire :
domain/
model.py
ports.py
application/
usecases.py
infrastructure/
adapters.py
Exemple :
class UserRepository:
def find_by_id(self, user_id):
raise NotImplementedError
def save(self, user):
raise NotImplementedError
Tests unitaires et tests d’intégration
Le gros avantage, c’est que vous pouvez tester le code métier sans base de données :
- Tests unitaires sur les cas d’utilisation
- Tests d’intégration sur les adaptateurs (DB, API, etc.)
Avantages de l’architecture hexagonale
Testabilité améliorée
Vous pouvez tester le code métier sans infrastructure.
Les tests unitaires deviennent rapides et fiables.
Maintenabilité et évolutivité
Vous pouvez changer :
- le framework (Spring → Quarkus)
- la base de données (MySQL → PostgreSQL)
- l’API externe (Stripe → PayPal)
…sans toucher au code métier.
Indépendance technologique
Le cœur métier ne dépend d’aucun framework, langage ou ORM.
Réduction des régressions
Comme la logique métier est isolée, les modifications techniques ont moins de risques d’impacter le domaine.
Inconvénients et limites
Complexité initiale
Au début, c’est plus complexe à mettre en place.
Mais sur le long terme, cela paye.
Surdimensionnement pour petits projets
Pour un petit site vitrine ou un mini outil, cela peut être trop lourd.
Discipline de design requise
Il faut bien définir les ports, adapter le code et respecter les règles.
Bonnes pratiques et conseils
Définir les ports dès le départ
Les ports sont la base. Si vous les définissez mal, l’architecture s’effondre.
Séparer domain / application / infrastructure
Un bon découpage est essentiel :
- Domain : modèle métier
- Application : cas d’utilisation
- Infrastructure : implémentations (DB, frameworks, etc.)
Tester le cœur métier
Les tests unitaires doivent se concentrer sur le domaine.
Documenter les interfaces
Utilisez des spécifications, des diagrammes UML et des schémas.
Cas d’usage / exemples réels
Microservices
Chaque microservice peut être une architecture hexagonale à part entière.
Systèmes multi-interfaces
Quand vous avez :
- API REST
- UI web
- Application mobile
- CLI
L’architecture hexagonale est idéale.
Projets évolutifs
Quand vous savez que votre application va évoluer, changer de framework, de base de données, etc.
Conclusion
L’architecture hexagonale est une approche moderne et robuste pour développer des applications logicielles solides, testables et évolutives. Elle est particulièrement utile dans les projets où la logique métier est au cœur du système, où les interfaces sont multiples, et où la maintenance et la qualité sont prioritaires.
Si vous êtes développeur, architecte logiciel ou chef de projet, elle mérite d’être maîtrisée. Et si vous le souhaitez, je peux vous aider à créer un exemple complet en Java/Spring, un diagramme UML, ou un projet modèle prêt à coder.
