Architecture hexagonale

Le problème

Quand un système grandit, le code se met souvent à tourner autour de la technique au lieu de tourner autour du métier.

On voit les mêmes symptômes revenir :

les règles métier vivent dans les controllers
les use cases dépendent directement de l’ORM ou du framework
la base de données finit par dicter la forme du modèle
tester une règle simple demande trop d’infrastructure
changer un provider externe coûte trop cher
personne ne sait vraiment où placer une nouvelle règle métier

Le problème n’est pas juste un manque de propreté.

Le vrai coût arrive ensuite :

les changements ralentissent
les régressions augmentent
les intégrations contaminent le cœur du système
le code devient plus difficile à lire que le métier lui-même

L’architecture hexagonale sert à remettre les frontières au bon endroit.

L’idée simple

L’idée centrale est simple :

le cœur métier ne doit pas dépendre des détails techniques.

En pratique, ça veut dire :

le domaine et les cas d’usage expriment l’intention métier
les entrées et sorties passent par des ports
la technique se branche via des adapters
les dépendances pointent vers le cœur

Le schéma de base est donc bien assez simple :

un cœur
des ports
des adapters

Mais pour l’appliquer correctement dans un vrai projet, il faut comprendre quelques notions autour :

qui dépend de qui
où placer la logique métier
ce qu’un adapter doit contenir
ce que signifie réellement “l’infrastructure au bord”

C’est exactement le rôle de cette section.

Est-ce que ce sujet te concerne ?

Ce sujet vaut le coup si tu te reconnais dans au moins une de ces situations :

le framework, l’ORM ou la base de données dictent déjà trop la structure du code
tu as du mal à savoir où placer la logique métier
plusieurs intégrations externes commencent à polluer les use cases
tester une règle métier simple est devenu trop coûteux
tu sens que le code reste livrable, mais devient de moins en moins lisible
tu veux mieux séparer le cœur métier des détails techniques

Tu n’as probablement pas besoin d’aller très loin tout de suite si :

ton problème est surtout CRUD
les règles métier sont encore faibles
le système est petit et ne souffre pas encore de son couplage
la structure actuelle ne ralentit pas encore les changements

L’idée n’est pas de faire de l’hexagonal par principe. L’idée est de savoir si cette structure répond à un vrai problème chez toi.

Un use case concret

Avant d’entrer dans le détail, prends un cas réel.

L’équipe front doit avancer, mais le BFF n’est pas prêt. On travaille avec des mocks. Le problème : rien ne garantit que la forme finale du payload ressemblera à celle du mock.

Si les composants consomment directement le mock, toute l’application risque de casser quand le vrai BFF arrive :

les noms changent
les champs bougent
le niveau de nesting change
certains cas métier arrivent plus tard
les stories et les tests deviennent faux

L’approche utile consiste à faire dépendre l’UI d’un modèle front stable, puis à absorber l’écart entre mock et BFF réel dans des adapters.

C’est exactement le genre de situation où l’architecture hexagonale devient intéressante :

le front définit ce qu’il consomme vraiment
les sources externes restent au bord
le câblage peut changer
le modèle utilisé par l’écran reste stable

Tu n’as pas besoin d’entrer dans tout le sujet pour savoir si ça t’intéresse : si tu vis ce type de décalage entre système réel et contrat instable, tu es déjà dans une zone où cette approche peut aider.

Si tu veux d’abord voir le sujet en action

Si tu préfères commencer par un cas concret avant de rentrer dans le détail des concepts :

Ces deux articles montrent comment l’approche aide quand le vrai problème n’est pas “comprendre un pattern”, mais continuer à livrer malgré des frontières instables.

Les concepts clés de la section

Cette section est organisée autour de quelques idées structurantes.

1. Le cœur métier

Le cœur contient :

les règles métier
les invariants
les comportements utiles
les cas d’usage

C’est la partie qui doit rester la plus lisible et la moins dépendante de la technique.

2. Les ports

Les ports sont des contrats.

Ils servent à exprimer :

ce que le système sait faire
ce dont le système a besoin

On distingue généralement :

des ports entrants
des ports sortants

3. Les adapters

Les adapters branchent le monde réel sur les ports.

Exemples courants :

controller HTTP
repository PostgreSQL
adapter Stripe
consumer Kafka
handler CLI
client BFF côté front

Leur rôle est de traduire la technique. Pas de décider du métier.

4. La direction des dépendances

C’est la règle qui tient toute l’architecture :

