Diagramy jako kod: diagramy sekwencyjne UML z użyciem PlantUML i VPasCode

Diagram sekwencyjny PlantUML UML diagram sekwencyjnypokazuje, jak uczestnicy wchodzą ze sobą w interakcje w czasie. Jest przydatny do dokumentowania scenariusza użycia, przepływu API, procesu biznesowego lub scenariusza systemowego. Czas zazwyczaj płynie od góry do dołu; pozioma pozycja pokazuje, kto bierze udział, a nie precyzyjny pomiar upływu czasu.

PlantUMLumożliwia opisanie diagramu jako tekstu. Edytor VPasCode firmy Visual Paradigmłączy edytor kodu z podglądem na żywo i pomocą AI w generowaniu, modyfikowaniu i poprawianiu kodu diagramu. Dobrym przepływem pracy jest użycie AI do uzyskania pierwszego szkicu, a następnie samodzielne sprawdzenie i dopracowanie kodu PlantUML.

1. Podstawowa struktura

Diagram sekwencyjny PlantUML Diagram sekwencyjny PlantUMLzaczyna się od @startuml i kończy się na @enduml. Uczestnicy są zazwyczaj wymieniani przed wiadomościami, abyś mógł kontrolować ich nazwy i kolejność.

@startuml
actor Klient
participant Przeglądarka
participant "API zamówień" jako API
database "Baza danych zamówień" jako DB

Klient -> Przeglądarka: Złóż zamówienie
Przeglądarka -> API: POST /orders
API -> DB: Zapisz zamówienie
DB --> API: ID zamówienia
API --> Przeglądarka: 201 Created
Przeglądarka -> Klient: Pokaż potwierdzenie
@enduml

Wyświetlana etykieta uczestnika może być ujęta w cudzysłów, z jako zapewniając krótszy alias do użycia w wiadomościach. Typowe słowa kluczowe uczestników obejmują aktor, uczestnik, granica, kontrola, entitet, baza danych, oraz kolekcje. Użyj słowa kluczowego, które najlepiej oddaje rolę uczestnika; nie narzuca ono konkretnej architektury.

2. Odczytywanie wiadomości i czasu

Każda wiadomość jest zapisywana jako nadawca, strzałka, odbiorca i etykieta. Kolejność linii wiadomości określa ich kolejność pionową na diagramie.

• -> jest ciągłą strzałką wiadomości, powszechnie używaną do żądań lub wywołań.

• --> jest przerywaną strzałką, często używaną do odpowiedzi lub zwracania wartości.

• ->> oraz -->> używają otwartych główek strzałek w typowych stylach PlantUML.

• : tekst dodaje etykietę wiadomości.

Wybierz spójną konwencję dla wywołań i odpowiedzi. Diagramy UML komunikują interakcję; nie gwarantują one automatycznie, że implementacja przestrzega przedstawionego protokołu.

3. Aktywacje i czasy życia uczestników

Aktywacje mogą pokazywać, kiedy uczestnik wykonuje pracę. Użyj activate oraz deaktywuj, lub skrót ++ oraz -- na strzałkach wiadomości.

@startuml
aktor User
uczestnik "Login API" jako API
baza danych Users

User -> API: Podaj dane logowania
aktywuj API
API -> Users: Znajdź konto
aktywuj Users
Users --> API: Rekord konta
deaktywuj Users
API --> User: Wynik logowania
deaktywuj API
@enduml

Aktywacje są najbardziej przydatne, gdy wyjaśniają zagnieżdżone wywołania lub odpowiedzialność. Unikaj dodawania ich mechanicznie do każdej wiadomości, jeśli utrudniają czytanie diagramu.

4. Warunki, alternatywy i powtórzenia

Użyj fragmentów połączonych do pokazania przepływu sterowania. Słowo kluczowe fragment rozpoczyna blok, else oddziela alternatywy tam, gdzie jest to możliwe, oraz end zamyka go. Warunki strażnicze umieszcza się w nawiasach kwadratowych.

Alternatywne ścieżki: alt i else

@startuml
aktor User
uczestnik "Login API" jako API
baza danych Users

User -> API: Podaj nazwę użytkownika i hasło
API -> Users: Sprawdź dane uwierzytelniające
Users --> API: Wynik dopasowania

alt [dane uwierzytelniające poprawne]
  API --> User: Zwróć token sesji
else [dane uwierzytelniające niepoprawne]
  API --> User: Zwróć błąd uwierzytelniania
end
@enduml

alt jest odpowiednie, gdy ścieżki są wzajemnie wykluczające się. Używaj etykiet, które czynią warunki jasnymi.

Opcjonalne zachowanie: opt

@startuml
aktor Customer
uczestnik Checkout
uczestnik "Email Service" jako Email

