[{"content":"Hexagonale Architektur (auch Ports and Adapters, geprägt von Alistair Cockburn) wird oft mit Schichtenarchitektur verwechselt oder zu einem Ordnerschema verkürzt. Dabei steckt hinter dem Konzept eine einzige, ziemlich scharfe Regel:\nAbhängigkeiten zeigen immer nach innen, zur Fachlichkeit. Die Fachlichkeit kennt weder Datenbank noch Framework noch HTTP.\nDas Bild dazu flowchart LR subgraph Aussen[\"Adapter (außen)\"] REST[\"REST-Controller\"] JPA[\"JPA-Repository\"] MAIL[\"Mail-Client\"] end subgraph Innen[\"Anwendungskern\"] IN[\"Eingehender Port\nBestellungAufgeben\"] UC[\"Use Case\nund Domäne\"] OUT[\"Ausgehender Port\nBestellungenSpeichern\"] end REST --\u003e IN IN --\u003e UC UC --\u003e OUT JPA -. implementiert .-\u003e OUT MAIL -. implementiert .-\u003e OUT Die gestrichelten Linien sind der entscheidende Punkt: Der Adapter implementiert ein Interface, das der Kern besitzt. Der Kern ruft nie eine Datenbank-Klasse direkt auf. Das nennt man Dependency Inversion.\nEin kleines Beispiel Der ausgehende Port ist ein Interface im Kern:\n// Gehört zum Anwendungskern, kein JPA, kein Spring public interface BestellungenSpeichern { void speichern(Bestellung bestellung); } Der Use Case nutzt nur dieses Interface:\npublic class BestellungAufgeben { private final BestellungenSpeichern speicher; public BestellungAufgeben(BestellungenSpeichern speicher) { this.speicher = speicher; } public void ausfuehren(Bestellung bestellung) { bestellung.pruefen(); // Fachregeln liegen in der Domäne speicher.speichern(bestellung); } } Erst der Adapter am Rand kennt die Technik:\n@Repository class BestellungenJpaAdapter implements BestellungenSpeichern { private final BestellungJpaRepository jpa; BestellungenJpaAdapter(BestellungJpaRepository jpa) { this.jpa = jpa; } @Override public void speichern(Bestellung bestellung) { jpa.save(BestellungEntity.from(bestellung)); } } Merke Nicht die Ordnerstruktur macht die Architektur hexagonal, sondern die Richtung der Abhängigkeiten. Prüfen lässt sich das automatisiert, zum Beispiel mit ArchUnit. Was du davon hast Fachlogik lässt sich ohne Datenbank und ohne Framework testen. Technische Entscheidungen (Datenbank, Messaging, Framework) bleiben austauschbar. Der Kern wird zur Dokumentation dessen, was das System fachlich tut. Was das kostet und wann es sich nicht lohnt, schreibe ich im Artikel Wann Hexagonal Overengineering ist.\n","permalink":"https://blog.groscyk.de/posts/hexagonale-architektur-einstieg/","summary":"Ports und Adapter ohne Dogma: ein kleines Beispiel, ein Diagramm und die eine Regel, auf die es ankommt.","title":"Hexagonale Architektur: Ports und Adapter an einem kleinen Beispiel"},{"content":"Architekturdokumentation veraltet schnell, aber Entscheidungen bleiben relevant. Wer in einem Projekt mit „Warum ist das eigentlich so gebaut?\u0026quot; konfrontiert wird, will keine Systembeschreibung, sondern den Kontext der Entscheidung.\nGenau dafür gibt es Architecture Decision Records (ADRs), ein Format, das Michael Nygard 2011 vorgestellt hat.\nDas Prinzip Eine Entscheidung pro Datei, Markdown, im selben Repository wie der Code. Kurz: eine Seite, nicht zehn. Unveränderlich: Eine überholte Entscheidung wird nicht gelöscht, sondern als ersetzt markiert und verweist auf die neue. Nummeriert: 0007-postgres-statt-mongodb.md Eine Vorlage # 7. PostgreSQL als primäre Datenbank Datum: 2026-11-07 Status: akzeptiert ## Kontext Welche Kräfte wirken? Anforderungen, Einschränkungen, Team-Wissen. ## Entscheidung Was haben wir entschieden? Ein Satz, aktiv formuliert. ## Alternativen Was wurde ernsthaft erwogen, und warum nicht gewählt? ## Konsequenzen Was wird einfacher? Was wird schwerer? Welche Risiken nehmen wir in Kauf? Der Abschnitt Alternativen ist der wertvollste. Er verhindert, dass dieselbe Diskussion alle sechs Monate neu geführt wird.\nFaustregel Schreibe einen ADR, wenn eine Entscheidung teuer zu ändern ist oder wenn du dich dabei ertappst, sie jemandem erklären zu müssen. Typische Fehler Fehler Besser ADR erst Monate später rückwirkend schreiben Direkt im Pull Request mit der Änderung Nur die Entscheidung, kein Kontext Kontext und Alternativen gehören zwingend dazu Zu viele ADRs für Kleinigkeiten Nur Entscheidungen mit Architektur-Wirkung ADRs in einem Wiki, getrennt vom Code Im Repository, wird im Review mit geprüft Fazit ADRs kosten pro Entscheidung zehn bis fünfzehn Minuten. Dafür sparen sie jedem neuen Teammitglied und dir selbst in zwei Jahren viele Stunden Detektivarbeit.\n","permalink":"https://blog.groscyk.de/posts/architecture-decision-records/","summary":"Eine Entscheidung pro Datei, kurz genug zum Lesen, im Repository versioniert. Mit Vorlage.","title":"Architecture Decision Records: Entscheidungen, die auch in zwei Jahren noch verständlich sind"},{"content":"Hexagonale Architektur ist ein mächtiges Werkzeug, aber sie hat einen Preis: mehr Klassen, mehr Mapping, mehr Indirektion. Wer sie auf einen einfachen CRUD-Dienst anwendet, schreibt viel Code, der nur Daten von A nach B kopiert.\nWas es kostet Mapping zwischen Domänenobjekten, Entities und DTOs Mehr Interfaces und mehr Dateien, die man beim Lesen verfolgen muss Das Team muss das Prinzip verstehen und die Regeln einhalten Was es bringt Fachlogik ist isoliert und gut testbar Technische Details sind austauschbar Langlebige, komplexe Domänen bleiben beherrschbar Wann lohnt es sich? Situation Hexagonal? Reiner CRUD-Dienst ohne echte Fachregeln Eher nein Komplexe Fachlogik, die lange leben soll Ja Viele externe Schnittstellen, die sich ändern Ja Prototyp, der evtl. wieder verschwindet Nein Migration eines gewachsenen Monolithen Ja, aber schrittweise Wichtig Die Entscheidung gilt pro Modul, nicht pro System. Ein System darf in seinem komplexen Kern hexagonal gebaut sein und trotzdem an den Rändern einfache CRUD-Module enthalten. Drei Fragen vor der Entscheidung Wie komplex sind die Fachregeln wirklich? Wenn sie sich auf „speichern und laden\u0026quot; beschränken, ist der Overhead nicht gerechtfertigt. Wie lange soll der Code leben? Je länger, desto eher zahlt sich die Entkopplung aus. Kann das Team das tragen? Eine Architektur, die nur eine Person versteht, ist ein Risiko. Wer unsicher ist, fängt mit einem einfachen Schnitt an und führt Ports erst ein, wenn der Schmerz real wird. Das Refactoring von einer sauberen Schichtung zu Ports und Adaptern ist deutlich günstiger als das Aufräumen eines Systems, das von Anfang an überstrukturiert war.\nDie Grundlagen dazu stehen im Artikel Hexagonale Architektur: Ports und Adapter an einem kleinen Beispiel.\n","permalink":"https://blog.groscyk.de/posts/wann-hexagonal-overengineering/","summary":"Kosten und Nutzen ehrlich gegenübergestellt, mit einer Checkliste für die Entscheidung.","title":"Wann Hexagonal Overengineering ist"},{"content":"Dieser Blog entsteht in Zusammenarbeit mit einer KI. Das offen zu sagen, ist mir wichtig. Wichtiger ist die Frage, wofür ich sie einsetze und wofür nicht.\nDas Problem Generische KI-Texte über Architektur gibt es im Überfluss: korrekt, glatt und austauschbar. Wenn ich die KI einfach „einen Artikel über Hexagonale Architektur\u0026quot; schreiben lasse, entsteht genau das. Mein Beitrag fehlt darin.\nDie Aufgabenteilung Von mir Von der KI These, Haltung, Erfahrungen Rückfragen und Gliederung Rohmaterial: Stichpunkte, Code, Zahlen Erster Entwurf aus genau diesem Material Überarbeitung in meiner Stimme Faktencheck, Lektorat, Kürzen Entscheidung, was veröffentlicht wird Diagramme (z. B. Mermaid) Der Ablauf flowchart TD A[\"Ich: These und Rohmaterial\"] --\u003e B[\"KI: Rückfragen und Gliederung\"] B --\u003e C[\"KI: Entwurf aus meinem Material\"] C --\u003e D[\"Ich: Überarbeiten, Generisches streichen\"] D --\u003e E[\"KI: Faktencheck und Lektorat\"] E --\u003e F{\"Würde ich das so sagen?\"} F -- nein --\u003e D F -- ja --\u003e G[\"Veröffentlichen\"] Entscheidend ist die Schleife an der Raute: Ein Text geht erst raus, wenn ich jede Aussage vertreten kann.\nMeine Regel Was ich nicht selbst erlebt oder verstanden habe, behaupte ich nicht. Die KI darf formulieren und strukturieren, aber keine Erfahrungen für mich erfinden. Wo es gut funktioniert Eine vage Idee in eine Gliederung verwandeln Gegenargumente finden, an die ich nicht gedacht habe Lange Absätze straffen Diagramme als Text (Mermaid) erzeugen und anpassen Wo es nicht funktioniert Eine eigene Haltung entwickeln Konkrete Projekterfahrung ersetzen Fakten ungeprüft übernehmen: KI formuliert Falsches genauso souverän wie Richtiges Deshalb prüfe ich Zahlen, Zitate und technische Aussagen immer selbst nach.\n","permalink":"https://blog.groscyk.de/posts/mit-ki-schreiben/","summary":"Die KI schreibt nicht für mich, sondern mit mir. Der Ablauf, die Aufgabenteilung und warum ich die Nutzung offenlege.","title":"Mit KI schreiben, ohne generisch zu klingen: der Workflow hinter diesem Blog"},{"content":"Ich bin Jarek, Senior Software Engineer und Architekt, wohne in der Nähe von Berlin und arbeite remote als Berater.\nMein Informatikstudium (B.Sc.) habe ich an der TU Berlin abgeschlossen. Zertifiziert bin ich als iSAQB Certified Professional for Software Architecture und als AWS Certified Developer – Associate.\nWorum es hier geht In diesem Blog schreibe ich über Software-Architektur aus der Praxis:\nArchitekturstile und ihre Trade-offs (Hexagonal, Schichten, Modulith) Entscheidungen dokumentieren und nachvollziehbar machen Migrationen, die nicht auf der grünen Wiese stattfinden KI im Entwickleralltag, vom Sparringspartner bis zu RAG-Anwendungen Wie die Artikel entstehen Die Artikel entstehen zusammen mit einer KI. Thesen, Erfahrungen und Beispiele kommen von mir, die KI hilft bei Gliederung, Diagrammen und Lektorat. Wie genau das abläuft, beschreibe ich im Artikel über den Workflow.\nKontakt Schreib mir gern, wenn du Fragen hast oder anderer Meinung bist. Kritik an meinen Thesen ist ausdrücklich erwünscht.\n","permalink":"https://blog.groscyk.de/about/","summary":"\u003cp\u003eIch bin Jarek, Senior Software Engineer und Architekt, wohne in der Nähe von Berlin und arbeite remote als Berater.\u003c/p\u003e\n\u003cp\u003eMein Informatikstudium (B.Sc.) habe ich an der TU Berlin abgeschlossen. Zertifiziert bin ich als \u003cstrong\u003eiSAQB Certified Professional for Software Architecture\u003c/strong\u003e und als \u003cstrong\u003eAWS Certified Developer – Associate\u003c/strong\u003e.\u003c/p\u003e\n\u003ch2 id=\"worum-es-hier-geht\"\u003eWorum es hier geht\u003c/h2\u003e\n\u003cp\u003eIn diesem Blog schreibe ich über Software-Architektur aus der Praxis:\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eArchitekturstile und ihre Trade-offs (Hexagonal, Schichten, Modulith)\u003c/li\u003e\n\u003cli\u003eEntscheidungen dokumentieren und nachvollziehbar machen\u003c/li\u003e\n\u003cli\u003eMigrationen, die nicht auf der grünen Wiese stattfinden\u003c/li\u003e\n\u003cli\u003eKI im Entwickleralltag, vom Sparringspartner bis zu RAG-Anwendungen\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2 id=\"wie-die-artikel-entstehen\"\u003eWie die Artikel entstehen\u003c/h2\u003e\n\u003cp\u003eDie Artikel entstehen zusammen mit einer KI. Thesen, Erfahrungen und Beispiele kommen von mir, die KI hilft bei Gliederung, Diagrammen und Lektorat. Wie genau das abläuft, beschreibe ich im \u003ca href=\"https://blog.groscyk.de/posts/mit-ki-schreiben/\"\u003eArtikel über den Workflow\u003c/a\u003e.\u003c/p\u003e","title":"Über mich"}]