l’infrastructure dépend du cœur
pas l’inverse

Si cette règle casse, le reste devient vite cosmétique.

5. La séparation application / domaine

La couche application orchestre. Le domaine décide.

C’est une distinction simple, mais elle évite une énorme partie des erreurs d’implémentation.

6. L’infrastructure comme détail

Base de données, framework, provider externe, file de messages, BFF réel, mock temporaire : tout ça peut être important, mais ne doit pas piloter le cœur du design.

Comment lire un schéma hexagonal

Un schéma hexagonal se lit toujours de la même manière :

au centre : le cœur du système
autour : les interactions avec le monde extérieur
entre les deux : les ports
branchés sur les ports : les adapters

Vue d'ensemble de l'architecture hexagonale

La bonne lecture est simple :

les entrées arrivent par des adapters entrants
le cœur exécute le comportement utile
les sorties passent par des ports sortants
les détails techniques restent à l’extérieur

Si tu lis un schéma hexagonal uniquement comme une histoire de dossiers, tu passes à côté du point principal. Le vrai sujet est la frontière entre le cœur et les détails.

Ce que ça change en pratique

L’architecture hexagonale ne change pas seulement la forme des dossiers. Elle change surtout la manière de penser les frontières.

En pratique, elle pousse à :

faire partir le design du métier
isoler les dépendances volatiles
tester le cœur sans infrastructure lourde
éviter que le framework pilote le système
rendre les cas d’usage plus lisibles
limiter l’impact des changements de contrat externe
localiser le câblage au bon endroit

Elle ne rend pas automatiquement un projet meilleur. Mais elle rend plus visible ce qui doit rester stable et ce qui peut changer.

Erreurs fréquentes

Les erreurs les plus courantes reviennent presque toujours :

mettre des interfaces partout sans besoin réel
déplacer la logique métier dans les adapters
faire dépendre le domaine du framework
confondre couche application et couche domaine
traiter la base de données comme le centre du système
sur-architecturer un CRUD simple
confondre une belle arborescence avec une vraie bonne direction des dépendances

Cette section couvre ces erreurs en détail dans les articles dédiés.

Quand l’utiliser

L’architecture hexagonale devient surtout utile quand :

les règles métier commencent à compter
plusieurs intégrations externes existent
le code doit durer
les changements techniques sont fréquents
la testabilité devient importante
les contrats entre systèmes évoluent ou restent incertains
le framework ou la base commencent à piloter le design

Elle est souvent moins utile quand :

l’application est surtout CRUD
les règles métier sont faibles
la structure supplémentaire n’apporte pas de gain réel
le principal besoin est juste d’avoir un découpage simple et léger

Le sujet n’est pas d’appliquer un pattern partout. Le sujet est de choisir une structure proportionnée au problème.

Comment lire la suite de cette section

Tu peux lire cette section de plusieurs façons.

Parcours découverte

Pour comprendre les bases dans le bon ordre :

Parcours mise en œuvre

Pour aller vers l’application concrète :

Parcours cadrage

Pour savoir si le sujet vaut vraiment le coût :

Parcours front / BFF / contrat instable

Pour un cas plus proche du terrain front :

Parcours modèle métier lié

Pour relier l’architecture au design métier :

Sujets de cette section

Concepts de base

Comparaison et cadrage

Mise en œuvre

Use cases concrets

Concepts liés côté domain design

Conclusion

L’architecture hexagonale repose sur une idée simple : garder le cœur métier lisible et laisser la technique au bord.

Cette page sert de point d’entrée pour comprendre le sujet, vérifier s’il correspond à ton besoin réel, voir comment les concepts s’articulent et choisir le bon parcours de lecture.

Le réflexe utile à retenir est simple :

si ton vrai problème vient du couplage entre le cœur du système et des détails instables, tu es probablement au bon endroit.

Concepts connexes

Infrastructure as Detail

Pourquoi la base de données, le framework et les services externes doivent rester des détails techniques et non piloter le design du système.

→

Ports and Adapters

Comprendre le rôle des ports entrants et sortants, et comment les adapters relient le domaine au monde extérieur sans le contaminer.

→

Dependency Direction

Clarifier la direction des dépendances dans une architecture hexagonale pour éviter que l’infrastructure remonte dans le domaine.

→

Application Layer vs Domain Layer

Distinguer orchestration et logique métier pour savoir quoi mettre dans la couche application et quoi garder dans le domaine.

→