Customer -> Checkout: Zakończ zakup
Checkout --> Customer: Potwierdzenie zamówienia

opt [klient wyraził zgodę na e-mail]
  Checkout -> Email: Wyślij paragon
  Email --> Checkout: Przyjęto
end
@enduml

Powtórzenie: pętla

@startuml
uczestnik "Zadanie partii" jako Job
uczestnik "API płatności" jako API

pętla [dla każdej oczekującej płatności]
  Job -> API: Złóż płatność
  API --> Job: Wynik płatności
koniec
@enduml

Umieść powtarzaną akcję wewnątrz fragmentu i wyraźnie określ warunek pętli lub jej zakres.

5. Interakcje równoległe i grupowane

Użyj par gdy interakcje zachodzą równolegle lub ich kolejność nie ma znaczenia. Użyj group aby oznaczyć zestaw wiadomości bez sugerowania konkretnej struktury przepływu sterowania.

@startuml
participant "Order Service" as Orders
participant "Inventory Service" as Inventory
participant "Notification Service" as Notify

Orders -> Orders: Order accepted

par Rezerwacja zapasów
  Orders -> Inventory: Rezerwuj przedmioty
  Inventory --> Orders: Wynik rezerwacji
else Powiadom klienta
  Orders -> Notify: Wyślij aktualizację zamówienia
  Notify --> Orders: Akceptacja
end
@enduml

Użyj partylko wtedy, gdy równoległość ma sens. Jeśli jedna akcja musi zakończyć się przed rozpoczęciem drugiej, pokaż wiadomości sekwencyjnie zamiast tego.

6. Notatki, odwołania i grupowanie wizualne

Notatki mogą wyjaśniać założenia, ograniczenia lub decyzje. Fragment ref może kierować czytelników do innego diagramu lub oddzielnie udokumentowanej interakcji.

@startuml
actor Customer
participant "Checkout UI" as UI
participant "Payment Service" as Pay
participant "Fraud Check" as Fraud

Customer -> UI: Zapłać za zamówienie
UI -> Pay: Autoryzuj płatność
Pay -> Fraud: Oceń transakcję

note right of Fraud
  Zasady ryzyka są utrzymywane
  poza tą interakcją.
end note

Fraud --> Pay: Wynik ryzyka
Pay --> UI: Wynik autoryzacji
UI --> Customer: Pokaż wynik
@enduml

Notatki powinny dodawać kontekst, a nie powtarzać etykiety wiadomości. Jeśli diagram stanie się przeładowany, podziel go na skoncentrowane scenariusze i użyj odwołań lub linków do dokumentacji, aby je połączyć.

7. Tworzenie i udoskonalanie diagramów w VPasCode

VPasCodeobsługuje edycję PlantUML z podglądem na żywo, a także generowanie diagramów wspomagane przez AI, modyfikację kodu oraz korektę składni. Dokładny interfejs i dostępność funkcji mogą się zmieniać, ale ogólny przepływ pracy wygląda następująco:

1. Otwórz VPasCode i wybierz lub wprowadź PlantUML.

2. Opisz interakcję lub wklej szkic PlantUML do edytora.

3. Sprawdzaj podgląd renderowania podczas udoskonalania źródła.

4. Poproś AI o wprowadzenie konkretnej zmiany, np. “dodaj ścieżkę dla nieprawidłowych danych uwierzytelniających przy użyciu “alt.”

5. Przejrzyj powstały kod i diagram pod kątem poprawności składni oraz poprawności systemu.

6. Eksportuj lub udostępnij gotowy diagram, korzystając z dostępnych w edytorze opcji.

Przydatne polecenie dostarcza AI typu diagramu, aktorów, granic systemu, głównej ścieżki sukcesu, ważnych ścieżek alternatywnych oraz poziomu szczegółowości. Na przykład:

Stwórz diagram sekwencji PlantUML dla klienta logującego się do aplikacji internetowej. Uwzględnij przeglądarkę, API logowania, dostawcę tożsamości i bazę danych użytkowników. Pokaż ścieżkę udanego logowania oraz alternatywę dla nieprawidłowego hasła. Używaj zwięzłych etykiet i nie wymyślaj usług poza tymi.

Traktuj wygenerowany kod jako szkic. Sprawdź, czy uczestnicy, strzałki, warunki i ścieżki błędów odzwierciedlają rzeczywisty system, a nie tylko prawdopodobnie wyglądający przepływ.

8. Bardziej szczegółowy przykład: finalizacja zamówienia z niepowodzeniem płatności

Ten przykład łączy aliasy uczestników, aktywacje i ścieżkę alternatywną.

@startuml
tytuł: Koszyk i autoryzacja płatności

