Diagramm als Code: UML-Sequenzdiagramme mit PlantUML und VPasCode

Ein UML Sequenzdiagrammzeigt, wie Teilnehmer im Laufe der Zeit interagieren. Es ist nützlich zur Dokumentation eines Anwendungsfalls, API-Fluss, Geschäftsprozess oder Systemszenario. Die Zeit verläuft in der Regel von oben nach unten; die horizontale Anordnung zeigt, wer teilnimmt, nicht ein genaues Maß für die vergangene Zeit.

PlantUMLermöglicht es Ihnen, das Diagramm als Text zu beschreiben. Visual Paradigms VPasCode-Editor kombiniert einen Code-Editor mit einer Live-Vorschau und KI-Unterstützung zum Erstellen, Ändern und Korrigieren von Diagrammcode. Ein guter Arbeitsablauf besteht darin, KI für einen ersten Entwurf zu verwenden und dann das PlantUML selbst zu überprüfen und zu verfeinern.

1. Die Grundstruktur

Ein PlantUML-Sequenzdiagrammbeginnt mit @startuml und endet mit @enduml. Teilnehmer werden normalerweise vor den Nachrichten aufgelistet, damit Sie deren Namen und Reihenfolge steuern können.

@startuml
actor Kunde
participant Browser
participant "Bestell-API" als API
database "Bestell-DB" als DB

Kunde -> Browser: Bestellung aufgeben
Browser -> API: POST /orders
API -> DB: Bestellung speichern
DB --> API: Bestell-ID
API --> Browser: 201 Created
Browser -> Kunde: Bestätigung anzeigen
@enduml

Das angezeigte Label des Teilnehmers kann in Anführungszeichen gesetzt werden, mit als einen kürzeren Alias für die Verwendung in Nachrichten bereitstellen. Häufig verwendete Teilnehmer-Schlüsselwörter sind Akteur, Teilnehmer, Grenze, Steuerung, Entität, Datenbank, und Sammlungen. Verwenden Sie das Schlüsselwort, das die Rolle des Teilnehmers am besten beschreibt; es erzwingt keine bestimmte Architektur.

2. Nachrichten und Zeit lesen

Jede Nachricht wird als Absender, ein Pfeil, ein Empfänger und ein Label geschrieben. Die Reihenfolge der Nachrichtenzeilen bestimmt ihre vertikale Reihenfolge im Diagramm.

• -> ist ein durchgezogener Nachrichtenpfeil, der häufig für eine Anforderung oder einen Aufruf verwendet wird.

• --> ist ein gestrichelter Pfeil, der häufig für eine Antwort oder Rückgabe verwendet wird.

• ->> und -->> verwenden offene Pfeilköpfe in gängigen PlantUML-Stilen.

• : Text fügt das Nachrichtenlabel hinzu.

Wählen Sie eine konsistente Konvention für Aufrufe und Antworten. UML-Diagramme kommunizieren eine Interaktion; sie garantieren nicht automatisch, dass die Implementierung dem dargestellten Protokoll folgt.

3. Aktivierungen und Lebensdauern der Teilnehmer

Aktivierungen können anzeigen, wann ein Teilnehmer arbeitet. Verwenden Sie aktivieren und deaktivieren, oder die Abkürzung ++ und -- auf Nachrichtenpfeilen.

@startuml
actor User
participant "Login API" as API
database Users

User -> API: Anmelden
activate API
API -> Users: Konto finden
activate Users
Users --> API: Kontoeintrag
deactivate Users
API --> User: Login-Ergebnis
deactivate API
@enduml

Aktivierungen sind am nützlichsten, wenn sie verschachtelte Aufrufe oder Verantwortlichkeiten verdeutlichen. Vermeiden Sie es, sie mechanisch bei jeder Nachricht hinzuzufügen, wenn dies die Lesbarkeit des Diagramms erschwert.

4. Bedingungen, Alternativen und Wiederholung

Verwenden Sie kombinierte Fragmente, um den Kontrollfluss darzustellen. Das Fragment-Schlüsselwort beginnt den Block, sonst trennt Alternativen, wo zutreffend, und end schließt ihn. Bedingungsbedingungen werden in eckigen Klammern angegeben.

Alternative Pfade: alt und sonst

@startuml
actor Benutzer
participant "Login-API" als API
database Benutzer

Benutzer -> API: Benutzername und Passwort eingeben
API -> Benutzer: Anmeldeinformationen prüfen
Benutzer --> API: Übereinstimmungsergebnis

alt [Anmeldeinformationen gültig]
  API --> Benutzer: Sitzungstoken zurückgeben
sonst [Anmeldeinformationen ungültig]
  API --> Benutzer: Authentifizierungsfehler zurückgeben
end
@enduml

alt ist geeignet, wenn die Pfade sich gegenseitig ausschließen. Verwenden Sie Beschriftungen, die die Bedingungen klar machen.

Optionales Verhalten: opt

@startuml
actor Kunde
participant Checkout
participant "E-Mail-Dienst" als E-Mail

Kunde -> Checkout: Kauf abschließen
Checkout --> Kunde: Bestellbestätigung

