Auf dieser Seite
Architekturregeln, die den Teamwechsel überleben
Eine Architektur steht am Anfang in einem Diagramm und in den Köpfen der Menschen, die sie entworfen haben. Ein paar Jahre später arbeiten andere Menschen am Code, das Diagramm zeigt einen alten Stand, und im Domänenmodell liegt ein Import aus der Datenbankschicht. Niemand hat das beschlossen. Es ist einfach passiert, in einem Pull Request unter Zeitdruck.
Wenn ich eine hexagonale Architektur aufsetze, sichere ich sie deshalb von Anfang an mit automatischen Tests ab. Dieser Artikel zeigt, welche Regeln ich prüfe und warum. Die Beispiele stammen aus einer erfundenen Ausleihe für Stadtbibliotheken und sind für ArchUnit 1.x geschrieben.
Die Architektur in drei Sätzen
Die Fachlogik liegt in der Mitte und kennt weder Datenbank noch HTTP. Was sie von außen braucht, beschreibt sie als Schnittstelle, den Port. Die technische Umsetzung, der Adapter, hängt von der Fachlogik ab und nie umgekehrt.
Das ist schnell erklärt und schnell verletzt. Ein einziger Import in die falsche Richtung genügt.
Regeln als Tests
ArchUnit ist eine Bibliothek, mit der sich solche Regeln als gewöhnliche Unit-Tests schreiben lassen. Sie liest den Bytecode der Klassen und prüft die Abhängigkeiten. Die wichtigste Regel beschreibt die Schichten:
@AnalyzeClasses(packages = "org.example.lending", importOptions = ImportOption.DoNotIncludeTests.class)
class ArchitectureTest {
@ArchTest
static final ArchRule layers = layeredArchitecture().consideringAllDependencies()
.layer("Domain").definedBy("..domain..")
.layer("Application").definedBy("..application..")
.layer("Adapter").definedBy("..adapter..")
.whereLayer("Adapter").mayNotBeAccessedByAnyLayer()
.whereLayer("Application").mayOnlyBeAccessedByLayers("Adapter")
.whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Adapter")
.because("Abhängigkeiten zeigen nur nach innen");
}
Mit consideringAllDependencies() zählen alle Abhängigkeiten, auch die von Klassen außerhalb der drei Schichten. Das hat eine Folge. Eine Spring-Konfiguration in einem eigenen Paket verdrahtet Use Cases und Adapter. Damit verletzt sie mayOnlyBeAccessedByLayers("Adapter") und mayNotBeAccessedByAnyLayer(), und der erste Build ist rot. Die Konfiguration bekommt deshalb entweder eine eigene Schicht „Configuration“, die auf alle anderen zugreifen darf, oder sie liegt im Adapter-Paket.
Für eine reine Ports-and-Adapters-Architektur bringt ArchUnit mit onionArchitecture() eine fertige Variante mit, die Domänenmodell, Domänenservices, Anwendungsschicht und Adapter unterscheidet.
Der Test läuft bei jedem Build. Wer aus dem Domänenmodell auf einen Adapter zugreift, bekommt keinen Kommentar im Review, sondern einen roten Build mit der genauen Stelle.
Welche Regeln sich bewährt haben
Bewährt haben sich drei Gruppen von Regeln:
- Schichtregeln. Abhängigkeiten zeigen nur nach innen. Eingehende und ausgehende Adapter kennen sich gegenseitig nicht.
- Coding-Regeln. Keine Field Injection, kein
System.out, keine Abhängigkeit des Domänenmodells auf Spring. - Namensregeln. Ein Use Case heißt wie ein Use Case, ein Port wie ein Port, und beide liegen im dafür vorgesehenen Paket.
Die Namensregeln klingen kleinlich, sind es aber nicht: Wer neu im Code ist, findet einen Anwendungsfall an derselben Stelle wie alle anderen. Die erste Regel unten verlangt, dass jede Klasse im Paket usecase auf UseCase endet. Kommandos und Ergebnisobjekte liegen deshalb in einem eigenen Paket daneben. Für Ports sieht die Regel genauso aus, nur mit anderem Paket und anderer Endung. Die zweite Regel schließt eine Lücke der Schichtregel. Für sie sind alle Adapter eine Schicht, und innerhalb einer Schicht ist jeder Zugriff erlaubt. Dass sich adapter.in und adapter.out nicht kennen, prüft erst eine eigene Regel:
@ArchTest
static final ArchRule useCasesAreNamedAsSuch = classes()
.that().resideInAPackage("..application.usecase..")
.and().areTopLevelClasses()
.should().haveSimpleNameEndingWith("UseCase");
@ArchTest
static final ArchRule adaptersAreIndependent = slices()
.matching("..adapter.(*)..")
.should().notDependOnEachOther();
@ArchTest
static final ArchRule domainIsFrameworkFree = noClasses()
.that().resideInAPackage("..domain..")
.should().dependOnClassesThat().resideInAnyPackage("org.springframework..", "jakarta.persistence..")
.because("Fachlogik soll ohne Spring und ohne Datenbank testbar sein");
@ArchTest
static final ArchRule noFieldInjection = GeneralCodingRules.NO_CLASSES_SHOULD_USE_FIELD_INJECTION;
Für System.out gibt es GeneralCodingRules.NO_CLASSES_SHOULD_ACCESS_STANDARD_STREAMS. Eine Regel darf ruhig eine Begründung tragen: Was in .because(…) steht, erscheint direkt in der Fehlermeldung, und niemand muss im Wiki suchen, warum der Build rot ist.
Eine bestehende Codebasis umstellen
In einem neuen Projekt gelten die Regeln vom ersten Tag an. In gewachsenem Code gibt es am ersten Tag oft hunderte Verstöße. Ich gehe deshalb in Schritten vor:
- Erst die Pakete. Der Code zieht in die Zielstruktur um, ohne sein Verhalten zu ändern.
- Dann die schärfste Regel. Das Domänenmodell darf keine Adapter kennen. Bestehende Verstöße werden eingefroren, neue sind verboten.
- Dann die Feinheiten. Namensregeln und Coding-Regeln folgen, wenn die Struktur steht.
Für das Einfrieren bringt ArchUnit FreezingArchRule mit:
@ArchTest
static final ArchRule domainKnowsNoAdapters = FreezingArchRule.freeze(
noClasses().that().resideInAPackage("..domain..")
.should().dependOnClassesThat().resideInAPackage("..adapter.."));
Die Schichtregel vom Anfang wäre in gewachsenem Code am ersten Tag genauso rot. Sie kommt deshalb erst dazu, wenn ihre Verstöße behoben sind, oder wird auf dieselbe Weise eingefroren: FreezingArchRule.freeze(layeredArchitecture()…). Bis dahin hält die eingefrorene Einzelregel die wichtigste Richtung fest.
Beim ersten Lauf speichert ArchUnit alle vorhandenen Verstöße in einem Verzeichnis, das mit ins Repository gehört. Standardmäßig heißt es archunit_store und liegt im Arbeitsverzeichnis des Testlaufs. Mit freeze.store.default.path in der archunit.properties lässt sich der Ort festlegen. Danach schlägt der Test nur noch bei neuen Verstößen an, und behobene verschwinden bei einem lokalen Lauf von selbst aus der Liste. Länger wird die Liste nur, wenn jemand bewusst neu einfriert. Auch das zeigt der Diff, und Änderungen am Verzeichnis gehören deshalb ins Review. Für den Betrieb sind drei Einstellungen wichtig:
- Anlegen nur lokal. Damit das Verzeichnis entstehen darf, ist einmalig
freeze.store.default.allowStoreCreation=truenötig, am besten als Systemproperty:-Darchunit.freeze.store.default.allowStoreCreation=true. Steht der Wert in einer eingechecktenarchunit.properties, gilt er auch in der Pipeline. - In der Pipeline nichts schreiben. Dort gehört
-Darchunit.freeze.store.default.allowStoreUpdate=falsehin. Hat dann jemand einen Verstoß behoben, aber die kürzere Liste nicht eingecheckt, bricht der Build ab. Ohne diese Einstellung schreibt ArchUnit den neuen Stand still in die Pipeline-Kopie, und niemand sieht ihn. - Neue eingefrorene Regeln lokal einchecken. ArchUnit ordnet die Liste dem Text der Regel zu. Eine neue oder umformulierte Regel braucht deshalb einen lokalen Lauf, bevor sie in die Pipeline kommt.
Unter Maven reicht Surefire -D-Werte von der Kommandozeile an die Tests weiter. Unter Gradle landen sie nur in der Gradle-JVM, nicht im Testprozess. Dann greift keine der Einstellungen, und die Pipeline schreibt still weiter. Der Test-Task muss sie durchreichen:
tasks.test {
System.getProperties()
.filterKeys { (it as String).startsWith("archunit.") }
.forEach { (key, value) -> systemProperty(key as String, value) }
}
Zeilennummern ignoriert ArchUnit beim Abgleich. Wird eine Klasse mit eingefrorenem Verstoß aber umbenannt oder verschoben, gilt der Verstoß als neu. Dasselbe gilt, wenn sich der Text in .because(…) ändert, denn er gehört zur Beschreibung der Regel. In beiden Fällen schreibt ein lokaler Lauf mit -Darchunit.freeze.refreeze=true die Liste neu. Im Diff ist dann zu prüfen, dass nur verschobene Einträge dazugekommen sind und keine echten neuen Verstöße.
Was sich nicht testen lässt
Ein Architekturtest prüft Abhängigkeiten, nicht Entscheidungen. Er erkennt nicht, ob ein Use Case zu viel tut oder ob ein fachlicher Begriff falsch geschnitten ist. Dafür bleiben Reviews und Gespräche nötig.
Der Test nimmt dem Review aber die Fragen ab, über die niemand diskutieren muss. Übrig bleibt Zeit für die, die ein Mensch beantworten sollte.
Was es bringt
Teams wechseln, Menschen gehen, Wissen geht mit. Eine Regel, die als Test im Repository liegt, bleibt, solange sie niemand abschaltet. Abschalten geht dann aber nur noch sichtbar, als Änderung im Pull Request, die jemand begründen muss. Wer die Regel verletzt, erfährt es sofort und mit der Begründung, die in ihr steht, auch wenn niemand mehr da ist, der sie aufgestellt hat.
Das ist der eigentliche Wert: Die Regeln gehören nicht mehr zu einer Person, sondern zum Code.
Thema für Ihr Projekt?
Passende Leistung: Architektur-Review. Schildern Sie mir kurz, worum es geht. Ich melde mich mit einer ersten Einschätzung.
Projekt anfragen