Hexagonale, Onion- und Clean Architecture

Eine Idee, drei Namen

Hexagonale Architektur, Onion-Architektur und Clean Architecture sind drei Formulierungen einer Idee: Die Geschäftslogik kommt ins Zentrum, wird unabhängig von Benutzeroberflächen, Datenbanken, Frameworks und externen Diensten gemacht, und alle Quellcode-Abhängigkeiten zeigen auf sie. Sie beschreiben die innere Struktur einer Anwendung und lassen sich daher mit jedem Deployment-Stil kombinieren: einem einzelnen Monolithen, einem modularen Monolithen, dessen Module jeweils so gebaut sind, oder einem Microservice.

Sie entstanden aus Frust über die klassische Schichtenarchitektur. Im Schichtenstil aus Abschnitt 5.2 hängt die Geschäftsschicht von der Persistenzschicht ab, die von der Datenbank abhängt, sodass Geschäftsregeln am Ende von Tabellen und objektrelationalem Mapping geprägt sind und das Testen einer Regel das Starten einer Datenbank bedeutet. Die Stilfamilie in diesem Abschnitt kehrt diese Abhängigkeit mit dem Prinzip der Abhängigkeitsumkehr um: Der Geschäftscode deklariert die Schnittstellen, die er braucht, und der Infrastrukturcode implementiert sie. Das Prinzip selbst behandelt Abschnitt 3.5; dieser Abschnitt zeigt die darauf aufbauenden Architekturen.

Hexagonale Architektur: Ports and Adapters

Alistair Cockburn beschrieb die Idee zuerst im Wiki des Portland Pattern Repository und verfasste 2005 einen Artikel darüber unter dem anschaulicheren Namen Ports and Adapters. Seine erklärte Absicht war, eine Anwendung gleichermaßen von Benutzern, Programmen, automatisierten Tests oder Batch-Skripten steuern zu lassen und sie isoliert von ihren späteren Datenbanken und Geräten zu entwickeln und zu testen. 2024 veröffentlichten er und Juan Manuel Garrido de Paz ein kurzes Buch, Hexagonal Architecture Explained, das das Muster neu darlegt.

Ein Port ist ein zweckgerichtetes Gespräch zwischen der Anwendung und der Außenwelt, ausgedrückt als Schnittstelle: „eine Bestellung aufgeben“, „Bestellungen speichern“, „eine Karte belasten“. Ein Adapter ist der Code, der zwischen einem Port und einer bestimmten Technologie übersetzt: ein HTTP-Controller, ein SQL-Repository, das SDK eines Zahlungsanbieters, ein Kommandozeilenskript, ein In-Memory-Fake. Ein Port kann viele Adapter haben. Die Anwendung im Hexagon kennt nur ihre Ports.

Das Hexagon hat als Form keine Bedeutung; Cockburn wählte es, um dem Bild der Schichten von oben nach unten zu entkommen und Platz zu lassen, auf jeder Seite mehrere Ports zu zeichnen. Entscheidend sind die Grenze zwischen innen und außen und die Asymmetrie zwischen zwei Arten von Ports.

Treibende und getriebene Seite

Treibende (primäre) Ports und Adapter sitzen im üblichen Bild links. Ein treibender Adapter nimmt eine Anfrage eines primären Akteurs entgegen (der Browser eines Nutzers, eine Mobil-App, ein anderes System, ein Test, ein geplanter Job) und ruft einen treibenden Port auf, der die eigene API der Anwendung ist: in der Praxis ein Use Case wie PlaceOrder. Der Adapter macht aus HTTP, einer Nachricht oder einem Kommandozeilenargument einen Aufruf mit Domänenwerten und aus dem Ergebnis wieder eine Antwort.

Getriebene (sekundäre) Ports und Adapter sitzen rechts. Die Anwendung ruft sie auf, wenn sie etwas von der Außenwelt braucht: eine Bestellung speichern, eine Karte belasten, eine Benachrichtigung senden, die Uhrzeit lesen. Der Port ist eine Schnittstelle, die der Anwendung gehört und in ihren Begriffen geschrieben ist (OrderRepository.save(order)), und ein getriebener Adapter implementiert sie für eine Technologie (PostgreSQL, die API eines Kartenanbieters, ein SMS-Gateway). Hier geschieht die Abhängigkeitsumkehr: Zur Laufzeit ruft die Anwendung den Adapter auf, aber im Quellcode hängt der Adapter von der Schnittstelle der Anwendung ab, nicht umgekehrt.

Cockburns Originaltext spricht von primären und sekundären Akteuren; die Begriffe treibend und getrieben sind heute verbreiteter, und er verwendet sie selbst. Die Unterscheidung ist wichtig für das Testen: Treibende Ports werden von Test-Harnesses angesprochen, die als Nutzer auftreten, und getriebene Ports werden durch Test Doubles ersetzt. Sie ist auch für Änderungen wichtig: Neue Kanäle (ein Sprachassistent, eine Partner-API) kommen als neue treibende Adapter hinzu, neue Infrastruktur als neue getriebene Adapter.

