01 - Le concept : ports, adaptateurs et le domaine au centre
Ce que tu vas apprendre
- Les trois zones de l'architecture hexagonale
- La différence entre ports entrants et ports sortants
- La regle de dépendance qui tient tout ensemble
Prerequisites
Le schema qui explique tout
Adaptateur entrant Adaptateur entrant
(Express Controller) (CLI Command)
| |
v v
+-----|--------------------------|-----+
| | PORTS ENTRANTS | |
| [CreateOrder] [GetOrder] |
| |
| +---------------+ |
| | | |
| | DOMAINE | |
| | (metier) | |
| | | |
| +---------------+ |
| |
| [OrderRepository] [PaymentGateway]|
| PORTS SORTANTS |
+-----|--------------------------|-----+
| |
v v
Adaptateur sortant Adaptateur sortant
(PostgreSQL Repo) (Stripe Gateway)Oublie la forme hexagonale. Ce qui compte, ce sont les trois zones.
Zone 1 : le domaine (le centre)
Le domaine contient ta logique métier. Les regles, les calculs, les validations, les transitions d'état. Rien d'autre.
Pas de import express. Pas de import pg. Pas de fetch. Le domaine est un monde ferme qui ne connaît que ses propres types et ses propres regles. Si tu retires Express, PostgreSQL, Redis, Stripe et tout le reste, le domaine compile encore.
C'est la partie la plus stable de ton application. Les frameworks changent, les bases de donnees migrent, les API externes evoluent. La logique métier, elle, reste.
On en parlera en détail dans l'article 02 sur le domaine. Si tu connais deja le concept de domaine métier via la serie Domaines et cycles de vie, tu es en terrain connu.
Zone 2 : les ports (les interfaces)
Un port, c'est une interface TypeScript. Point. C'est le contrat entre le domaine et le monde extérieur.
Il y a deux types de ports :
Les ports entrants (driving ports) definissent ce que le monde extérieur peut demander au domaine. "Creer une commande", "Récupérer une commande par ID", "Annuler une commande". Ce sont les cas d'usage de ton application.
Les ports sortants (driven ports) definissent ce dont le domaine a besoin du monde extérieur. "Sauvegarder une commande", "Envoyer un paiement", "Envoyer un email". Le domaine dit "j'ai besoin de ca" mais ne dit jamais comment le faire.
La subtilite : les ports appartiennent au domaine. C'est le domaine qui décidé quelles opérations existent. Le monde extérieur doit respecter ces contrats.
Zone 3 : les adaptateurs (les implementations)
Les adaptateurs sont le code concret qui connecte le domaine au monde réel.
Les adaptateurs entrants recoivent des requêtes et appellent les ports entrants. Un controller Express qui recoit un POST et appelle CreateOrderPort. Un handler CLI qui lit les arguments et appelle le meme port. Un resolver GraphQL. Un job cron.
Les adaptateurs sortants implementent les ports sortants. Un repository PostgreSQL qui implemente OrderRepositoryPort. Un client Stripe qui implemente PaymentGatewayPort. Un service SendGrid qui implemente EmailSenderPort.
Le point fort : tu peux avoir plusieurs adaptateurs pour le meme port. Un PostgresOrderRepository pour la prod, un InMemoryOrderRepository pour les tests. Meme interface, implementation différente.
L'analogie qui m'a fait comprendre
Pense a un lecteur de musique. Le domaine, c'est le lecteur lui-meme : il sait lire de l'audio, gerer le volume, passer a la piste suivante.
Les ports sortants, c'est la prise jack et le port USB. Le lecteur sait qu'il peut "envoyer du son" (interface) mais il ne sait pas a quoi il est branche.
Les adaptateurs sortants, c'est le casque, l'enceinte Bluetooth, le système audio de la voiture. Chacun recoit le son differemment, mais tous respectent le meme contrat (la prise jack ou l'USB).
Tu veux changer d'enceinte ? Debranche l'ancienne, branche la nouvelle. Le lecteur ne change pas. C'est exactement ce que fait l'architecture hexagonale avec ton code.
La regle de dépendance
C'est la regle la plus importante. Si tu retiens une seule chose de cet article, c'est celle-ci :
Les dépendances pointent toujours vers le centre.
- Les adaptateurs dependent des ports
- Les ports dependent du domaine
- Le domaine ne depend de rien
Adaptateurs --> Ports --> Domaine --> (rien)C'est le principe d'inversion de dépendance en action. Dans un code classique, le domaine appelle la base de donnees. Ici, le domaine definit un port "je veux sauvegarder", et c'est l'adaptateur qui implemente le comment. Le flux de contrôle va du domaine vers la base, mais la dépendance va de la base vers le domaine.
Cette inversion change tout. Elle rend le domaine testable sans infrastructure, remplacable sans réécriture, et lisible sans connaître les détails techniques.
Sur paltemps.fr, c'est le premier concept qu'on explique quand on forme une équipe a l'architecture hexagonale. Si la regle de dépendance est comprise, le reste suit naturellement.
Résumé
- Trois zones : domaine (centre), ports (interfaces), adaptateurs (implementations)
- Ports entrants : ce que le monde peut demander au domaine
- Ports sortants : ce dont le domaine a besoin du monde
- Adaptateurs : le code concret qui branche le tout
- La regle : les dépendances pointent toujours vers le centre
Article précédent : 00 - Introduction
Article suivant : 02 - Le domaine : ta logique métier sans dépendances