aktor Klient
granica "Interfejs koszyka" jako UI
kontrola "Serwis zamówień" jako Orders
uczestnik "Brama płatności" jako Pay
baza danych "Baza zamówień" jako DB

Klient -> UI: Złóż zamówienie
UI -> Orders: Utwórz oczekujące zamówienie
aktywuj Orders

Orders -> DB: Zapisz oczekujące zamówienie
DB --> Orders: ID zamówienia

Orders -> Pay: Autoryzuj płatność
aktywuj Pay

alt [płatność zatwierdzona]
  Pay --> Orders: Kod autoryzacji
  dezaktywuj Pay

  Orders -> DB: Oznacz zamówione jako potwierdzone
  DB --> Orders: Zaktualizowano
  Orders --> UI: Zamówienie potwierdzone
  UI --> Klient: Pokaż potwierdzenie
else [płatność odrzucona]
  Pay --> Orders: Powód odrzucenia
  dezaktywuj Pay

  Orders -> DB: Oznacz zamówienie jako nieudane
  DB --> Orders: Zaktualizowano
  Orders --> UI: Płatność odrzucona
  UI --> Klient: Pokaż opcję ponowienia
end

dezaktywuj Orders
@enduml

Sprawdź, czy kolejność na diagramie odpowiada rzeczywistemu zachowaniu. Na przykład, jeśli system zapisuje zamówienie dopiero po pomyślnej autoryzacji, przenieś komunikaty dotyczące bazy danych, aby odzwierciedlić ten projekt.

9. Praktyczne wytyczne modelowania

• Utrzymuj skupienie diagramu.Pokaż jeden scenariusz lub ściśle powiązany zestaw ścieżek. Wyodrębnij głębokie szczegóły, które odciągają uwagę od głównej interakcji.

• Nazywaj uczestników według ich odpowiedzialności. Preferuj etykiety takie jak “Serwis zamówień” lub “Brama płatności” zamiast niejasnych etykiet takich jak “System.

• ” Pokazuj znaczące granice.Rozróżniaj użytkownika, klienta, usługi wewnętrzne, bazy danych i systemy zewnętrzne, gdy pomaga to czytelnikom zrozumieć odpowiedzialność.

• Używaj jasnych etykiet komunikatów.Dołącz operację, zdarzenie lub istotny wynik; unikaj etykiet, które jedynie mówią „proces”.

• Modeluj ścieżki błędów, które mają znaczenie.Dołącz odpowiednie limity czasowe, odrzucenia, ponawiania prób lub błędy walidacji, gdy wpływają one na scenariusz.

• Używaj fragmentów precyzyjnie. altoznacza alternatywne ścieżki, optoznacza zachowanie opcjonalne, loopoznacza powtarzanie, a paroznacza zachowanie równoległe.

• Unikaj szumu implementacyjnego.Nie diagramuj każdego gettera, metody wewnętrznej ani szczegółu niskiego poziomu, chyba że odbiorcy tego potrzebują.

• Utrzymuj źródło w stanie łatwym do utrzymania.Używaj aliasów dla długich nazw, spójnego nazewnictwa oraz krótkich komentarzy lub uwag dla istotnych założeń.

10. Typowe błędy i lista kontrolna przeglądu

Jeśli diagram nie zostanie wyrenderowany, sprawdź, czy @startuml oraz @enduml są obecne, bloki fragmentów mają pasujące koniec instrukcji, aliasy są używane spójnie, a wszystkie punkty końcowe wiadomości odnoszą się do zdefiniowanych uczestników. Sprawdź również, czy przypadkowo nie wklejono do kodu źródłowego PlantUML składni z innego języka tworzenia diagramów.

Przed udostępnieniem sprawdź dwie rzeczy:

• Składnia: Czy diagram się renderuje? Czy fragmenty są zamknięte? Czy uczestnicy i aliasy są spójne?

• Znaczenie: Czy uczestnicy i kierunki wiadomości są poprawne? Czy uwzględniono ważne ścieżki błędów? Czy systemy zewnętrzne i magazyny danych są przedstawione poprawnie?

Najmocniejszym przepływem pracy diagramów jako kodu łączy czytelne źródło, szybki feedback wizualny i przeglądarkę domenową. PlantUML zapewnia jawną kontrolę nad notacją interakcji, podczas gdy VPasCode może przyspieszyć tworzenie szkiców i iteracje; ostatecznym autorytetem co do poprawności diagramu pozostaje zachowanie systemu, które ma on opisywać.

Ten post dostępny jest również w Deutsch, English, Español, فارسی, Français, Bahasa Indonesia, 日本語, Portuguese, Ру́сский, Việt Nam, 简体中文 and 繁體中文