La Clean Architecture, popularisée par Robert "Uncle Bob" Martin, est une approche architecturale qui vise à créer des systèmes logiciels maintenables, testables et indépendants des frameworks. Voici un guide pratique pour une implémentation réussie.
Votre logique métier ne doit dépendre d'aucun framework spécifique. Les frameworks sont des détails d'implémentation, pas le cœur de votre application.
❌ Problème courant : La logique métier est mélangée avec les controllers web (Express, Fastify, etc.). La validation, les règles métier et la gestion HTTP sont entrelacées.
✅ Solution : Extraire la logique métier dans des Use Cases indépendants. Les controllers deviennent de simples adaptateurs qui traduisent les requêtes HTTP en commandes métier.
Vos use cases ne doivent pas connaître les détails de persistance. La base de données est un détail d'implémentation.
Principe clé : Définir les interfaces de persistance dans la couche domaine, pas dans l'infrastructure. Le Use Case dépend d'une abstraction (UserRepository), l'implémentation concrète (Postgres, MongoDB) est injectée.
L'interface définit les opérations métier (save, findByEmail) sans détails d'implémentation SQL ou NoSQL. Cela permet de changer de base de données, d'ajouter un cache, ou de tester avec des mocks sans toucher à la logique métier.
┌─────────────────────────────────────┐
│ Frameworks & Drivers │ ← Web, DB, External APIs
├─────────────────────────────────────┤
│ Interface Adapters │ ← Controllers, Presenters, Gateways
├─────────────────────────────────────┤
│ Application Logic │ ← Use Cases, Interactors
├─────────────────────────────────────┤
│ Entities │ ← Business Rules, Domain Models
└─────────────────────────────────────┘
Couche Entities : Les règles métier fondamentales. Validation, invariants, comportements du domaine.
Couche Use Cases : Orchestration des entités et des dépendances. Logique applicative spécifique (créer un utilisateur, passer une commande).
Couche Adapters : Traduction entre le monde extérieur et la logique métier. Les controllers HTTP, repositories, services externes sont ici.
Exemple de flux : HTTP Request → Controller (adapter) → Use Case (orchestration) → Entity (règles métier) → Repository (adapter)
Règle d'or : Les dépendances pointent toujours vers l'intérieur. Le domaine ne dépend de rien. Les Use Cases dépendent du domaine. L'infrastructure dépend des Use Cases.
Composition Root : Un seul endroit (souvent au démarrage de l'app) où toutes les dépendances sont assemblées. Les Use Cases reçoivent leurs dépendances par injection, jamais par instanciation directe.
Cela permet de remplacer n'importe quelle implémentation (DB, email, cache) sans modifier le code métier.
Avantage majeur : Tester la logique métier sans démarrer de serveur, sans base de données, sans services externes.
Chaque Use Case est testé isolément avec des mocks de ses dépendances. Les tests sont :
Les tests d'intégration (avec vraie DB) restent utiles mais en nombre limité. L'essentiel de la couverture vient des tests unitaires des Use Cases.
Pourquoi : Découpler la signature du Use Case des détails du transport (HTTP, gRPC, CLI).
Chaque Use Case définit son propre contrat d'entrée/sortie indépendant du framework. Les adapters (controllers) traduisent entre le format externe (JSON HTTP) et le format interne (Request/Response objects).
Avantages :
Concept : Encapsuler les valeurs primitives avec leurs règles de validation. Un Email n'est pas juste un string, c'est un concept métier avec des contraintes.
Un Value Object expose une factory method statique (Email.create()) qui valide l'entrée. Le constructeur est privé pour forcer la validation.
Bénéfices :
string là où un Email validé est attendu❌ ANTI-PATTERN : Object.freeze
N'utilisez JAMAIS Object.freeze() en TypeScript. C'est un contrôle runtime redondant avec le système de types.
Problèmes :
✅ BONNE PRATIQUE : Types readonly TypeScript
Déclarez vos types avec readonly : { readonly id: string }. TypeScript garantit l'immutabilité à la compilation.
Avantages :
Règle d'or : Utiliser exclusivement readonly TypeScript. Object.freeze est un anti-pattern.
Avant : Tout dans le controller - validation, logique métier, persistance, services externes sont mélangés. Impossible à tester sans base de données.
Après :
Gain immédiat : Le Use Case devient testable en isolation avec des mocks. Le controller devient un simple adaptateur thin qui ne contient aucune logique métier.
La Clean Architecture n'est pas une solution miracle, mais un ensemble de principes qui, bien appliqués, créent des systèmes robustes et évolutifs. La clé du succès réside dans :
L'investissement initial en complexité est largement compensé par la facilité de maintenance et d'évolution à long terme.
Appliquer le pattern ports et adapters dans les systèmes distribués. Comment structurer les microservices pour la testabilité, la maintenabilité et la clarté du domaine.
Comment identifier, concevoir et implémenter des bounded contexts efficaces dans des domaines complexes. Patterns stratégiques, techniques de context mapping et exemples concrets.