Irgendjemand muss die Adapter erzeugen und in die Anwendung einstecken. Das geschieht in einem einzigen Composition Root, typischerweise dem Startcode des Programms, dem einzigen Teil des Systems, der jeden Adapter kennt. Ein Dependency-Injection-Framework kann diese Arbeit übernehmen, aber einfache Konstruktoraufrufe in main sind oft klarer.

Onion-Architektur

Jeffrey Palermo beschrieb die Onion-Architektur in einer Reihe von Blogbeiträgen ab Juli 2008, gedacht für langlebige Geschäftsanwendungen mit umfangreichem Verhalten (für kleine Websites riet er davon ab). Er zeichnete konzentrische Ringe: das Domänenmodell im Zentrum, Domain Services darum, Application Services um diese und einen äußeren Ring mit Benutzeroberfläche, Infrastruktur (einschließlich der Datenbank) und Tests. Seine zentralen Grundsätze sind, dass die Anwendung um ein unabhängiges Objektmodell herum gebaut wird, dass innere Schichten Schnittstellen definieren, die äußere Schichten implementieren, dass alle Kopplung zum Zentrum hin verläuft und dass der Anwendungskern getrennt von der Infrastruktur kompiliert und ausgeführt werden kann.

Im Vergleich zur hexagonalen Architektur fügt Onion benannte Ringe innerhalb der Anwendung hinzu und macht einen Punkt explizit, den Cockburns Bild offenlässt: Die Datenbank ist nicht das Fundament des Systems, sondern ein externer Dienst am Rand. Repository-Schnittstellen liegen im Kern; ihre Implementierungen liegen im Infrastrukturring.

Clean Architecture und die Abhängigkeitsregel

Robert C. Martin veröffentlichte „The Clean Architecture“ im August 2012 in seinem Blog als Synthese aus hexagonaler Architektur, Onion-Architektur und anderen ähnlichen Vorschlägen und baute es 2017 zum Buch Clean Architecture aus. Sein Bild hat vier Ringe. Entitäten enthalten unternehmensweite Geschäftsregeln. Use Cases enthalten anwendungsspezifische Regeln, die Entitäten orchestrieren. Interface Adapters wandeln Daten zwischen der Form, die die Use Cases brauchen, und der Form, die externe Instanzen brauchen: Controller, Presenter und Gateways. Frameworks und Treiber bilden den äußeren Ring: das Web-Framework, die Datenbank, die UI.

Die Abhängigkeitsregel hält alles zusammen: Quellcode-Abhängigkeiten zeigen nur nach innen, und nichts in einem inneren Ring darf etwas benennen, das in einem äußeren Ring deklariert ist, sei es eine Klasse, eine Funktion oder ein Datenformat. Muss die Steuerung nach außen fließen (ein Use Case speichert eine Bestellung), deklariert der innere Ring eine Schnittstelle, und der äußere Ring implementiert sie. Daten, die eine Grenze überqueren, sollten einfache Strukturen in den Begriffen des inneren Rings sein, nie eine Datenbankzeile oder ein HTTP-Request-Objekt. Martin argumentiert außerdem, dass die oberste Struktur den Zweck des Systems (Bestellungen, Zahlungen, Lieferungen) zeigen sollte statt seines Frameworks, eine Idee, die er Screaming Architecture nennt.

Ein Use Case mit einem Port und zwei Adaptern

Das folgende Python-Beispiel implementiert den Use Case PlaceOrder der Essenslieferplattform auf hexagonale Weise. Das erste Snippet ist das Innere: eine kleine Domänenklasse, zwei getriebene Ports, geschrieben als typing.Protocol-Klassen, und der Use Case, der als treibender Port dient. Das zweite Snippet ist das Äußere: ein PostgreSQL-Adapter und ein In-Memory-Test-Double, die denselben Port implementieren. Das dritte zeigt, warum das wichtig ist: ein schneller Unit-Test und der Composition Root, in dem die Produktionsadapter eingesteckt werden.

from dataclasses import dataclass
from decimal import Decimal
from typing import Protocol

@dataclass
class Order:
    id: str
    total: Decimal
    status: str = "new"

class OrderRepository(Protocol):        # driven port
    def save(self, order: Order) -> None: ...

class PaymentGateway(Protocol):         # driven port
    def charge(self, order_id: str, amount: Decimal) -> bool: ...

class PlaceOrder:                       # driving port + use case
    def __init__(self, orders: OrderRepository, payments: PaymentGateway):
        self.orders, self.payments = orders, payments

    def __call__(self, order_id: str, total: Decimal) -> Order:
        if total <= 0:
            raise ValueError("empty basket")
        order = Order(order_id, total)
        order.status = "paid" if self.payments.charge(order_id, total) else "payment-failed"
        self.orders.save(order)
        return order

class PostgresOrderRepository:          # real driven adapter
    def __init__(self, conn):
        self.conn = conn
    def save(self, order):
        with self.conn.cursor() as cur:
            cur.execute(
                "INSERT INTO orders (id, total, status) VALUES (%s, %s, %s) "
                "ON CONFLICT (id) DO UPDATE SET status = EXCLUDED.status",
                (order.id, order.total, order.status))
        self.conn.commit()

