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:

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:

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:

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