Microservices-Architekturdiagramm: Ein Beispiel und sieben Regeln, damit es lesbar bleibt

Bitte ein Team, seine Microservices zu zeichnen, und du bekommst oft dasselbe Bild: dreißig Boxen, jede mit jeder verbunden, Pfeile ohne Beschriftung. Es stimmt, und es beantwortet keine einzige Frage, die irgendjemand hat. Unter Entwicklern heißt so etwas Todesstern-Diagramm.

Ein nützliches Microservices-Architekturdiagramm ist eine Reihe von Entscheidungen darüber, was man zeigt. Dieser Guide erklärt an einem Beispiel, einem Onlineshop mit fünf Services, die sieben Regeln, die ein solches Diagramm lesbar machen. Dieselben Regeln funktionieren, ob du fünf Services hast oder fünfzig.

Was das Diagramm beantworten muss

Schreib die Fragen auf, bevor du zeichnest. Ein gutes Microservices-Diagramm beantwortet fünf davon auf einen Blick:

1. Wo kommen Requests herein? Clients, das API-Gateway, Backends for Frontends.
2. Welcher Service besitzt welche Daten? Jede Datenbank sollte genau einen Owner haben.
3. Wer ruft wen synchron auf? Diese Aufrufe teilen sich Latenz und Ausfälle.
4. Was passiert asynchron? Events und Queues entkoppeln Services zeitlich.
5. Was liegt außerhalb unserer Kontrolle? Zahlungsanbieter, E-Mail-Dienste, Partner-APIs.

Was bei keiner dieser Fragen hilft, ob Box oder Pfeil, gehört wahrscheinlich in ein anderes Diagramm.

Das Beispiel: ein Onlineshop mit fünf Services

Der Shop hat Web- und Mobile-Clients, ein API-Gateway und fünf Services:

• Catalog liefert Produkte aus seiner eigenen PostgreSQL-Datenbank aus.
• Cart hält Warenkörbe in Redis.
• Orders legt Bestellungen in seiner eigenen PostgreSQL-Datenbank an und veröffentlicht OrderPlaced im Kafka-Topic orders.
• Payments konsumiert OrderPlaced, belastet die Karte über Stripe, speichert das Ergebnis und veröffentlicht PaymentSucceeded oder PaymentFailed im Topic payments.
• Notifications konsumiert das Topic payments und verschickt über einen E-Mail-Anbieter eine Zahlungsbestätigung oder einen Hinweis, dass die Zahlung fehlgeschlagen ist.

Auch Orders konsumiert das Topic payments, um eine Bestellung als bezahlt zu markieren. Niemand ruft Payments direkt auf; der Checkout ist eine Kette von Events. Genau diese Designentscheidung muss das Diagramm sichtbar machen:

Lies es von links nach rechts: Das Gateway ist der einzige Einstiegspunkt, durchgezogene Pfeile sind synchrone Aufrufe, gestrichelte Pfeile sind Events über benannte Topics, und jede Datenbank hängt an genau einem Service.

Sieben Regeln für ein lesbares Microservices-Diagramm

1. Bei den Einstiegspunkten anfangen

Zeichne zuerst links die Clients und das API-Gateway. Sie geben die Leserichtung vor und zeigen, welche Services überhaupt von außen erreichbar sind. Ein Service, zu dem kein Pfad vom Gateway führt, ist intern, und das sollte man sehen.

2. Jede Datenbank an ihren Owner hängen

Setz jeden Datenspeicher neben den einen Service, dem er gehört, und verbinde nur diesen Service. Teilen sich heute zwei Services eine Datenbank, zeichne das ebenfalls. Das ist ein bekannter Architektur-Smell, und ein Diagramm, das ihn versteckt, macht die nächste Migration schwerer planbar.

3. Synchrone Aufrufe und Events trennen

Nutze zwei Linienstile und erkläre sie in einer Legende: durchgezogen für Request und Response (REST, gRPC), gestrichelt für Nachrichten über einen Broker. Zeichne die Topics oder Queues als Nodes. Eine einzige „Event-Bus“-Box, an der alle Services hängen, verschleiert, wer was produziert und wer was konsumiert.

4. Jede Kante mit dem beschriften, was darüber fließt

GET /products, POST /orders, OrderPlaced, PaymentFailed. Ein Label macht aus einem Pfeil einen Vertrag, und genau danach sucht man im Diagramm während eines Incidents.

5. Nach Domäne gruppieren, nicht nach Technologie

Wenn du Frames brauchst, gruppiere die Services nach fachlicher Domäne oder zuständigem Team: Einkauf, Checkout, Kundenkommunikation. Frames wie „Node.js-Services“ oder „Java-Services“ beantworten eine Frage, die niemand stellt.

6. Infrastruktur in eine eigene Sicht auslagern