opt [Kunde hat sich für E-Mails angemeldet]
  Checkout -> E-Mail: Beleg senden
  E-Mail --> Checkout: Akzeptiert
end
@enduml

Wiederholung: loop

@startuml
participant "Batch-Job" als Job
participant "Zahlungs-API" als API

loop [für jede ausstehende Zahlung]
  Job -> API: Zahlung einreichen
  API --> Job: Zahlungsergebnis
end
@enduml

Legen Sie die wiederholte Aktion innerhalb des Fragments fest und geben Sie die Schleifenbedingung oder den Geltungsbereich klar an.

5. Parallele und gruppierte Interaktionen

Verwenden Sie par wenn Interaktionen gleichzeitig stattfinden oder ihre Reihenfolge nicht von Bedeutung ist. Verwenden Sie group um eine Gruppe von Nachrichten zu kennzeichnen, ohne eine bestimmte Steuerflussstruktur zu implizieren.

@startuml
participant "Bestelldienst" as Orders
participant "Lagerdienst" as Inventory
participant "Benachrichtigungsdienst" as Notify

Orders -> Orders: Bestellung akzeptiert

par Lagerbestand reservieren
  Orders -> Inventory: Artikel reservieren
  Inventory --> Orders: Reservierungsergebnis
else Kunde benachrichtigen
  Orders -> Notify: Bestellupdate senden
  Notify --> Orders: Akzeptiert
end
@enduml

Verwenden Sie parnur dann, wenn Parallelität sinnvoll ist. Wenn eine Aktion abgeschlossen sein muss, bevor eine andere beginnt, zeigen Sie die Nachrichten stattdessen in einer Sequenz an.

6. Anmerkungen, Referenzen und visuelle Gruppierung

Anmerkungen können Annahmen, Einschränkungen oder Entscheidungen klären. Ein ref-Fragment kann Leser auf ein anderes Diagramm oder eine separat dokumentierte Interaktion verweisen.

@startuml
actor Kunde
participant "Checkout-Benutzeroberfläche" as UI
participant "Zahlungsdienst" as Pay
participant "Betrugsprüfung" as Fraud

Kunde -> UI: Für Bestellung bezahlen
UI -> Pay: Zahlung autorisieren
Pay -> Fraud: Transaktion bewerten

note right of Fraud
  Risikoregeln werden
  außerhalb dieser Interaktion verwaltet.
end note

Fraud --> Pay: Risikoegebnis
Pay --> UI: Autorisierungsergebnis
UI --> Kunde: Ergebnis anzeigen
@enduml

Anmerkungen sollten Kontext hinzufügen, anstatt Nachrichtenbeschriftungen zu wiederholen. Wenn das Diagramm überladen wird, teilen Sie es in fokussierte Szenarien auf und verwenden Sie Referenzen oder Dokumentationslinks, um sie zu verbinden.

7. Erstellen und Verfeinern von Diagrammen in VPasCode

VPasCode unterstützt die Bearbeitung von PlantUML mit Live-Vorschau sowie KI-gestützte Diagrammerstellung, Codeänderungen und Syntaxkorrekturen. Das genaue Interface und die Verfügbarkeit von Funktionen können sich ändern, aber der allgemeine Arbeitsablauf ist:

1. Öffnen Sie VPasCode und wählen Sie oder geben Sie PlantUML ein.

2. Beschreiben Sie die Interaktion oder fügen Sie einen PlantUML-Entwurf in den Editor ein.

3. Überprüfen Sie die gerenderte Vorschau, während Sie die Quelle verfeinern.

4. Bitten Sie die KI, eine spezifische Änderung vorzunehmen, z. B. “einen Pfad für ungültige Anmeldeinformationen unter Verwendung von ” hinzufügenalt.”

5. Überprüfen Sie den resultierenden Code und das Diagramm sowohl auf Syntax als auch auf Systemkorrektheit.

6. Exportieren oder teilen Sie das fertige Diagramm unter Verwendung der im Editor verfügbaren Optionen.

Ein nützlicher Prompt gibt der KI den Diagrammtyp, Akteure, Systemgrenzen, den Haupterfolgs Pfad, wichtige alternative Pfade und den Detaillierungsgrad vor. Zum Beispiel:

Erstellen Sie ein PlantUML-Sequenzdiagramm für einen Kunden, der sich in einer Web-App anmeldet. Enthalten Sie Browser, Login-API, Identitätsanbieter und Benutzerdatenbank. Zeigen Sie den erfolgreichen Anmeldepfad und eine Alternative für ein ungültiges Passwort. Verwenden Sie prägnante Beschriftungen und erfinden Sie keine weiteren Dienste außer diesen.

Betrachten Sie generierten Code als Entwurf. Überprüfen Sie, ob Teilnehmer, Pfeile, Bedingungen und Fehlerpfade das tatsächliche System widerspiegeln – nicht nur einen plausibel aussehenden Ablauf.

8. Ein ausführlicheres Beispiel: Checkout mit Zahlungsfehler

