00 - Pourquoi ton code merite une vraie architecture
Ce que tu vas apprendre
- Pourquoi le couplage au framework est un piège
- Ce qu'est l'architecture hexagonale (ports and adapters)
- Ce que cette serie couvre et comment la lire
Prerequisites
Aucun. C'est le point de depart.
L'anecdote qui fait mal
Il y a deux ans, j'ai récupéré un projet Node.js/Express avec Sequelize comme ORM. Le client voulait migrer vers PostgreSQL natif (via pg) parce que Sequelize generait des requêtes catastrophiques sur les grosses tables. Mission simple en apparence.
Sauf que les appels Sequelize etaient partout. Dans les controllers, dans les middlewares, dans des fichiers utilitaires, dans les crons. La logique métier etait melee aux Model.findAll() et aux req.body. Changer l'ORM signifiait retoucher 80% du code. Trois semaines pour ce qui aurait du prendre trois jours.
Ce projet n'avait pas un problème de qualité de code. Il avait un problème d'architecture. Ou plutot, une absence totale d'architecture.
Le code spaghetti, version 2026
On ne parle plus de code spaghetti comme dans les annees 2000. Aujourd'hui, le spaghetti est plus subtil. Ton code est bien formate, tes fonctions font moins de 30 lignes, tu as des tests. Mais ta logique métier est collee a Express. Tes regles de validation vivent dans un middleware. Ton calcul de prix appelle directement Stripe.
Ce couplage invisible, c'est ce qui te rattrape au bout de 6 mois. Tu veux ajouter un endpoint GraphQL a cote de ton API REST ? Tu dupliques la logique. Tu veux tester un calcul métier ? Tu dois mocker la base de donnees, le serveur HTTP, et deux API externes. Tu veux changer de provider de paiement ? Bonne chance.
L'architecture hexagonale, c'est quoi ?
En 2005, Alistair Cockburn a formalise une idee simple : la logique métier ne devrait pas savoir que le monde extérieur existe. Pas de import express, pas de import prisma, pas de fetch("https://api.stripe.com") dans ton code métier. Rien.
Il a appele ca l'architecture hexagonale, ou "ports and adapters" (ports et adaptateurs). Le nom "hexagonale" vient du schema qu'il a dessine, un hexagone au centre qui represente le domaine. Mais la forme n'a rien de magique. Ca pourrait etre un cercle, un carre, un blob. L'idee, c'est la séparation.
La regle tient en une phrase : le domaine ne depend de rien d'extérieur. C'est le monde extérieur qui s'adapte au domaine, pas l'inverse.
Non, c'est pas du bla-bla academique
Je sais ce que tu penses. "Encore un pattern d'architecte en tour d'ivoire qui n'a jamais livre un projet en prod." J'ai pense la meme chose la première fois. Et puis j'ai essaye.
Le vrai gain, c'est la testabilité. Quand ton domaine ne depend de rien, tu peux le tester avec zero infrastructure. Pas de Docker, pas de base de donnees de test, pas de mock de 50 lignes. Des tests qui tournent en millisecondes et qui verifient la logique métier réelle.
L'autre gain, c'est la flexibilité. Quand ton ORM change, tu reecris un adaptateur. Quand tu ajoutes une CLI en plus de l'API, tu branches un nouvel adaptateur. Le domaine, lui, ne bouge pas.
Sur paltemps.fr, on utilise ce type de séparation des responsabilités sur les projets backend qui ont une vraie logique métier. Ca change la donne.
Ce que couvre cette serie
| # | Article | Contenu |
|---|---|---|
| 01 | Le concept | Ports, adaptateurs, domaine au centre |
| 02 | Le domaine | Logique métier sans dépendances |
| 03 | Les ports | Interfaces TypeScript du domaine |
| 04 | Les adaptateurs | Brancher le monde réel |
| 05 | Les tests | Le vrai gain de l'hexa |
| 06 | Projet complet | API de commandes en TypeScript |
| 07 | Quand utiliser | Et quand ne pas utiliser |
Les exemples sont en TypeScript. Si tu viens de la serie Domaines et cycles de vie, tu retrouveras des concepts familiers comme les entités et les regles métier. L'architecture hexagonale, c'est la couche au-dessus : comment organiser tout ca dans un projet réel.
Comment lire cette serie
Lis dans l'ordre. Chaque article s'appuie sur le précédent. Le code TypeScript est progressif : on construit les memes exemples d'un article a l'autre.
Résumé
- Le couplage framework/métier est le problème numero un des projets backend
- L'architecture hexagonale (Alistair Cockburn, 2005) impose une regle simple : le domaine ne depend de rien
- C'est un outil pratique, pas une theorie academique
- Cette serie couvre le concept, l'implementation en TypeScript, et les cas d'usage réels
Article suivant : 01 - Le concept : ports, adaptateurs et le domaine au centre