class InMemoryOrderRepository:          # test double, same port
    def __init__(self):
        self.saved = {}
    def save(self, order):
        self.saved[order.id] = order

class DecliningPayments:
    def charge(self, order_id, amount): return False

def test_failed_payment_is_recorded():
    orders = InMemoryOrderRepository()
    place = PlaceOrder(orders, DecliningPayments())
    place("A-17", Decimal("23.50"))
    assert orders.saved["A-17"].status == "payment-failed"

# composition root (main.py): the only place that knows every adapter
# place_order = PlaceOrder(PostgresOrderRepository(conn), CardProviderGateway(key))
# app.add_route("/orders", make_rest_controller(place_order))   # driving adapter

Beachten Sie, was der Use Case nicht enthält: kein SQL, keine HTTP-Statuscodes, keine anbieterspezifischen Exception-Typen, keine Framework-Decorators. Der Test läuft in Millisekunden und deckt einen Fall ab (eine abgelehnte Zahlung), der sich gegen die Sandbox eines echten Anbieters nur umständlich herstellen ließe. Der PostgreSQL-Adapter braucht eigene Tests, doch das sind fokussierte Integrationstests einer Klasse gegen eine echte Datenbank, keine Tests von Geschäftsregeln. Das ist der Testbarkeitsnutzen, der in Abschnitt 2.6 beschrieben ist: Steuerbarkeit und Beobachtbarkeit durch injizierte Abhängigkeiten.

Kosten, Kritik und wann man sie einsetzt

Der Nutzen ist real, die Kosten sind es auch. Jeder Port ist eine zusätzliche Schnittstelle; jede Grenze braucht unter Umständen Mapping-Code, um etwa zwischen einer ORM-Entität, einem Domänenobjekt und einer API-Antwort umzuwandeln. Für eine Anwendung, die überwiegend Formularfelder in Tabellen schiebt, mit wenig Logik dazwischen, fügt diese Struktur Dateien hinzu, ohne Schutz hinzuzufügen, und die Konventionen eines Frameworks (ein Active-Record-Modell, eine generierte Admin-Oberfläche) liefern womöglich schneller ein besseres Ergebnis. Manche erfahrenen Praktiker argumentieren, dass strenge Varianten der Clean Architecture zu viel Indirektion erzeugen und die meisten Teams ihre Datenbank nie austauschen; andere entgegnen, dass der Hauptnutzen nicht im Austausch von Technologie liegt, sondern in schnellen, verlässlichen Tests und in Geschäftscode, den man lesen kann, ohne das Framework zu kennen. Beide haben in unterschiedlichen Kontexten recht.

Setzen Sie sie ein, wenn die Geschäftslogik umfangreich ist und die aktuellen Frameworks überdauern wird; wenn das System mit externen Diensten integriert ist, die sich wahrscheinlich ändern; wenn schnelle, isolierte Tests der Geschäftsregeln wichtig sind; und als innere Struktur der Module eines modularen Monolithen oder von Services, die mit Domain-Driven Design gebaut sind (Abschnitt 5.7). Seien Sie vorsichtig bei einfachen CRUD-Anwendungen, Prototypen und kurzlebigen Werkzeugen, wo die Standardstruktur des Frameworks meist ausreicht. Ein pragmatischer Mittelweg ist verbreitet: Ports für externe Dienste und alles, was sich wahrscheinlich ändert, und anderswo die Annehmlichkeiten des Frameworks.

Die Abhängigkeitsregel durchsetzen

Wie bei Schichten erodiert die Regel, wenn keine Maschine sie prüft. In Python kann import-linter die Ringe als layers-Vertrag deklarieren (Adapter über Anwendung über Domäne) und forbidden-Verträge hinzufügen, die verhindern, dass die Domänen- und Anwendungspakete Web-Frameworks, Datenbanktreiber oder SDKs importieren. In Java hat ArchUnit eine fertige Regel onionArchitecture(), in der Sie die Pakete für Domänenmodell, Domain Service, Application Service und Adapter benennen, und sie lässt einen Test fehlschlagen, wenn eine Abhängigkeit nach außen zeigt. Den Code in getrennte Build-Module aufzuteilen (ein Domänenmodul ganz ohne Framework-Abhängigkeiten) macht Abhängigkeiten nach außen unkompilierbar, und das ist die stärkste Prüfung von allen. Diese Prüfungen sind Beispiele für die Fitness Functions, die Kapitel 11 behandelt.

Eine Paketstruktur, die die Regel sichtbar macht, hilft beim Review: zum Beispiel orders/domain, orders/application (Use Cases und Ports) und orders/adapters/{rest,postgres,payments}. Zuerst nach Geschäftsbereich und dann nach Ring zu gliedern, hält die Struktur an den Domänengrenzen der Abschnitte 5.3 und 5.7 ausgerichtet.