Clean Architecture Framework
Ein disziplinierter Ansatz zur Strukturierung von Software, sodass Geschäftsregeln unabhängig von Frameworks, Datenbanken und Liefermechanismen bleiben. Wenden Sie diese Prinzipien an, wenn Sie Systemarchitekturen entwerfen, Modulgrenzen überprüfen oder bei der Abhängigkeitsverwaltung beraten.
Kernprinzip
Quellcode-Abhängigkeiten müssen nach innen zeigen – zu Richtlinien höherer Ebene. Nichts in einem inneren Kreis darf etwas über einen äußeren Kreis wissen. Diese einzige Regel erzeugt Systeme, die testbar und unabhängig von Frameworks, Benutzeroberflächen, Datenbanken und externen Instanzen sind. Geschäftsregeln sind das, was zählt; Datenbanken, Web-Frameworks und Liefermechanismen sind Details – wenn Details von Richtlinien abhängen, können Sie Entscheidungen aufschieben, Implementierungen austauschen und Geschäftslogik isoliert testen.
Bewertung
Ziel: 10/10. Vergeben Sie einen Punkt für jede der sieben Zeilen der Schnelldiagnose, die die Architektur erfüllt (0-7), und ordnen Sie diese dann einer 0-10-Skala zu: 6-7 erfüllt = 9-10 (Abhängigkeitsregel gilt, Geschäftslogik ist framework- und datenbankunabhängig); 4-5 = 6-8 (Kern ist testbar, aber einige Details sickern nach innen); 2-3 = 3-5 (Framework oder Persistenz bestimmt die Struktur); 0-1 = 0-2 (keine Grenzen – Geschäftsregeln leben in Controllern und ORM-Modellen). Berichten Sie die Punktzahl, die nicht bestandenen Diagnosezeilen und die spezifische Umkehrung, die zur Behebung jeder einzelnen erforderlich ist.
1. Abhängigkeitsregel und konzentrische Kreise
Kernkonzept: Organisieren Sie die Architektur als konzentrische Kreise – Entitäten (unternehmensweite Geschäftsregeln) am innersten, dann Anwendungsfälle (anwendungsspezifische Geschäftsregeln), dann Schnittstellenadapter, mit Frameworks und Treibern am äußersten. Quellcode-Abhängigkeiten zeigen immer nach innen.
Warum es funktioniert: Wenn Richtlinien hoher Ebene nicht von Details niedriger Ebene abhängen, können Sie die Datenbank, das Web-Framework oder den API-Stil austauschen, ohne die Geschäftslogik zu berühren – das System wird widerstandsfähig gegenüber den volatilsten Teilen des Stacks.
Wichtige Erkenntnisse:
- Innere Kreise dürfen keine Namen äußerer Kreise erwähnen – keine Klassen, Funktionen, Variablen oder Datenformate von außen
- Daten, die eine Grenze überschreiten, müssen in der für den inneren Kreis günstigsten Form vorliegen, niemals vom äußeren Kreis vorgegeben
- Dependency Inversion (nach innen definierte, nach außen implementierte Schnittstellen) ist der Mechanismus, der die Regel durchsetzt
- Die Anzahl der Kreise ist nicht festgelegt – vier sind typisch; die Regel bleibt gleich
- Frameworks sind Details, keine Architektur – sie gehören in den äußersten Kreis
Code-Anwendungen:
| Kontext | Muster | Beispiel |
|---|---|---|
| Schichtenrichtung | Innere Kreise definieren Schnittstellen; äußere implementieren | BenutzerRepository-Schnittstelle in Anwendungsfällen; PostgresBenutzerRepository in Adaptern |
| Datenübertragung | DTOs überqueren Grenzen, nicht ORM-Entitäten | Anwendungsfall gibt Benutzerantwort-DTO zurück, nicht ein ActiveRecord-Modell |
| Abhängigkeitsrichtung | Importpfeile zeigen immer nach innen | Controller importiert Anwendungsfall; Anwendungsfall importiert niemals Controller |
Siehe references/dependency-rule.md, wenn ein Import aus dem inneren Kreis nach außen zeigt und Sie die Code-Durchlauf durch die vier Kreise, die Regeln für Datenübertragung und die vierstufige Dependency-Inversion-Prozedur zur Behebung benötigen.
2. Entitäten und Anwendungsfälle
Kernkonzept: Entitäten kapseln unternehmensweite Geschäftsregeln – Regeln, die auch ohne Software existieren würden. Anwendungsfälle enthalten anwendungsspezifische Regeln, die den Datenfluss zu und von Entitäten orchestrieren.
Warum es funktioniert: Die Trennung von dem, was das Geschäft tut (Entitäten), und wie die Anwendung es orchestriert (Anwendungsfälle), ermöglicht die Wiederverwendung von Entitäten über Anwendungen hinweg und die Änderung des Anwendungsverhaltens, ohne die Kern-Geschäftsregeln zu verändern.
Wichtige Erkenntnisse:
- Entitäten sind keine Datenbankzeilen – sie sind Objekte oder reine Funktionen, die kritische Geschäftsregeln kapseln
- Anwendungsfälle akzeptieren Anforderungsmodelle und geben Antwortmodelle zurück – niemals Framework-Objekte
- Jeder Anwendungsfall ist ein einzelner Anwendungsvorgang (
BestellungErstellen,AusgabeGenehmigen) - Das Interactor-Muster: Eine Anwendungsfall-Klasse implementiert eine Eingabe-Grenzschnittstelle und ruft eine Ausgabe-Grenzschnittstelle auf
- Änderungen an einem Anwendungsfall sollten niemals eine Entität betreffen; Änderungen an Entitäten können sich auf Anwendungsfälle auswirken
Code-Anwendungen:
| Kontext | Muster | Beispiel |
|---|---|---|
| Entitätsdesign | Kritische Geschäftsregeln, null Framework-Abhängigkeiten | Bestellung.berechneGesamtsumme() wendet Steuerregeln an; weiß nichts über HTTP |
| Anforderung/Antwort | Einfache Datenstrukturen überqueren die Grenze | BestellungErstellenAnfrage { artikel, kundenId } – keine ORM-Modelle |
| Einzelverantwortung | Ein Anwendungsfall pro Vorgang | BestellungAufgeben, BestellungStornieren, BestellungRückerstatten als separate Klassen |
| Interactor | Implementiert Eingabeport, ruft Ausgabeport auf | BestellungAufgebenInteractor implements BestellungAufgebenEingabe |
Siehe references/entities-use-cases.md beim Entwerfen eines Interactors oder bei der Entscheidung, was in eine Entität vs. einen Anwendungsfall gehört – vollständige Behandlung der Unternehmens- vs. Anwendungs-Geschäftsregeln mit Beispielen für Anforderungs-/Antwortmodelle.
3. Schnittstellenadapter und Frameworks
Kernkonzept: Schnittstellenadapter konvertieren Daten zwischen der für Anwendungsfälle/Entitäten bequemen Form und der von externen Instanzen geforderten Form. Frameworks und Treiber sind die äußerste Schicht – Klebecode zur Außenwelt.
Warum es funktioniert: Wenn das Web-Framework, ORM oder die Nachrichtenwarteschlange auf die äußeren Kreise beschränkt ist, ist das Ersetzen eines von ihnen eine lokalisierte Änderung. Die Datenbank ist ein Detail; das Web ist ein Detail; Details sollten Plugins für Ihre Geschäftsregeln sein, nicht das Skelett der Anwendung.
Wichtige Erkenntnisse:
- Controller übersetzen HTTP in Anwendungsfalleingaben; Presenter übersetzen Anwendungsfallausgaben in Ansichtsmodelle
- Gateways implementieren von Anwendungsfällen definierte Repository-Schnittstellen – der innere Kreis definiert den Vertrag, der äußere erfüllt ihn
- Geschäftsregeln wissen nie, ob Daten in SQL, NoSQL oder flachen Dateien leben oder ob die Lieferung über HTTP erfolgt
- Behandeln Sie Frameworks mit Misstrauen – sie möchten, dass Sie sich an sie koppeln; halten Sie sie auf Armeslänge
Code-Anwendungen:
| Kontext | Muster | Beispiel |
|---|---|---|
| Controller | Liefermechanismus → Anwendungsfalleingabe | BestellungController.erstellen(req) erstellt BestellungErstellenAnfrage, ruft Interactor auf |
| Presenter | Anwendungsfallausgabe → Ansichtsmodell | BestellungPresenter.präsentieren(antwort) formatiert für JSON/HTML |
| Gateway | Pro DB implementierte Repository-Schnittstelle | SqlBestellungRepository implementiert BestellungRepository |
| Framework-Grenze | Framework ruft nach innen auf, nie umgekehrt | Express-Routen-Handler ruft Controller auf; Controller importiert nie Express |
Siehe references/adapters-frameworks.md beim Verdrahten von Controllern, Presentern oder Gateways oder beim Argumentieren, dass Datenbank/Web ein Detail sind – behandelt Plugin-Architektur und wie man ein Framework auf die Ränder beschränkt.
4. Komponentenprinzipien
Kernkonzept: Komponenten sind die Bereitstellungseinheiten. Drei Kohäsionsprinzipien bestimmen, was in eine Komponente gehört; drei Kopplungsprinzipien bestimmen die Beziehungen zwischen Komponenten.
Warum es funktioniert: Schlecht zusammengesetzte Komponenten erzeugen Auswirkungen, bei denen eine Änderung die erneute Bereitstellung von nicht zusammenhängendem Code erzwingt; die Prinzipien halten Änderungen lokal und veröffentlichungen unabhängig.
Wichtige Erkenntnisse:
- REP (Wiederverwendungs-/Veröffentlichungsäquivalenz): Klassen in einer Komponente müssen als Einheit versionierbar und veröffentlichbar sein
- CCP (Gemeinsamer Abschluss): Klassen, die sich aus demselben Grund zur selben Zeit ändern, gehören zusammen – SRP für Komponenten
- CRP (Gemeinsame Wiederverwendung): Zwingen Sie Benutzer nicht, von Klassen abzuhängen, die sie nicht verwenden
- ADP (Azyklische Abhängigkeiten): Der Komponentengraph darf keine Zyklen haben – brechen Sie sie mit DIP oder einer neuen Komponente auf
- SDP (Stabile Abhängigkeiten): Hängen Sie in Richtung der Stabilität ab
- SAP (Stabile Abstraktionen): Stabile Komponenten sollten abstrakt sein; instabile konkret
Code-Anwendungen:
| Kontext | Muster | Beispiel |
|---|---|---|
| Komponentengruppierung | Gruppieren Sie Klassen, die sich gemeinsam ändern (CCP) | Alle bestellbezogenen Anwendungsfälle in einer Komponente |
| Zyklen brechen | Wenden Sie DIP an, um eine Abhängigkeitskante umzukehren | Extrahiere eine Schnittstelle in eine neue Komponente, um den Zyklus zu brechen |
| Stabilitätsmetriken | Instabilität I = Ce / (Ca + Ce) | Viele eingehende, keine ausgehenden Abhängigkeiten → I nahe 0 (stabil) |
Siehe references/component-principles.md beim Gruppieren von Klassen in bereitstellbare Komponenten oder beim Brechen eines Abhängigkeitszyklus – jedes von REP, CCP, CRP, ADP, SDP, SAP durchgearbeitet mit der Instabilitätsmetrik.
5. SOLID-Prinzipien
Kernkonzept: Fünf Prinzipien auf Klassen- und Modulebene – Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion – die Bausteine der mittleren Ebene, die die Abhängigkeitsregel ermöglichen.
Warum es funktioniert: Jedes Prinzip adressiert eine spezifische Art und Weise, wie Abhängigkeiten schiefgehen, und verhindert die Starrheit, Zerbrechlichkeit und Unbeweglichkeit, die Codebasen zu Albtraum-Altsystemen machen.
Wichtige Erkenntnisse:
- SRP: Ein Modul hat einen Grund, sich zu ändern – es dient einem Akteur (nicht „es tut eine Sache“)
- OCP: Verhalten durch Hinzufügen von neuem Code erweitern, nicht durch Ändern von vorhandenem – Strategie- und Plugin-Muster
- LSP: Untertypen müssen über die Basisschnittstelle nutzbar sein, ohne dass der Client es weiß – verletzt durch unerwartete Ausnahmen oder ignorierte Methoden
- ISP: Clients sollten nicht von Methoden abhängen, die sie nicht verwenden – fette Schnittstellen erzeugen unnötige Kopplung
- DIP: Hochwertige Module und niederwertige Module hängen beide von Abstraktionen ab, die vom hochwertigen Modul definiert werden
Code-Anwendungen:
| Kontext | Muster | Beispiel |
|---|---|---|
| SRP-Verletzung | Klasse dient mehreren Akteuren | Mitarbeiter behandelt Gehalt (CFO), Berichterstattung (COO), Persistenz (CTO) |
| OCP via Strategie | Neues Verhalten durch neue Klassen | ExpressVersand implementiert Versandstrategie; Bestellung unberührt |
| LSP-Verletzung | Untertyp ändert erwartetes Verhalten | Quadrat erweitert Rechteck bricht den setBreite()/setHöhe()-Vertrag |
| ISP-Anwendung | Fette Schnittstellen in Rollenschnittstellen aufteilen | Drucker, Scanner, Fax statt einem Multifunktionsgerät |
| DIP-Verdrahtung | Hochwertig definiert Schnittstelle; niederwertig implementiert | BestellService hängt von ZahlungsGateway ab, nicht von StripeClient |
Siehe references/solid-principles.md bei der Anwendung von SRP/OCP/LSP/ISP/DIP auf eine bestimmte Klasse oder bei der Diagnose einer Verletzung – jedes Prinzip durchgearbeitet mit Codebeispielen und dem Geruch, den es verhindert.
6. Grenzen und Grenzanatomie
Kernkonzept: Eine Grenze ist eine Linie zwischen Dingen, die wichtig sind, und Details, implementiert durch Polymorphismus: Abhängigkeiten kreuzen nach innen zeigend, während der Kontrollfluss in beide Richtungen verlaufen kann.
Warum es funktioniert: Jede Grenze erkauft die Option, eine Entscheidung aufzuschieben oder eine Implementierung auszutauschen; die strategische Platzierung von Grenzen bestimmt, ob ein System über Jahre hinweg eine Freude oder eine Qual zu warten ist.
Wichtige Erkenntnisse:
- Vollständige Grenzen verwenden reziproke Schnittstellen auf beiden Seiten; partielle Grenzen verwenden eine einfachere Strategie oder Fassade
- Bescheidenes-Objekt-Muster: Teilen Sie Grenzcode in einen schwer testbaren Teil (nahe der Grenze) und einen einfach testbaren Teil (die Logik)
- Dienste sind nicht automatisch architektonische Grenzen – ein Microservice mit einem fetten gemeinsamen Datenmodell ist ein Monolith mit Netzwerkaufrufen
- Tests sind die isolierteste Komponente: Sie hängen nach innen ab, nichts hängt von ihnen ab
- Vorzeitige Grenzen sind teuer, aber fehlende auch – ziehen Sie sie an Punkten wahrscheinlicher Volatilität
Code-Anwendungen:
| Kontext | Muster | Beispiel |
|---|---|---|
| Vollständige vs. partielle Grenze | Reziproke Ports oder eine einzelne Strategie | Anwendungsfall definiert BestellungAufgebenEingabe/BestellungAufgebenAusgabe; einfachere Fälle nehmen eine Versandstrategie |
| Bescheidenes Objekt | Testbare Logik von Infrastruktur trennen | PresenterLogik (testbar) erzeugt Ansichtsmodell; Ansicht (bescheiden) rendert es |
| Main als Plugin | Kompositionswurzel setzt das System zusammen | main() verdrahtet alle konkreten Implementierungen und startet die App |
Siehe references/boundaries.md bei der Entscheidung, wo eine Grenze zu ziehen ist, bei der Wahl zwischen vollständiger und partieller Grenze oder bei der Anwendung des Bescheidenen-Objekt-Musters – behandelt auch Dienste als Grenzen, Testgrenzen und Main als das ultimative Plugin.
Häufige Fehler
| Fehler | Warum es scheitert | Behebung |
|---|---|---|
| ORM sickert in Geschäftslogik | Entitäten koppeln an das Schema; DB-Änderungen schreiben Geschäftsregeln neu | Trennen Sie Domänenentitäten von Persistenzmodellen; mappen Sie auf der Adapterschicht |
| Geschäftsregeln in Controllern | Ohne HTTP nicht testbar; über Endpunkte dupliziert | Verschieben Sie Logik in Anwendungsfall-Interactors; Controller übersetzen und delegieren nur |
| Framework-zentrierte Architektur | Framework bestimmt Struktur; Austausch bedeutet Neuschreibung | Behandeln Sie das Framework als Plugin; strukturieren Sie Code nach Geschäftsfähigkeit |
| Zirkuläre Komponentenabhängigkeiten | Änderungen wirken sich unvorhersehbar aus; keine unabhängigen Veröffentlichungen | Wenden Sie DIP an oder extrahieren Sie eine gemeinsame Abstraktionskomponente |
| Ein riesiger Anwendungsfall pro Funktion | Aufgeblähte tausendzeilige Orchestratoren | Teilen Sie in fokussierte Einzelvorgangs-Anwendungsfälle auf |
| Grenzen überspringen, „weil es einfach ist“ | Kopplung sammelt sich still an, bis die Kosten enorm sind | Ziehen Sie Grenzen proaktiv an Punkten wahrscheinlicher Volatilität |
| Microservices als automatisch gute Architektur | Ein verteilter Monolith ist schlimmer als ein sauberer Monolith | Wenden Sie die Abhängigkeitsregel innerhalb und zwischen Diensten an; Dienste sind Bereitstellungsgrenzen, keine architektonischen |
Schnelldiagnose
| Frage | Wenn Nein | Aktion |
|---|---|---|
| Können Sie Geschäftsregeln ohne DB, Webserver oder Framework testen? | Regeln an Infrastruktur gekoppelt | Extrahiere Entitäten und Anwendungsfälle hinter Schnittstellen; mocke äußere Schichten |
| Zeigen alle Quellcode-Abhängigkeiten nach innen? (Kein Import aus innerem Kreis nach außen) | Abhängigkeitsregel verletzt | Wende Dependency Inversion an: Definiere Schnittstelle im inneren Kreis, verschiebe Implementierung nach außen |
| Können Sie die Datenbank wechseln, ohne Geschäftslogik zu ändern? | Geschäftslogik kennt DB-API | Mappe ORM auf Domänen-Entitäten im Repository-Adapter; ändere Geschäftslogik nie |
| Haben Sie isolierte Anwendungsfälle, die eine Sache tun? | Anwendungsfälle sind aufgebläht oder fehlen | Refaktoriere in einzelne, nach Aktion benannte Anwendungsfall-Klassen |
| Sind Framework-Importe auf die äußerste Schicht beschränkt? | Framework sickert in Anwendungsfälle oder Entitäten | Extrahiere Framework-Code in Adapter; Geschäftslogik darf Framework nicht importieren |
| Kann eine neue Version einer Komponente bereitgestellt werden, ohne andere neu zu deployen? | Zirkuläre Abhängigkeiten oder verdeckte Kopplung | Breche Zyklen auf; wende Stabile-Abhängigkeiten-Prinzip (SDP) an |
| Prüfen Sie regelmäßig Abhängigkeiten mit Abhängigkeits- und Stabilitätsmetriken? | Architektur degradiert ohne Messung | Führe automatische Prüfungen in CI/CD ein; richte Governance mit ADRs ein |
Nächste Schritte
- Diagnostizieren: Beantworten Sie die 7 Schnelldiagnose-Fragen für jedes Modul oder jeden Dienst
- Scoren: Berechnen Sie den Clean Architecture Score 0-10
- Priorisieren: Wählen Sie den niedrigsten Score und die einfachste Behebung aus der Fehlertabelle
- Umsetzen: Verwenden Sie die Referenzdateien (
references/*.md) für Schritt-für-Schritt-Code-Anwendungen:- references/dependency-rule.md – Dependency Rule, Datenübertragung, vier Kreise
- references/entities-use-cases.md – Entitäten vs. Anwendungsfälle, Interactors
- references/adapters-frameworks.md – Controller, Presenter, Gateways
- references/component-principles.md – REP, CCP, CRP, ADP, SDP, SAP
- references/solid-principles.md – SRP, OCP, LSP, ISP, DIP
- references/boundaries.md – Grenztypen, Bescheidenes Objekt, Main als Plugin