Pods, Sidecars, Service Meshes und Dashboards sind wichtig, aber nicht in der logischen Sicht. Zeichne das Deployment in einem separaten Diagramm, zum Beispiel einem Kubernetes-Architekturdiagramm, und verlinke beide miteinander.

7. Einen kritischen Flow zeigen

Wähle den Flow, mit dem das Geld verdient wird, hier den Checkout, und mach ihn leicht nachvollziehbar: Nummeriere die Schritte an den Kanten oder hebe seinen Pfad hervor. Ein Flow pro Diagramm; ein zweiter Flow bekommt seine eigene Kopie der Sicht.

Wenn das System für ein Diagramm zu groß ist

Ab etwa zwanzig Boxen solltest du aufteilen. Ein Muster, das sich bewährt:

• Ein Landschaftsdiagramm mit den Domänen als Frames und nur den wichtigsten Verbindungen zwischen ihnen.
• Ein Diagramm pro Domäne mit ihren Services, Datenspeichern und Topics, gezeichnet nach den Regeln oben.
• Flow-Diagramme für die wenigen Journeys, auf die es ankommt, etwa Checkout oder Registrierung.

Das passt sauber zum C4-Modell: Das Landschaftsdiagramm entspricht ungefähr einer Systemkontext-Sicht, und jedes Domänendiagramm ist eine Container-Sicht, in der Services und ihre Datenbanken die Container sind.

Häufige Fehler

• Pfeile ohne Beschriftung. Leser raten, und jeder rät anders.
• Das Gateway hängt an Datenbanken. Wenn es wirklich eine Datenbank liest, ist das eine Designentscheidung, die man besprechen sollte, und keine Abkürzung zum Einzeichnen.
• Sichten vermischen. Pods, AWS-Services und Business Capabilities auf einem Canvas führen dazu, dass niemand mehr irgendetwas davon lesen kann.
• Den Broker verstecken. Kafka ist kein Rohr; Topics haben Namen, Owner und Consumer.
• Ein Snapshot, der sich nie ändert. Ein Diagramm aus der letzten Re-Architektur ist ein historisches Dokument. Versieh es mit einem Datum oder halte es live.

In Archboard nachbauen

Archboard hat Node-Packs für jeden Teil dieses Diagramms, sodass Services, Speicher und Topics typisierte Nodes mit Ports sind statt gleich aussehender Boxen:

1. Melde dich mit Google oder GitHub an und leg ein Diagramm an.
2. Füge für die Clients einen Kasten aus dem Basis-Pack und ein API-Gateway aus dem Cloud-Pack hinzu.
3. Füge die Services als Container-Nodes aus dem C4-Modell-Pack hinzu, mit Sprache oder Framework im Feld Technologie.
4. Füge Postgres und Redis aus dem Daten-Pack neben ihren Ownern hinzu, dazu Thema-Nodes für orders und payments.
5. Füge für Stripe und den E-Mail-Anbieter Nodes vom Typ Externes System aus dem C4-Modell-Pack hinzu.
6. Verbinde die Ports. Lass synchrone Aufrufe durchgezogen, stell Events auf gestrichelt um und beschrifte dann jede Kante.
7. Teile den Live-Link mit dem Team oder bette das Diagramm mit Pro in deine Doku ein.

Das Beispiel oben hat 15 Diagramm-Nodes und passt damit in den Free-Plan. Für verwandte Beispiele öffne /examples/kubernetes-microservices für die Deployment-Seite und /examples/api-gateway-infographic für eine Infografik zum Gateway-Pattern.

FAQ

Wie viele Services sollte ein Diagramm zeigen? So viele, wie du ohne Zoomen lesen kannst, meist bis zu etwa zwanzig Boxen. Darüber hinaus teilst du nach Domänen auf und behältst eine Landschaftssicht als oberste Ebene.

Sollte ich für Microservices das C4-Modell verwenden? Das funktioniert gut. Services und ihre Datenbanken werden zu Containern in einer Container-Sicht. Manche Teams modellieren jeden Service mit eigenem, unabhängigem Owner als eigenes Softwaresystem; entscheide dich für eine Konvention und halte sie schriftlich fest.

Wie zeige ich Kubernetes, das Service Mesh und das Monitoring? In einem separaten Deployment-Diagramm. Die logische Sicht beantwortet, wer mit wem spricht; die Deployment-Sicht beantwortet, wo es läuft.

Sollten Events vom Consumer zum Topic zeigen, weil Consumer pullen? Zeichne die Richtung, in die die Daten fließen, vom Producer zum Topic und weiter zum Consumer, und vermerke, dass Consumer pullen, wenn das für die Diskussion wichtig ist.

Wie halte ich das Diagramm aktuell? Gib dem Diagramm einen Owner, aktualisiere es im selben Pull Request wie die Änderung und verlinke das Live-Diagramm aus deiner Doku, statt Screenshots einzufügen.

Kostenlos starten — ein Seat, keine Kreditkarte.