Clean architecture en pratique : le guide pour ceux qui livrent

La clean architecture fait partie de ces idées que tout le monde cite et que peu appliquent avec jugement. Un camp l'ignore et vit dans la boue des dépendances ; l'autre l'applique en dogme et transforme une app CRUD en quarante fichiers de cérémonie. Chez Lasting Dynamics, nous l'utilisons depuis des années sur des systèmes en production et nous l'enseignons dans notre academy — ce guide est notre façon de l'expliquer en interne : la règle qui compte, les frontières qui comptent, et l'honnêteté de dire quand ne pas l'utiliser.

La seule règle qui compte vraiment

Retire les diagrammes en cercles concentriques et la clean architecture (Robert C. Martin, 2012 — avec l'architecture hexagonale/ports-and-adapters et l'onion architecture comme proches parentes) se réduit à une règle unique :

Les dépendances pointent vers l'intérieur : la logique métier ne sait rien des bases de données, des frameworks, de l'UI ni des services externes.

Tout le reste — entités, use cases, interface adapters — n'est que l'arrangement de cette règle en couches. L'idée centrale : le code qui décide ce que ton système fait n'importe pas ton ORM et ignore que HTTP existe. Les détails techniques dépendent des décisions métier, jamais l'inverse.

Pourquoi est-ce la bonne règle ? Parce que les détails changent sans cesse et que les règles métier durent. En dix ans de projets clients, nous avons changé d'ORM, de bases de données, de prestataires de paiement et de frameworks frontend — plusieurs fois. Les règles métier des clients ont survécu à tout ça. Une architecture qui couple les secondes aux premiers paie chaque changement, avec intérêts.

À quoi ça ressemble dans un vrai projet

Oublie les quatre cercles un instant ; dans un service typique, la substance c'est :

src/
  domain/          ← entités et règles métier. Zéro import externe.
  application/     ← use cases qui orchestrent le domaine. Ils DÉCLARENT
                     des interfaces pour ce dont ils ont besoin (repository, mailer…)
  infrastructure/  ← implémentations concrètes : Postgres, Stripe, SMTP.
                     Elles implémentent les interfaces d'application.
  interface/       ← handlers HTTP, CLI, UI : traduisent le monde extérieur
                     en appels de use cases.

Le mécanisme qui tient l'ensemble, c'est l'inversion de dépendance : un use case déclare interface ApplicationRepository { save(app): ... } et se moque de savoir si derrière il y a Postgres, un fichier ou un mock de test. L'implémentation concrète vit à l'extérieur et est injectée.

Les bénéfices sont immédiats et mesurables :

• Testabilité. Les use cases se testent en millisecondes, sans base de données ni réseau. Les suites rapides sont celles que les gens écrivent et lancent vraiment.
• Interchangeabilité. Changer d'ORM ou de prestataire touche infrastructure/, pas les règles.
• Intention lisible. application/submit-application.ts te dit ce que le système fait ; le code devient la documentation du métier.

Où les gens se trompent (dans les deux sens)

Erreur 1 — Le dogme des couches. Quatre couches, des mappers entre chacune, des DTO à chaque saut : pour un formulaire qui insère une ligne, c'est 300 lignes de cérémonie autour de 10 lignes de logique. La clean architecture protège la logique métier ; si la logique métier c'est « enregistre et affiche », il n'y a rien à protéger. Une app CRUD a le droit de rester une app CRUD.

Erreur 2 — Les fausses frontières. Des couches qui existent dans les noms de dossiers mais pas dans les dépendances : un « domain » qui importe l'ORM, un use case qui lit req.headers. C'est le pire des deux mondes — la cérémonie sans les bénéfices. Le test est mécanique : qu'importe ton domaine ? Si la réponse n'est pas « rien d'externe », tes frontières sont décoratives.

Erreur 3 — L'abstraction préventive partout. Des interfaces pour des choses qui ne changeront jamais, « au cas où ». Les abstractions coûtent de l'indirection ; place-les là où le changement est plausible (stockage, services externes, canaux d'I/O), pas partout par principe.

Erreur 4 — Confondre clean architecture et microservices. Ils sont orthogonaux. Un monolithe avec des frontières internes propres est une excellente architecture — et en général le bon point de départ. De bonnes frontières internes sont d'ailleurs précisément ce qui rend l'extraction d'un service possible plus tard, si jamais il le faut.

Quand ça paie, et quand c'est de trop

Ça vaut le coup quand : il y a de la vraie logique métier (règles, états, calculs, politiques), le système vivra des années, plus d'une personne y travaille, ou les détails techniques sont instables (plus fréquent qu'on ne l'admet).

C'est de trop quand : c'est un prototype, un outil interne jetable, un CRUD mince au-dessus d'une base — ou quand l'équipe n'a pas encore le jugement pour tracer les bonnes frontières, parce que de mauvaises frontières coûtent plus cher que pas de frontières.

La bonne pratique honnête : commence simple, mais garde la règle des dépendances comme boussole. Même dans un petit projet, garder la logique hors des contrôleurs HTTP ne coûte presque rien et laisse toutes les options futures ouvertes.

À l'ère des agents IA, ça compte plus, pas moins

Un détail devenu central : les outils d'agentic coding fonctionnent radicalement mieux sur les codebases aux frontières claires. Un agent qui change une règle métier dans un système au domaine isolé touche un fichier et ses tests ; dans du spaghetti, il en touche vingt et tu croises les doigts. Les frontières architecturales sont aussi la façon dont l'IA sait où mettre les mains — comme nous le disons dans notre guide Claude Code : tu décides la structure, l'IA la remplit.

Comment ça s'apprend vraiment

La clean architecture ne s'apprend pas dans des diagrammes — elle s'apprend en traçant des frontières sur de vrais systèmes et en écoutant quelqu'un de plus expérimenté t'expliquer exactement pourquoi la tienne est au mauvais endroit. C'est le format de la Lasting Dynamics Academy : l'architecture logicielle est au curriculum à côté des design patterns, des RDBMS et des tests, entraînée sur de vraies tâches avec une review hebdomadaire par un mentor. Gratuit, entièrement à distance, sélectif, et tous ceux qui terminent reçoivent une offre d'emploi. Si ce guide t'a semblé être de l'ingénierie saine, les candidatures sont ouvertes.

FAQ

Clean architecture et architecture hexagonale, c'est la même chose ? Des proches parentes : hexagonale (ports & adapters), onion et clean partagent l'idée centrale — le domaine au centre, les dépendances vers l'intérieur, les détails aux bords. Les différences tiennent à la terminologie et à la granularité des couches. Choisis-en une et sois cohérent ; débattre des noms est du temps perdu.

Est-ce que ça s'applique au code frontend ? Le principe, oui : sépare l'état et la logique métier des composants UI (qui sont autant un « détail » que la base de données). L'appareil complet des couches est en général de trop ; la règle des dépendances porte à elle seule l'essentiel de la valeur.

Par où commencer sur un codebase existant ? Par le prochain morceau de logique que tu dois toucher : extrais-le en fonction pure, donne-lui une interface pour ses dépendances, couvre-le de tests. La clean architecture sur un système legacy se gagne une frontière à la fois, pas en big bang.