{"id":685,"date":"2026-06-11T00:35:56","date_gmt":"2026-06-10T23:35:56","guid":{"rendered":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/?p=685"},"modified":"2026-06-17T00:36:31","modified_gmt":"2026-06-16T23:36:31","slug":"archunit-architekturregeln-automatisch-als-unit-tests-pruefen","status":"publish","type":"post","link":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/?p=685","title":{"rendered":"ArchUnit \u2014 Architekturregeln automatisch als Unit-Tests pr\u00fcfen"},"content":{"rendered":"\n

Architektur ist kein Zufall \u2014 aber sie l\u00e4sst sich schwer durchsetzen. Ein Entwickler f\u00fcgt eine Abh\u00e4ngigkeit zwischen zwei Modulen hinzu, die eigentlich getrennt bleiben sollten. Ein anderer benennt eine Controller-Klasse ohne das Suffix Controller<\/code>. Solche Verst\u00f6\u00dfe fallen in Code-Reviews oft durch \u2014 aber nicht immer. ArchUnit<\/strong> macht Architekturregeln zu automatisch pr\u00fcfbaren Unit-Tests. Was mit JUnit Assertions f\u00fcr die Code-Logik funktioniert, leistet ArchUnit f\u00fcr die Code-Struktur.<\/p>\n\n\n\n

Grundlagen<\/h2>\n\n\n\n

ArchUnit besteht aus zwei Komponenten:<\/p>\n\n\n\n

    \n
  • archunit<\/strong>\u00a0\u2014 die Kernbibliothek mit einer Fluent-API zum Definieren von Regeln<\/li>\n\n\n\n
  • archunit-junit5<\/strong>\u00a0\u2014 Integration mit JUnit 5 f\u00fcr komfortables Testen<\/li>\n<\/ul>\n\n\n
    <dependency<\/span>><\/span>\n    <groupId<\/span>><\/span>com.tngtech.archunit<\/groupId<\/span>><\/span>\n    <artifactId<\/span>><\/span>archunit-junit5<\/artifactId<\/span>><\/span>\n    <version<\/span>><\/span>1.4.2<\/version<\/span>><\/span>\n    <scope<\/span>><\/span>test<\/scope<\/span>><\/span>\n<\/dependency<\/span>><\/span>\n<\/code><\/span>Code-Sprache:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
    ArchUnit analysiert den Java-Bytecode (keine Quelltextanalyse) und kann Regeln auf Package-, Klassen-, Methoden- und Feldebene definieren.<\/p>\n\n\n\n
    Paketabh\u00e4ngigkeiten \u00fcberwachen<\/h2>\n\n\n\n
    Die h\u00e4ufigste Architekturregel betrifft Schichten und Paketabh\u00e4ngigkeiten:<\/p>\n\n\n
    import<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.junit<\/span>.AnalyzeClasses<\/span>;\nimport<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.junit<\/span>.ArchTest<\/span>;\nimport<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.lang<\/span>.ArchRule<\/span>;\n\nimport<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.library<\/span>.Architectures<\/span>.layeredArchitecture<\/span>;\n\n@AnalyzeClasses<\/span>(packages = \"com.example.shop\"<\/span>)\nclass SchichtenArchitekturTest {\n\n    @ArchTest<\/span>\n    static final ArchRule schichtenRegel = layeredArchitecture()\n        .consideringAllDependencies()\n\n        .layer(\"Controller\"<\/span>).definedBy(\"..controller..\"<\/span>)\n        .layer(\"Service\"<\/span>).definedBy(\"..service..\"<\/span>)\n        .layer(\"Repository\"<\/span>).definedBy(\"..repository..\"<\/span>)\n        .layer(\"Domain\"<\/span>).definedBy(\"..domain..\"<\/span>)\n\n        .whereLayer(\"Controller\"<\/span>).mayNotBeAccessedByAnyLayer()\n        .whereLayer(\"Service\"<\/span>).mayOnlyBeAccessedByLayers(\"Controller\"<\/span>)\n        .whereLayer(\"Repository\"<\/span>).mayOnlyBeAccessedByLayers(\"Service\"<\/span>)\n        .whereLayer(\"Domain\"<\/span>).mayOnlyBeAccessedByLayers(\"Service\"<\/span>, \"Repository\"<\/span>);\n}\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Dieser Test schl\u00e4gt fehl, sobald ein Controller direkt auf ein Repository zugreift oder die Dom\u00e4nenschicht einen Service importiert \u2014 ein klassischer Fall von Architekturerosion.<\/p>\n\n\n\n
    Zyklenfreiheit erzwingen<\/h2>\n\n\n\n
    Zirkul\u00e4re Abh\u00e4ngigkeiten zwischen Paketen sind ein Warnsignal f\u00fcr schlechte Modularisierung:<\/p>\n\n\n
    import<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.library<\/span>.dependencies<\/span>.SlicesRuleDefinition<\/span>.slices<\/span>;\n\n@ArchTest<\/span>\nstatic final ArchRule keineZyklen = slices()\n    .matching(\"com.example.shop.(*)..\"<\/span>)\n    .should().beFreeOfCycles();\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Ein Zyklus zwischen com.example.shop.bestellung<\/code> und com.example.shop.kunde<\/code> f\u00fchrt sofort zu einem roten Test.<\/p>\n\n\n\n
    Namenskonventionen durchsetzen<\/h2>\n\n\n\n
    Mit ArchUnit lassen sich auch Benennungsregeln zentral definieren:<\/p>\n\n\n
    import<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.lang<\/span>.syntax<\/span>.ArchRuleDefinition<\/span>.classes<\/span>;\n\n@ArchTest<\/span>\nstatic final ArchRule controllerNamen = classes()\n    .that().resideInAPackage(\"..controller..\"<\/span>)\n    .should().haveSimpleNameEndingWith(\"Controller\"<\/span>);\n\n@ArchTest<\/span>\nstatic final ArchRule serviceImplementierungen = classes()\n    .that().resideInAPackage(\"..service..\"<\/span>)\n    .should().haveSimpleNameEndingWith(\"Service\"<\/span>)\n    .andShould().beAnnotatedWith(Service.class);\n\n@ArchTest<\/span>\nstatic final ArchRule repositoriesAlsInterfaces = classes()\n    .that().resideInAPackage(\"..repository..\"<\/span>)\n    .should().beInterfaces();\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Vertippt sich jemand und nennt einen Service KundeVerwaltung<\/code> statt KundeVerwaltungService<\/code>, signalisiert der ArchUnit-Test den Versto\u00df.<\/p>\n\n\n\n
    Gesch\u00fctzte Zugriffe auf externe Bibliotheken<\/h2>\n\n\n\n
    Manche Klassen sollten bestimmte externe APIs nicht nutzen d\u00fcrfen. ArchUnit kann das pr\u00fcfen:<\/p>\n\n\n
    import<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.lang<\/span>.syntax<\/span>.ArchRuleDefinition<\/span>.noClasses<\/span>;\n\n@ArchTest<\/span>\nstatic final ArchRule serviceKeinSystemOut = noClasses()\n    .that().resideInAPackage(\"..service..\"<\/span>)\n    .should().accessClassesThat()\n    .resideInAnyPackage(\"java.util.logging..\"<\/span>, \"java.sql..\"<\/span>);\n\n@ArchTest<\/span>\nstatic final ArchRule domainKeineFrameworkAbh\u00e4ngigkeit = noClasses()\n    .that().resideInAPackage(\"..domain..\"<\/span>)\n    .should().dependOnClassesThat()\n    .resideInAnyPackage(\n        \"org.springframework..\"<\/span>,\n        \"jakarta.persistence..\"<\/span>,\n        \"com.fasterxml..\"<\/span>\n    );\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Die Dom\u00e4nenschicht bleibt so frei von technischen Abh\u00e4ngigkeiten \u2014 ein Kernprinzip von Clean Architecture und Domain-Driven Design.<\/p>\n\n\n\n
    Kapselung von Feldern<\/h2>\n\n\n\n
    Auch innerhalb von Klassen lassen sich Regeln definieren:<\/p>\n\n\n
    import<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.lang<\/span>.syntax<\/span>.ArchRuleDefinition<\/span>.fields<\/span>;\nimport<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.lang<\/span>.syntax<\/span>.ArchRuleDefinition<\/span>.noClasses<\/span>;\n\n@ArchTest<\/span>\nstatic final ArchRule keinePublicFelder = fields()\n    .that().areDeclaredInClassesThat()\n    .resideInAPackage(\"..domain..\"<\/span>)\n    .should().bePrivate();\n\n@ArchTest<\/span>\nstatic final ArchRule keineJpaInDom\u00e4ne = noClasses()\n    .that().resideInAPackage(\"..domain..\"<\/span>)\n    .should().accessClassesThat()\n    .resideInAnyPackage(\"jakarta.persistence..\"<\/span>);\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    PlantUML-Integration: Diagramm als Regel<\/h2>\n\n\n\n
    Eine Architektur kann auch als PlantUML-Komponentendiagramm modelliert und direkt als Regel eingebunden werden:<\/p>\n\n\n
    import<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.library<\/span>.plantuml<\/span>.PlantUmlArchCondition<\/span>;\n\nimport<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.library<\/span>.plantuml<\/span>.PlantUmlArchCondition<\/span>.consideringOnlyDependenciesInAnyPackage<\/span>;\n\n@ArchTest<\/span>\nstatic final ArchRule plantUmlRegel = PlantUmlArchCondition\n    .adhereToPlantUmlDiagram(\n        MyArchitectureTest.class.getResource(\"\/architektur.puml\"<\/span>),\n        consideringOnlyDependenciesInAnyPackage(\"com.example.shop..\"<\/span>));\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    ArchUnit vergleicht dann die tats\u00e4chlichen Abh\u00e4ngigkeiten mit den im Diagramm erlaubten Verbindungen. So bleibt die Dokumentation im Code automatisch synchron mit der Realit\u00e4t.<\/p>\n\n\n\n
    Onion Architecture & Hexagonal Architecture<\/h2>\n\n\n\n
    Neben der klassischen Schichtenarchitektur unterst\u00fctzt ArchUnit auch Onion Architecture<\/strong> (Hexagonal Architecture \/ Ports & Adapters):<\/p>\n\n\n
    import<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.library<\/span>.Architectures<\/span>.onionArchitecture<\/span>;\n\n@ArchTest<\/span>\nstatic final ArchRule onionRegel = onionArchitecture()\n    .domainModels(\"..domain.model..\"<\/span>)\n    .domainServices(\"..domain.service..\"<\/span>)\n    .applicationServices(\"..application..\"<\/span>)\n    .adapter(\"rest\"<\/span>, \"..adapter.rest..\"<\/span>)\n    .adapter(\"persistence\"<\/span>, \"..adapter.persistence..\"<\/span>);\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Die Dom\u00e4nenschicht ist der Kern und darf keine Abh\u00e4ngigkeiten nach au\u00dfen haben. Adapter d\u00fcrfen auf Dom\u00e4ne und Applikation zugreifen, aber nicht untereinander \u2014 ArchUnit pr\u00fcft diese Regeln automatisch.<\/p>\n\n\n\n
    General Coding Rules<\/h2>\n\n\n\n
    F\u00fcr projekt\u00fcbergreifende Best Practices bietet ArchUnit vordefinierte GeneralCodingRules<\/code>:<\/p>\n\n\n
    import<\/span> static<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.library<\/span>.GeneralCodingRules<\/span>.*;\n\n@ArchTest<\/span>\nstatic final ArchRule keinFieldInjection = NO_CLASSES_SHOULD_USE_FIELD_INJECTION;\n\n@ArchTest<\/span>\nstatic final ArchRule keinSystemOut = NO_CLASSES_SHOULD_ACCESS_STANDARD_STREAMS;\n\n@ArchTest<\/span>\nstatic final ArchRule keineGenericExceptions = NO_CLASSES_SHOULD_THROW_GENERIC_EXCEPTIONS;\n\n@ArchTest<\/span>\nstatic final ArchRule keineAltenDatumsklassen = OLD_DATE_AND_TIME_CLASSES_SHOULD_NOT_BE_USED;\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Diese Regeln sind sofort einsetzbar und decken h\u00e4ufige Fallstricke wie Field Injection, System.out<\/code>-Logging oder die Nutzung von java.util.Date<\/code> ab.<\/p>\n\n\n\n
    Frozen Rules<\/h2>\n\n\n\n
    Hat man eine bestehende Codebasis mit vielen Architektur-Verst\u00f6\u00dfen, ist es unrealistisch, alle auf einmal zu beheben. Frozen Rules<\/strong> frieren den aktuellen Stand ein und schlagen nur bei neuen Verst\u00f6\u00dfen Alarm:<\/p>\n\n\n
    import<\/span> com<\/span>.tngtech<\/span>.archunit<\/span>.library<\/span>.freeze<\/span>.FreezingArchRule<\/span>;\n\n@ArchTest<\/span>\nstatic final ArchRule schichtenRegel = FreezingArchRule\n    .freeze(layeredArchitecture()\n        .layer(\"Controller\"<\/span>).definedBy(\"..controller..\"<\/span>)\n        .layer(\"Service\"<\/span>).definedBy(\"..service..\"<\/span>)\n        .whereLayer(\"Controller\"<\/span>).mayNotBeAccessedByAnyLayer()\n        .whereLayer(\"Service\"<\/span>).mayOnlyBeAccessedByLayers(\"Controller\"<\/span>));\n<\/code><\/span>Code-Sprache:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Beim ersten Ausf\u00fchren speichert ArchUnit alle aktuellen Verst\u00f6\u00dfe in einem ViolationStore<\/code>. Zuk\u00fcnftige Testl\u00e4ufe melden dann nur noch neue<\/strong> Verst\u00f6\u00dfe \u2014 bestehende werden toleriert. Um den aktuellen Stand aller Verst\u00f6\u00dfe bewusst neu einzufrieren, kann die Eigenschaft freeze.refreeze<\/code> auf true<\/code> gesetzt werden (z.\u202fB. via System-Property -Darchunit.freeze.refreeze=true<\/code>). Der ViolationStore<\/code> wird eingecheckt, sodass das gesamte Team dieselbe Baseline nutzt.<\/p>\n\n\n\n
    Fazit<\/h2>\n\n\n\n
    ArchUnit verwandelt Architektur von einer subjektiven Diskussion in eine objektive, automatisierte Pr\u00fcfung. Es ersetzt kein Architekturverst\u00e4ndnis, macht aber Architekturregeln messbar und durchsetzbar. In CI\/CD-Pipelines sichern diese Tests die strukturelle Integrit\u00e4t des Codes bei jedem Commit \u2014 und das mit einer API, die jedem JUnit-Entwickler sofort vertraut ist.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Architektur ist kein Zufall \u2014 aber sie l\u00e4sst sich schwer durchsetzen. Ein Entwickler f\u00fcgt eine Abh\u00e4ngigkeit zwischen zwei Modulen hinzu, die eigentlich getrennt bleiben sollten. Ein anderer benennt eine Controller-Klasse ohne das Suffix Controller. Solche Verst\u00f6\u00dfe fallen in Code-Reviews oft durch \u2014 aber nicht immer. ArchUnit macht Architekturregeln zu automatisch pr\u00fcfbaren Unit-Tests. Was mit JUnit Assertions f\u00fcr die […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[],"class_list":["post-685","post","type-post","status-publish","format-standard","hentry","category-plain_java"],"_links":{"self":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/685","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=685"}],"version-history":[{"count":1,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/685\/revisions"}],"predecessor-version":[{"id":686,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/685\/revisions\/686"}],"wp:attachment":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=685"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=685"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=685"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}