Zu Hexagonaler Architektur
Analysiere ein vorhandenes Repository gründlich und entwerfe einen atomaren, schrittweisen Refactoring-Plan, um es auf Hexagonale Architektur (Ports and Adapters) zu migrieren, ohne externe Verträge oder beobachtbares Verhalten zu brechen.
Antworte in derselben Sprache wie die Anfrage des Benutzers. Arbeite streng im Planmodus: Untersuche zuerst die Codebasis und liefere den vollständigen Plan, bevor du Dateien änderst.
Wann verwenden
- Der Benutzer bittet um Migration oder Refactoring eines bestehenden Projekts in Hexagonale Architektur oder Ports and Adapters.
- Der Benutzer möchte die Geschäftslogik von Web-Frameworks, ORMs, Datenbanken, Message Brokern oder externen SDKs entkoppeln.
- Der Benutzer wünscht einen sicheren, inkrementellen Architektur-Refactoring-Plan ohne Breaking Changes.
Kernprinzipien
- Null Breaking Changes (Goldene Regel): Jeder bestehende externe Vertrag muss erhalten bleiben. Routen, HTTP-Methoden, Statuscodes, Request/Response-Payload-Schemata, Header, Fehlerformate, CLI-Optionen oder Nachrichtenformate von Queues müssen identisch bleiben.
- Charakterisierung vor Refactoring: Verschiebe oder lösche keine Produktionslogik, bis automatisierte Vertrags-/Charakterisierungstests bestehende Endpunkte oder Einstiegspunkte abdecken.
- Strenge Abhängigkeitsregel: Quellcode-Abhängigkeiten müssen stets nach innen auf
domainzeigen. Die Domain-Schicht darf keine Importe von Web-Frameworks, Datenbanktreibern, ORMs, Serialisierungsbibliotheken oder externen SDKs haben. - Stack-idiomatische Anpassung: Passe Verzeichnispfade, Namenskonventionen, Typkonstrukte und Test-Runner an die erkannte Sprache und das Ökosystem des Projekts an (z.B. TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust).
Arbeitsablauf
Schritt 1: Codebase-Erkundung
Scanne das Repository, bevor du einen Ordnerbaum oder Migrationsschritte vorschlägst:
- Stack und Tooling: Überprüfe Abhängigkeits-Manifeste, Compiler/Linter-Konfigurationen und Test-Runner, um die Sprache, das Framework, die Validierungsbibliothek, den ORM/Query Builder und den DI-Ansatz zu identifizieren.
- Einstiegspunkte und Verträge: Erfasse alle treibenden Einstiegspunkte (HTTP-Routen, GraphQL-Resolver, gRPC-Dienste, Message-Consumer, Cron-Jobs), deren Validierungsschemata, Middleware/Interceptor und globale Fehlerbehandler.
- Externe Abhängigkeiten: Erfasse alle getriebenen Seiteneffekte (Datenbanken, Caches, HTTP/RPC-Clients, Queues, Dateispeicher, Umgebungskonfiguration, Logger).
- Aktueller Ausführungsfluss: Verfolge, wie Daten derzeit vom Einstiegspunkt zur Persistenz/externen Aufruf und zurück fließen, und notiere, wo Geschäftsregeln mit Transport- oder Persistenzdetails vermischt sind.
Schritt 2: Entwurf des hexagonalen Zielaufbaus
Ordne die drei konzentrischen Schichten dem idiomatischen Quellstamm des Projekts zu (z.B. src/ in TypeScript/Rust, internal/ in Go, src/main/<lang>/ in JVM oder das Hauptpaketverzeichnis in Python):
domain/(Reiner Geschäftskern - null Framework- oder I/O-Abhängigkeiten):entities/undvalue-objects/: Domänenmodelle, die Geschäftsregeln, Invarianten und Selbstvalidierung kapseln.ports/in/: Treibende Port-Schnittstellen, die Use-Case-Verträge definieren.ports/out/: Getriebene Port-Schnittstellen, die Verträge für Repository, externen Dienst, Event-Publisher undLoggerPortdefinieren.errors/: Semantische Domänenausnahmen (z.B.ResourceNotFoundError,DomainValidationError,ConflictError).
application/(Use-Case-Orchestrierung):use-cases/: Implementierungen vonports/in, die Domänenentitäten undports/outkoordinieren.dtos/: Unveränderliche Eingabe- und Ausgabedatenstrukturen, die von Transport-Payloads und Persistenzentitäten entkoppelt sind.
infrastructure/(Technische Details und Adapter):adapters/in/: Treibende Adapter (HTTP-Controller/Handler, Consumer-Handler), Transportvalidierungsschemata, Mapper (TransportInput -> InputDTOundOutputDTO -> TransportOutput) und ein globaler Fehlermapper, derdomain/errorsin die exakten Legacy-Fehlerantworten übersetzt.adapters/out/: Konkrete Implementierungen vonports/out(Datenbank-Repositories, HTTP-Clients, Broker) mit Persistenz-/Externen-Mappern, sodass ORM-Modelle oder SDK-Typen niemals indomain/eindringen.config/: Strikte Laden und Startvalidierung von Umgebungsvariablen und Laufzeiteinstellungen.di/(Composition Root): Explizites Verkabeln von getriebenen Adaptern, Use Cases und treibenden Adaptern via Konstruktorinjektion, unter Vermeidung von versteckten Singletons oder Service Locators.
- Bootstrap-Trennung: Trenne die Anwendungskonstruktion (
buildApp/ Factory-Funktion für isolierte Integrationstests) vom Server-/Prozess-Start (main/listen).
Schritt 3: Durchsetzung von Engineering-Standards im Plan
Stelle sicher, dass jede Phase im Plan Folgendes durchsetzt:
- Starke Typisierung und Unveränderlichkeit: Verbiete untypisierte Entweichungen (wie
anyoder rohe untypisierte Maps, wo typisierte Strukturen anwendbar sind) und bevorzuge unveränderliche DTOs und Value Objects (readonly, eingefrorene Dataclasses, Records, Value Types). - SOLID und Konstruktorinjektion: Halte Klassen und Funktionen klein mit einzelnen Verantwortlichkeiten; injiziere Schnittstellen über Konstruktoren.
- Beobachtbarkeit ohne Kopplung: Bewahre strukturiertes Logging und Request-Correlation-Kontext, während
domain/undapplication/überLoggerPortvon spezifischen Logging-Bibliotheken entkoppelt bleiben. - Pyramiden-Testing:
- Unit-Tests für
domain/(reine Invarianten) undapplication/(Mocking vonports/out). - Integrations-/Vertragstests, die reale treibende Adapter gegen die Anwendungsverkabelung mit dem nativen In-Memory-Test-Client des Stacks verifizieren (z.B.
fastify.inject, Supertest, FastAPITestClient, SpringMockMvcoder Gohttptest).
- Unit-Tests für
Ausgabeformat (Planmodus)
Liefere die Antwort strukturiert in diese genauen Abschnitte:
- Aktuelle Architektur-Diagnose: Prägnante Inventur des erkannten Stacks, der Einstiegspunkte/Endpunkte, externen Abhängigkeiten und der wichtigsten Kopplungshotspots.
- Zielverzeichnisbaum: Vollständige vorgeschlagene Ordnerstruktur unter Verwendung der tatsächlichen Modul- und Feature-Namen aus dem Repository.
- Phasenweiser Ausführungsplan: Fünf atomare, verifizierbare Phasen:
- Phase 1 - Charakterisierungstests und Basisgerüst: Erstelle Vertragstests, die das aktuelle Verhalten einfrieren, erstelle Zielordner, Konfigurationslader und Composition Root (
di/). - Phase 2 - Domänenextraktion: Extrahiere Entitäten, Value Objects, Domänenfehler und
ports/in+ports/out-Schnittstellen mit Unit-Tests. - Phase 3 - Anwendungsfälle und getriebene Adapter: Implementiere Use Cases, DTOs,
adapters/outRepositories/Clients und Persistenz-Mapper. - Phase 4 - Treibende Adapter und Fehlerübersetzung: Refaktoriere Controller/Handler, um über Mapper an Use Cases zu delegieren, verdrahte globale Fehlerübersetzung und verbinde
di/. - Phase 5 - Legacy-Bereinigung und finale Verifikation: Entferne obsolet gewordene Dateien, führe die vollständige Test-Suite, den Linter und den Typchecker aus und verifiziere null Vertragsabweichungen.
- Phase 1 - Charakterisierungstests und Basisgerüst: Erstelle Vertragstests, die das aktuelle Verhalten einfrieren, erstelle Zielordner, Konfigurationslader und Composition Root (
- Validierungs-Checkpoints: Am Ende jeder Phase expliziter Befehl oder Prüfung, die belegt, dass nichts gebrochen ist, bevor zur nächsten Phase übergegangen wird.
Stolperfallen
- Code nicht vorzeitig bearbeiten: Sofern der Benutzer nicht explizit bittet, sofort mit Phase 1 zu beginnen, gib zunächst nur den Plan aus, damit er die Modulgrenzen überprüfen kann.
- Über-Abstraktion bei trivialem CRUD vermeiden: Trenne dennoch sauber in
domain,applicationundinfrastructure, aber halte Durchgangs-Use-Cases prägnant, anstatt künstliche Domänenkomplexität zu erfinden. - Legacy-Eigenheiten übernehmen: Wenn ein bestehender Endpunkt einen nicht standardmäßigen Statuscode oder Fehlerfeldnamen zurückgibt, dokumentiere dies in Phase 1 und bewahre es im Fehlermapper von
infrastructure, damit bestehende Clients nicht brechen.