Framework d'Architecture Propre
Une approche disciplinée pour structurer un logiciel afin que les règles métier restent indépendantes des frameworks, bases de données et mécanismes de livraison. Appliquez ces principes lors de la conception de l'architecture système, de la révision des limites de modules ou du conseil sur la gestion des dépendances.
Principe Fondamental
Les dépendances du code source doivent pointer vers l'intérieur — vers les politiques de plus haut niveau. Rien dans un cercle intérieur ne peut rien savoir d'un cercle extérieur. Cette règle unique produit des systèmes testables et indépendants des frameworks, de l'interface utilisateur, de la base de données et de toute agence externe. Les règles métier sont ce qui compte ; les bases de données, les frameworks web et les mécanismes de livraison sont des détails — lorsque les détails dépendent des politiques, vous pouvez reporter les décisions, échanger les implémentations et tester la logique métier en isolation.
Score
Objectif : 10/10. Comptez un point pour chacune des sept lignes du Diagnostic Rapide que l'architecture satisfait (0-7), puis reportez-vous à une bande de 0 à 10 : 6-7 satisfaites = 9-10 (la règle de dépendance tient, la logique métier est indépendante du framework et de la base de données) ; 4-5 = 6-8 (le noyau est testable mais certains détails fuient vers l'intérieur) ; 2-3 = 3-5 (le framework ou la persistance dicte la structure) ; 0-1 = 0-2 (aucune frontière — les règles métier vivent dans les contrôleurs et les modèles ORM). Signalez le score, les lignes de diagnostic échouées et l'inversion spécifique nécessaire pour corriger chacune.
1. Règle de Dépendance et Cercles Concentriques
Concept de base : Organisez l'architecture sous forme de cercles concentriques — les Entités (règles métier de l'entreprise) les plus à l'intérieur, puis les Cas d'Utilisation (règles métier de l'application), puis les Adaptateurs d'Interface, avec les Frameworks et Pilotes les plus à l'extérieur. Les dépendances du code source pointent toujours vers l'intérieur.
Pourquoi ça fonctionne : Lorsque les politiques de haut niveau ne dépendent pas des détails de bas niveau, vous pouvez changer la base de données, le framework web ou le style d'API sans toucher à la logique métier — le système devient résilient aux parties les plus volatiles de la pile.
Points clés :
- Les cercles intérieurs ne peuvent pas mentionner les noms des cercles extérieurs — pas de classes, fonctions, variables ou formats de données provenant de l'extérieur
- Les données traversant une frontière doivent être sous la forme la plus pratique pour le cercle intérieur, jamais dictées par l'extérieur
- L'Inversion de Dépendance (interfaces définies vers l'intérieur, implémentées vers l'extérieur) est le mécanisme qui applique la règle
- Le nombre de cercles n'est pas fixe — quatre est typique ; la règle reste la même
- Les frameworks sont des détails, pas l'architecture — ils appartiennent au cercle le plus extérieur
Applications dans le code :
| Contexte | Modèle | Exemple |
|---|---|---|
| Direction des couches | Les cercles intérieurs définissent les interfaces ; les extérieurs les implémentent | Interface UserRepository dans les Cas d'Utilisation ; PostgresUserRepository dans les Adaptateurs |
| Traversée des données | Les DTO traversent les frontières, pas les entités ORM | Le Cas d'Utilisation retourne un DTO UserResponse, pas un modèle ActiveRecord |
| Direction des dépendances | Les flèches d'import pointent toujours vers l'intérieur | Le Contrôleur importe le Cas d'Utilisation ; le Cas d'Utilisation n'importe jamais le Contrôleur |
Voir references/dependency-rule.md lorsqu'un import du cercle intérieur pointe vers l'extérieur et que vous avez besoin de la procédure de quatre étapes pour l'inversion de dépendance, des règles de traversée des données et de la démonstration du code des quatre cercles pour le corriger.
2. Entités et Cas d'Utilisation
Concept de base : Les Entités encapsulent les règles métier de l'entreprise — des règles qui existeraient même sans logiciel. Les Cas d'Utilisation contiennent des règles spécifiques à l'application qui orchestrent le flux de données vers et depuis les Entités.
Pourquoi ça fonctionne : Séparer ce que l'entreprise fait (Entités) de la manière dont l'application l'orchestre (Cas d'Utilisation) vous permet de réutiliser les Entités dans plusieurs applications et de modifier le comportement de l'application sans altérer les règles métier fondamentales.
Points clés :
- Les Entités ne sont pas des lignes de base de données — ce sont des objets ou des fonctions pures encapsulant des règles métier critiques
- Les Cas d'Utilisation acceptent des Modèles de Requête et retournent des Modèles de Réponse — jamais d'objets framework
- Chaque Cas d'Utilisation est une seule opération applicative (
CreateOrder,ApproveExpense) - Le modèle Interactor : une classe Cas d'Utilisation implémente une interface d'entrée et appelle une interface de sortie
- Les modifications d'un Cas d'Utilisation ne doivent jamais affecter une Entité ; les modifications d'une Entité peuvent se propager aux Cas d'Utilisation
Applications dans le code :
| Contexte | Modèle | Exemple |
|---|---|---|
| Conception d'Entité | Règles métier critiques, zéro dépendance framework | Order.calculateTotal() applique les règles fiscales ; ne sait rien de HTTP |
| Requête/Réponse | Structures de données simples traversent la frontière | CreateOrderRequest { items, customerId } — pas de modèles ORM |
| Responsabilité unique | Un Cas d'Utilisation par opération | PlaceOrder, CancelOrder, RefundOrder comme classes séparées |
| Interactor | Implémente le Port d'Entrée, appelle le Port de Sortie | PlaceOrderInteractor implements PlaceOrderInput |
Voir references/entities-use-cases.md lors de la conception d'un Interactor ou pour décider ce qui appartient à une Entité par rapport à un Cas d'Utilisation — traitement complet des Règles Métier d'Entreprise vs. d'Application avec des exemples de modèles de requête/réponse.
3. Adaptateurs d'Interface et Frameworks
Concept de base : Les Adaptateurs d'Interface convertissent les données entre la forme pratique pour les Cas d'Utilisation/Entités et la forme requise par les agences externes. Les Frameworks et Pilotes sont la couche la plus externe — du code de colle avec le monde extérieur.
Pourquoi ça fonctionne : Lorsque le framework web, l'ORM ou la file de messages est confiné aux cercles extérieurs, leur remplacement est un changement localisé. La base de données est un détail ; le web est un détail ; les détails doivent être des plugins de vos règles métier, pas le squelette de l'application.
Points clés :
- Les Contrôleurs traduisent HTTP en entrée de Cas d'Utilisation ; les Présentateurs traduisent la sortie du Cas d'Utilisation en modèles de vue
- Les Passerelles implémentent les interfaces de dépôt définies par les Cas d'Utilisation — le cercle intérieur définit le contrat, l'extérieur l'exécute
- Les règles métier ne savent jamais si les données vivent dans SQL, NoSQL ou des fichiers plats, ni que la livraison est HTTP
- Traitez les frameworks avec méfiance — ils veulent que vous vous couplez à eux ; gardez-les à distance
Applications dans le code :
| Contexte | Modèle | Exemple |
|---|---|---|
| Contrôleur | Mécanisme de livraison → entrée du Cas d'Utilisation | OrderController.create(req) construit CreateOrderRequest, appelle l'Interactor |
| Présentateur | Sortie du Cas d'Utilisation → modèle de vue | OrderPresenter.present(response) formate pour JSON/HTML |
| Passerelle | Interface de dépôt implémentée par base de données | SqlOrderRepository implements OrderRepository |
| Frontière de framework | Le framework appelle vers l'intérieur, jamais l'inverse | Le gestionnaire de route Express appelle le Contrôleur ; le Contrôleur n'importe jamais Express |
Voir references/adapters-frameworks.md lors du câblage des contrôleurs, présentateurs ou passerelles, ou pour argumenter que la base de données/le web est un détail — couvre l'architecture de plugin et comment confiner un framework aux bords.
4. Principes des Composants
Concept de base : Les composants sont les unités de déploiement. Trois principes de cohésion régissent ce qui se trouve à l'intérieur d'un composant ; trois principes de couplage régissent les relations entre composants.
Pourquoi ça fonctionne : Des composants mal composés créent des effets de ripple où un changement force le redéploiement de code non lié ; les principes maintiennent les changements localisés et les versions indépendantes.
Points clés :
- REP (Équivalence Réutilisation/Version) : les classes d'un composant doivent être versionnables et libérables comme une unité
- CCP (Fermeture Commune) : les classes qui changent pour la même raison au même moment vont ensemble — SRP pour les composants
- CRP (Réutilisation Commune) : ne forcez pas les utilisateurs à dépendre de classes qu'ils n'utilisent pas
- ADP (Dépendances Acycliques) : le graphe de composants ne doit pas contenir de cycles — brisez-les avec DIP ou un nouveau composant
- SDP (Dépendances Stables) : dépendez dans la direction de la stabilité
- SAP (Abstractions Stables) : les composants stables doivent être abstraits ; les instables, concrets
Applications dans le code :
| Contexte | Modèle | Exemple |
|---|---|---|
| Regroupement de composants | Regrouper les classes qui changent ensemble (CCP) | Tous les Cas d'Utilisation liés aux commandes dans un composant |
| Briser les cycles | Appliquer DIP pour inverser une arête de dépendance | Extraire une interface dans un nouveau composant pour briser le cycle |
| Métriques de stabilité | Instabilité I = Ce / (Ca + Ce) | Beaucoup de dépendances entrantes, aucune sortante → I proche de 0 (stable) |
Voir references/component-principles.md lors du regroupement de classes en composants déployables ou pour briser un cycle de dépendance — chacun de REP, CCP, CRP, ADP, SDP, SAP travaillé avec la métrique d'instabilité.
5. Principes SOLID
Concept de base : Cinq principes au niveau classe et module — Responsabilité Unique, Ouvert-Fermé, Substitution de Liskov, Ségrégation d'Interface, Inversion de Dépendance — les blocs de construction de niveau intermédiaire qui rendent la Règle de Dépendance possible.
Pourquoi ça fonctionne : Chaque principe aborde une manière spécifique dont les dépendances dévient, empêchant la rigidité, la fragilité et l'immobilité qui transforment les bases de code en cauchemars hérités.
Points clés :
- SRP : un module a une seule raison de changer — il sert un seul acteur (pas "fait une seule chose")
- OCP : étendez le comportement en ajoutant du nouveau code, pas en modifiant le code existant — modèles de stratégie et de plugin
- LSP : les sous-types doivent être utilisables via l'interface de base sans que le client le sache — violé par des exceptions inattendues ou des méthodes ignorées
- ISP : les clients ne doivent pas dépendre de méthodes qu'ils n'utilisent pas — les interfaces trop larges créent un couplage inutile
- DIP : les modules de haut niveau et les modules de bas niveau dépendent tous d'abstractions définies par le module de haut niveau
Applications dans le code :
| Contexte | Modèle | Exemple |
|---|---|---|
| Violation SRP | Classe servant plusieurs acteurs | Employee gère la paie (CFO), le reporting (COO), la persistance (CTO) |
| OCP via stratégie | Nouveau comportement via de nouvelles classes | Ajouter ExpressShipping implémentant ShippingStrategy ; Order inchangé |
| Violation LSP | Sous-type modifiant le comportement attendu | Square extends Rectangle brise le contrat setWidth()/setHeight() |
| Application ISP | Diviser les interfaces trop larges en interfaces de rôle | Printer, Scanner, Fax au lieu d'un seul MultiFunctionDevice |
| Câblage DIP | Le haut niveau définit l'interface ; le bas niveau implémente | OrderService dépend de PaymentGateway, pas de StripeClient |
Voir references/solid-principles.md lors de l'application de SRP/OCP/LSP/ISP/DIP à une classe spécifique ou du diagnostic d'une violation — chaque principe travaillé avec des exemples de code et l'odeur de code qu'il prévient.
6. Frontières et Anatomie des Frontières
Concept de base : Une frontière est une ligne entre ce qui compte et ce qui est détail, implémentée via le polymorphisme : les dépendances traversent en pointant vers l'intérieur tandis que le flux de contrôle peut traverser dans les deux sens.
Pourquoi ça fonctionne : Chaque frontière achète l'option de reporter une décision ou d'échanger une implémentation ; le placement stratégique des frontières détermine si un système est un plaisir ou une douleur à maintenir sur des années.
Points clés :
- Les frontières complètes utilisent des interfaces réciproques des deux côtés ; les frontières partielles utilisent une stratégie ou une façade plus simple
- Le modèle Objet Humble : divisez le code de frontière en une partie difficile à tester (près de la frontière) et une partie facile à tester (la logique)
- Les services ne sont pas automatiquement des frontières architecturales — un microservice avec un modèle de données partagé volumineux est un monolithe avec des appels réseau
- Les tests sont le composant le plus isolé : ils dépendent vers l'intérieur, rien ne dépend d'eux
- Les frontières prématurées sont coûteuses, mais les frontières manquantes aussi — tracez-les aux points de volatilité probable
Applications dans le code :
| Contexte | Modèle | Exemple |
|---|---|---|
| Frontière complète vs. partielle | Ports réciproques, ou une stratégie seule | Le Cas d'Utilisation définit PlaceOrderInput/PlaceOrderOutput ; les cas plus simples prennent un ShippingStrategy |
| Objet Humble | Séparer la logique testable de l'infrastructure | PresenterLogic (testable) produit ViewModel ; View (humble) le rend |
| Main comme plugin | Racine de composition assemble le système | main() câble toutes les implémentations concrètes et démarre l'application |
Voir references/boundaries.md lors de la décision de l'endroit où tracer une frontière, du choix entre complète et partielle, ou de l'application du modèle Objet Humble — couvre également les services comme frontières, les frontières de test et Main comme le plugin ultime.
Erreurs Courantes
| Erreur | Pourquoi Ça Échoue | Correction |
|---|---|---|
| ORM fuyant dans la logique métier | Les entités se couplent au schéma ; les changements de base de données réécrivent les règles métier | Séparer les entités domaine des modèles de persistance ; mapper au niveau de l'adaptateur |
| Règles métier dans les contrôleurs | Non testables sans HTTP ; dupliquées entre les points de terminaison | Déplacer la logique dans les Interactors de Cas d'Utilisation ; les contrôleurs ne font que traduire et déléguer |
| Architecture d'abord framework | Le framework dicte la structure ; le remplacer signifie une réécriture | Traiter le framework comme un plugin ; structurer le code par capacité métier |
| Dépendances circulaires entre composants | Les changements se propagent de manière imprévisible ; pas de versions indépendantes | Appliquer DIP ou extraire un composant d'abstraction partagé |
| Un seul énorme Cas d'Utilisation par fonctionnalité | Des orchestrateurs boursouflés de mille lignes | Diviser en Cas d'Utilisation ciblés à opération unique |
| Sauter les frontières "parce que c'est simple" | Le couplage s'accumule silencieusement jusqu'à ce que le coût soit énorme | Tracer les frontières de manière proactive aux points de volatilité probable |
| Les microservices comme bonne architecture automatique | Un monolithe distribué est pire qu'un monolithe propre | Appliquer la Règle de Dépendance à l'intérieur et entre les services ; les services sont des frontières de déploiement, pas architecturales |
Diagnostic Rapide
| Question | Si Non | Action |
|---|---|---|
| Pouvez-vous tester les règles métier sans base de données, serveur web ou framework ? | Les règles sont couplées à l'infrastructure | Extraire les entités et les cas d'utilisation derrière des interfaces ; simuler les couches externes |
| Toutes les dépendances du code source pointent-elles vers l'intérieur ? | Il y a une inversion de dépendance | Appliquer le principe d'inversion de dépendance (DIP) pour inverser la direction |
| Les entités sont-elles libres de toute dépendance framework ? | Les entités importent des objets ORM ou framework | Déplacer les dépendances framework vers l'extérieur ; les entités ne doivent import\er que des types du langage standard |
| Les cas d'utilisation acceptent-ils et retournent-ils des structures de données simples plutôt que des modèles framework ? | Les cas d'utilisation reçoivent/renvoient des objets framework ou ORM | Définir des modèles de requête et de réponse simples pour chaque cas d'utilisation |
| Les contrôleurs se contentent-ils de traduire et de déléguer, sans logique métier ? | Les contrôleurs contiennent des règles métier ou d'importantes transformations | Extraire la logique métier dans des cas d'utilisation ; les contrôleurs ne font que traduire et transmettre |
| Le graphique des dépendances entre composants est-il exempt de cycles ? | Une modification dans un composant en affecte un autre de manière imprévisible | Casser le cycle en extrayant une interface ou en divisant le composant |
| Les implémentations de passerelles (par exemple, les dépôts SQL) résident-elles à l'extérieur de la logique métier ? | Les requêtes de base de données sont dispersées dans les cas d'utilisation | Définir les interfaces de dépôt dans les cas d'utilisation ; implémenter les passerelles dans la couche d'adaptateur |