Dieses Beispiel kombiniert Teilnehmer-Aliasnamen, Aktivierungen und einen alternativen Pfad.

@startuml
Titel: Checkout und Zahlungsautorisation

Akteur Kunde
Grenze "Checkout-Benutzeroberfläche" als UI
Steuerung "Bestelldienst" als Orders
Teilnehmer "Zahlungs-Gateway" als Pay
Datenbank "Bestell-DB" als DB

Kunde -> UI: Checkout einreichen
UI -> Orders: Ausstehende Bestellung erstellen
Orders aktivieren

Orders -> DB: Ausstehende Bestellung speichern
DB --> Orders: Bestell-ID

Orders -> Pay: Zahlung autorisieren
Pay aktivieren

alt [Zahlung genehmigt]
  Pay --> Orders: Autorisierungscode
  Pay deaktivieren

  Orders -> DB: Bestellung als bestätigt markieren
  DB --> Orders: Aktualisiert
  Orders --> UI: Bestellung bestätigt
  UI --> Kunde: Bestätigung anzeigen
sonst [Zahlung abgelehnt]
  Pay --> Orders: Ablehnungsgrund
  Pay deaktivieren

  Orders -> DB: Bestellung als fehlgeschlagen markieren
  DB --> Orders: Aktualisiert
  Orders --> UI: Zahlung abgelehnt
  UI --> Kunde: Wiederholungsoption anzeigen
end

Orders deaktivieren
@enduml

Stellen Sie sicher, dass die Reihenfolge im Diagramm dem tatsächlichen Verhalten entspricht. Wenn das System die Bestellung beispielsweise erst nach erfolgreichem Autorisierungsprozess speichert, verschieben Sie die Datenbanknachrichten, um diesem Design zu entsprechen.

9. Praktische Modellierungsrichtlinien

• Halten Sie ein Diagramm fokussiert.Zeigen Sie ein Szenario oder eine eng verwandte Reihe von Pfaden. Trennen Sie tiefe Details ab, die von der Hauptinteraktion ablenken.

• Benennen Sie Teilnehmer nach ihrer Verantwortung.Bevorzugen Sie Beschriftungen wie “Bestelldienst” oder “Zahlungs-Gateway” statt vager Beschriftungen wie “System.

• “Zeigen Sie sinnvolle Grenzen.Unterscheiden Sie Benutzer, Client, interne Dienste, Datenbanken und externe Systeme, wenn dies den Lesern hilft, die Verantwortung zu verstehen.

• Verwenden Sie klare Nachrichtenbeschriftungen.Fügen Sie eine Operation, ein Ereignis oder ein wichtiges Ergebnis hinzu; vermeiden Sie Beschriftungen, die lediglich „Prozess“ sagen.

• Modellieren Sie relevante Fehlerpfade.Fügen Sie relevante Timeouts, Ablehnungen, Wiederholungsversuche oder Validierungsfehler hinzu, wenn sie das Szenario beeinflussen.

• Verwenden Sie Fragmente präzise. alt bedeutet alternative Pfade, opt bedeutet optionales Verhalten, loop bedeutet Wiederholung, und par bedeutet paralleles Verhalten.

• Vermeiden Sie Implementierungsdetails, die vom Wesentlichen ablenken.Diagrammen Sie nicht jeden Getter, jede interne Methode oder jedes Detail der unteren Ebene, es sei denn, das Publikum benötigt es.

• Halten Sie die Quelle wartbar.Verwenden Sie Aliase für lange Namen, eine konsistente Benennung und kurze Kommentare oder Hinweise für wichtige Annahmen.

10. Häufige Fehler und Überprüfungsliste

Wenn das Diagramm nicht gerendert wird, überprüfen Sie, dass @startuml und @enduml vorhanden sind, müssen Fragmentblöcke passende endAnweisungen, Aliase werden konsistent verwendet und alle Nachrichtenendpunkte verweisen auf definierte Teilnehmer. Überprüfen Sie auch, ob versehentlich Syntax aus einer anderen Diagrammsprache in die PlantUML-Quelle eingefügt wurde.

Bevor Sie teilen, überprüfen Sie zwei Dinge:

• Syntax:Wird es gerendert? Sind Fragmente geschlossen? Sind Teilnehmer und Aliase konsistent?

• Bedeutung:Sind die Teilnehmer und Nachrichtenrichtungen korrekt? Sind wichtige Fehlerpfade enthalten? Werden externe Systeme und Datenspeicher genau dargestellt?

Der stärkste Diagram-as-Code-Workflowverbindet lesbaren Quellcode, schnelles visuelles Feedback und Domänenüberprüfung. PlantUML bietet explizite Kontrolle über die Interaktionsnotation, während VPasCodedas Entwurfen und Iterieren beschleunigen kann; die letztgültige Autorität für die Genauigkeit des Diagramms bleibt das Systemverhalten, das es beschreiben soll.

Der Artikel ist auch in English, Español, فارسی, Français, Bahasa Indonesia, 日本語, Polski, Portuguese, Ру́сский, Việt Nam, 简体中文 and 繁體中文 verfügbar.