Que fait Vers l'Architecture Hexagonale ?
Analysez un dépôt existant en profondeur et concevez un plan de refactoring atomique et par phases pour le migrer vers l'Architecture Hexagonale (Ports et Adaptateurs) sans casser aucun contrat externe ni comportement observable.
Répondez dans la même langue que la demande de l'utilisateur. Opérez strictement en Mode Plan : inspectez d'abord la base de code et livrez le plan complet avant de modifier un fichier.
Quand Utiliser
- L'utilisateur demande de migrer ou refactoriser un projet existant vers l'Architecture Hexagonale ou les Ports et Adaptateurs.
- L'utilisateur souhaite découpler la logique métier des frameworks web, ORM, bases de données, courtiers de messages ou SDK externes.
- L'utilisateur demande un plan de refactoring architectural sûr, progressif et sans changement cassant.
Principes Fondamentaux
- Zéro Changement Cassant (Règle d'Or) : Préservez tous les contrats externes existants. Les routes, méthodes HTTP, codes de statut, schémas de payloads requête/réponse, en-têtes, formats d'erreur, indicateurs CLI ou formes de messages de files d'attente doivent rester identiques.
- Caractérisation Avant Refactoring : Ne déplacez ni ne supprimez de logique de production tant que des tests automatisés de contrat/caractérisation ne couvrent pas les points d'entrée existants.
- Règle de Dépendance Stricte : Les dépendances du code source doivent toujours pointer vers l'intérieur, vers
domain. La couche domaine doit avoir zéro import de frameworks web, pilotes de base de données, ORM, bibliothèques de sérialisation ou SDK externes. - Adaptation Idiomatique de la Pile : Adaptez les chemins de répertoires, les conventions de nommage, les constructs de typage et les exécuteurs de tests à la langue et à l'écosystème détectés du projet (par exemple, TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust).
Flux de Travail
Étape 1 : Découverte de la Base de Code
Scannez le dépôt avant de proposer une arborescence de dossiers ou des étapes de migration :
- Pile et Outillage : Inspectez les manifestes de dépendances, les configurations du compilateur/linter et les exécuteurs de tests pour identifier le langage, le framework, la bibliothèque de validation, l'ORM/constructeur de requêtes et l'approche d'injection de dépendances.
- Points d'Entrée et Contrats : Inventoriez tous les points d'entrée moteurs (routes HTTP, résolveurs GraphQL, services gRPC, consommateurs de messages, tâches cron), leurs schémas de validation, middlewares/intercepteurs et gestionnaires d'erreurs globaux.
- Dépendances Externes : Inventoriez tous les effets secondaires moteurs (bases de données, caches, clients HTTP/RPC, files d'attente, stockage de fichiers, configuration d'environnement, journaux).
- Flux d'Exécution Actuel : Tracez comment les données circulent actuellement du point d'entrée à la persistance/appel externe et retour, en notant où les règles métier sont mélangées avec les détails de transport ou de persistance.
Étape 2 : Conception de la Structure Hexagonale Cible
Mappez les trois couches concentriques vers la racine source idiomatique du projet (par exemple, src/ en TypeScript/Rust, internal/ en Go, src/main/<lang>/ en JVM, ou le répertoire principal du package en Python) :
domain/(Cœur Métier Pur - zéro dépendance framework ou E/S) :entities/etvalue-objects/: Modèles du domaine encapsulant les règles métier, invariants et auto-validation.ports/in/: Interfaces des ports moteurs définissant les contrats des cas d'utilisation.ports/out/: Interfaces des ports entraînés définissant les contrats des dépôts, services externes, éditeurs d'événements etLoggerPort.errors/: Exceptions du domaine sémantiques (par exemple,ResourceNotFoundError,DomainValidationError,ConflictError).
application/(Orchestration des Cas d'Utilisation) :use-cases/: Implémentations deports/incoordonnant les entités du domaine etports/out.dtos/: Structures de données immuables d'entrée et de sortie découplées des payloads de transport et des entités de persistance.
infrastructure/(Détails Techniques et Adaptateurs) :adapters/in/: Adaptateurs moteurs (contrôleurs/gestionnaires HTTP, gestionnaires de consommateurs), schémas de validation de transport, mappeurs (TransportInput -> InputDTOetOutputDTO -> TransportOutput), et un mappeur d'erreurs global traduisantdomain/errorsen réponses d'erreur héritées exactes.adapters/out/: Implémentations concrètes deports/out(dépôts de base de données, clients HTTP, courtiers) avec des mappeurs de persistance/externes afin que les modèles ORM ou les types SDK ne fuient jamais dansdomain/.config/: Chargement strict et validation au démarrage des variables d'environnement et des paramètres d'exécution.di/(Racine de Composition) : Câblage explicite des adaptateurs entraînés, des cas d'utilisation et des adaptateurs moteurs via injection par constructeur, en évitant les singletons cachés ou les localisateurs de services.
- Séparation du Démarrage : Séparez la construction de l'application (
buildApp/ fonction factory pour les tests d'intégration isolés) du démarrage du serveur/processus (main/listen).
Étape 3 : Appliquer les Normes d'Ingénierie dans le Plan
Assurez-vous que chaque phase du plan applique :
- Typage Fort et Immuabilité : Interdisez les échappatoires non typées (tels que
anyou les cartes brutes non typées là où des structures typées s'appliquent) et privilégiez les DTO immuables et les Objets Valeur (readonly, dataclasses figés, enregistrements, types valeur). - SOLID et Injection par Constructeur : Gardez les classes et fonctions petites avec des responsabilités uniques ; injectez les interfaces via les constructeurs.
- Observabilité Sans Couplage : Préservez la journalisation structurée et le contexte de corrélation des requêtes tout en gardant
domain/etapplication/découplés des bibliothèques de journalisation spécifiques viaLoggerPort. - Tests Pyramidaux :
- Tests unitaires pour
domain/(invariants purs) etapplication/(en simulantports/out). - Tests d'intégration/contrats vérifiant les adaptateurs moteurs réels contre le câblage de l'application en utilisant le client de test en mémoire natif de la pile (par exemple,
fastify.inject, Supertest, FastAPITestClient, SpringMockMvc, ou Gohttptest).
- Tests unitaires pour
Format de Sortie (Mode Plan)
Livrez la réponse structurée dans ces sections exactes :
- Diagnostic de l'Architecture Actuelle : Inventaire concis de la pile détectée, des points d'entrée/endpoints, des dépendances externes et des principaux points de couplage.
- Arborescence de Répertoires Cible : Structure de dossiers proposée complète en utilisant les vrais noms de modules et fonctionnalités trouvés dans le dépôt.
- Plan d'Exécution par Phases : Cinq phases atomiques et vérifiables :
- Phase 1 - Tests de Caractérisation et Échafaudage de Base : Créez des tests de contrat verrouillant le comportement actuel, créez les dossiers cibles, le chargeur de configuration et la Racine de Composition (
di/). - Phase 2 - Extraction du Domaine : Extrayez les entités, objets valeur, erreurs du domaine et interfaces
ports/in+ports/outavec tests unitaires. - Phase 3 - Cas d'Utilisation de l'Application et Adaptateurs Entraînés : Implémentez les cas d'utilisation, DTO, dépôts/clients
adapters/outet mappeurs de persistance. - Phase 4 - Adaptateurs Moteurs et Traduction d'Erreurs : Refactorisez les contrôleurs/gestionnaires pour déléguer aux cas d'utilisation via des mappeurs, câblez la traduction d'erreurs globale et connectez
di/. - Phase 5 - Nettoyage des Anciens Éléments et Vérification Finale : Supprimez les fichiers obsolètes, exécutez la suite de tests complète, le linter et le vérificateur de types, et vérifiez l'absence de dérive de contrat.
- Phase 1 - Tests de Caractérisation et Échafaudage de Base : Créez des tests de contrat verrouillant le comportement actuel, créez les dossiers cibles, le chargeur de configuration et la Racine de Composition (
- Points de Validation : Commande ou vérification explicite à la fin de chaque phase prouvant que rien n'a été cassé avant de passer à la phase suivante.
Pièges à Éviter
- Ne modifiez pas le code prématurément : À moins que l'utilisateur ne demande explicitement de commencer à exécuter la Phase 1 immédiatement, sortez d'abord uniquement le plan afin qu'il puisse examiner les limites des modules.
- Évitez la sur-abstraction sur les CRUD triviaux : Séparez toujours proprement
domain,applicationetinfrastructure, mais gardez les cas d'utilisation de passage concis plutôt que d'inventer une complexité métier artificielle. - Respectez les bizarreries héritées : Si un endpoint existant renvoie un code de statut non standard ou un nom de champ d'erreur, documentez-le dans la Phase 1 et préservez-le dans le mappeur d'erreurs
infrastructureafin que les clients existants ne soient pas cassés.