Przewodnik po składni diagramu sekwencji Mermaid.js

Co to jest diagram sekwencji?

A Diagram sekwencji to istotny diagram zachowania diagram UML zaprojektowany do wizualizacji kolejności przepływu wiadomości, wywołań funkcji i ładunków danych między różnymi jednostkami systemu wzdłuż liniowego czasu. Uznawany za podstawowy typ diagramu UML, mapuje interakcje w czasie rzeczywistym, układając składniki systemu wzdłuż osi X jako pionowe linie życia i śledząc wymianę wiadomości wzdłuż osi Y. Ten szablon jest nieoceniony dla programistów debugujących rozproszone wymiany danych API, ścieżki koordynacji mikroserwisów lub przepływy uwierzytelniania użytkownika w czasie rzeczywistym.

Z użyciem Mermaid.js, możesz tworzyć skrypty złożonych procesów czasowych przy użyciu intuicyjnej struktury tekstu. Silnik automatycznie obsługuje odstępy pionowe, zarządza wyrównaniem strzałek wiadomości i precyzyjnie rysuje bloki aktywacji w czasie rzeczywistym na Twojej płótnie.

Podstawowy przewodnik składniowy: elementy i konstrukcje

Aby stworzyć dokładny, łatwo czytelny diagram sekwencji UML w Mermaid, musisz opanować deklaracje uczestników, warianty strzałek wiadomości, jasne linie życia oraz struktury bloków warunkowych.

1. Deklarowanie uczestników i aktorów

Deklarujesz standardową jednostkę systemu za pomocą słowa kluczowego participant słowa kluczowego. Jeśli jednostka reprezentuje końcowego użytkownika lub zewnętrznego operatora, użyj słowa kluczowego actor aby wyświetlić standardowy ikonę postaci z drutu na płótnie:

sequenceDiagram
    actor Klient
    participant API jako Router Bramy

Porada: Użyj słowa kluczowego as aby przypisać długie nazwy składników do krótkich wewnętrznych aliasów, utrzymując skrypty wiadomości zwięzłe i czytelne.

2. Formatowanie strzałek wiadomości

Typ linii i kształt strzałki, który używasz, określa styl komunikacji między uczestnikami systemu:

• ->> **Wywołanie synchroniczne:** Ciągła linia z zapełnionym zakończeniem strzałki. Reprezentuje blokujące żądanie oczekujące na zakończenie wykonania.
• --> **Linia odpowiedzi:** Linia przerywana z otwartym zakończeniem strzałki. Używana do zwracania ładunków danych lub tokenów potwierdzenia.
• -> **Wywołanie asynchroniczne:** Ciągła linia z otwartym zakończeniem strzałki. Wskazuje na nieblokujące wiadomość lub nadawanie zdarzenia.

sequenceDiagram
    App->>Server: Wysyłka ładunku żądania
    Server-->App: Odpowiedź 200 OK

3. Zarządzanie paskami aktywacji linii życia

Aby dokładnie pokazać, kiedy składnik systemu aktywnie wykonuje zadanie lub zajmuje pamięć wątku, użyj poleceniaactivate i deactivate polecenia. Alternatywnie możesz dołączyć znak plus (+) lub minus (-) bezpośrednio do celów wiadomości jako szybki sposób wizualny:

sequenceDiagram
    Client->>+Server: Przetwarzanie danych
    %% Serwer jest teraz wizualnie aktywny
    Server-->-Client: Zwrócenie wyników

4. Struktury warunków i alternatyw (Alt, Opt, Loop)

Aby obsłużyć rozgałęzioną logikę czasu wykonania, ocenę tokenów lub powtarzające się ponowne próby żądań, otocz skrypty wiadomości standardowymi fragmentami bloków:

• alt / else — Ocena ścieżek warunkowych (podobnie jak bloki kodu if/else).
• opt — Definiuje opcjonalny krok, który wykonuje się tylko przy określonych kryteriach.
• pętla — Powtarza sekwencję wykonywania, aż warunek zostanie spełniony.

diagramSequencji
    pętla Co 30 sekund
        Klient->>Serwer: Ping serca
    koniec

Najlepsze praktyki dla czystych linii czasu sekwencji

• Zachowaj linie życia niezamieszane: Unikaj wymieniania dziesiątek mikrojednostek wzdłuż osi X. Jeśli proces współdziała z małymi klasami pomocniczymi, abstrahuj je za granicą systemu najwyższego poziomu, taką jak[Pracownik uwierzytelniania] lub [Pula pamięci podręcznej].
• Jasno oznacz kody stanu: Podczas pisania zwracanych odpowiedzi (-->), nie rób tylko „Zwróć dane”. Oznacz ścieżkę jawnymi kodami HTTP lub typami zdarzeń (np. "201 Utworzono (token JWT)") aby zapewnić inżynierom dokładny kontekst.
• Zaimplementuj notatki dla złożonych obliczeń: Użyj polecenia Note over, Note left of, lub Note right of aby dokumentować operacje niewizualne, takie jak kroki szyfrowania wewnętrzne lub skrótowanie danych w bazie danych.

Przykłady diagramów sekwencji Mermaid.js z rzeczywistego świata

Przykład 1: Bezpieczny przepływ wymiany tokenów OAuth2 (bloki aktywacji i alternatywne)

To funkcjonalny szablon modeluje bezpieczny przepływ logowania użytkownika. Pokazuje, jak łączyć aktorów ludzkich, jasne linie życia systemu i złożone ścieżki weryfikacji przy użyciu bloku alt/else.

sequenceDiagram
    actor Użytkownik jako Klient końcowy
    uczestnik Aplikacja jako Klient aplikacji mobilnej
    uczestnik Auth jako dostawca tożsamości Auth0

    Użytkownik->>+Aplikacja: Kliknij "Zaloguj się przez OAuth"
    Aplikacja->>+Auth: Przekierowanie z client_id i zakresem
    Auth-->>Użytkownik: Wyświetl interfejs logowania
    Użytkownik->>Auth: Prześlij dane logowania
    
    Auth->>Auth: Sprawdź poprawność skrótu hasła
    
    alt Dane logowania są poprawne
        Auth-->>Aplikacja: 302 Przekierowanie z kodem uwierzytelnienia
        Aplikacja->>Auth: Zamień kod na token dostępu
        Auth-->>-Aplikacja: Zwróć token JWT (IdToken)
        Aplikacja-->>Użytkownik: Wyświetl stronę główną konta użytkownika
    else Niepoprawne dane logowania
        Auth-->>Aplikacja: Zwróć błąd 401 Nieautoryzowany
        Aplikacja-->>-Użytkownik: Wyświetl ostrzeżenie "Niepoprawna nazwa użytkownika/hasło"
    end

Analiza składni: Ten harmonogram śledzi wymianę wiadomości między wieloma stronami. alt / else kontener jasno przedstawia dwie ścieżki weryfikacji, zapewniając pełną dokumentację stanów błędów wraz z główną ścieżką działania.

Przykład 2: Rozproszony proces wykonywania zamówienia i weryfikacji stanu magazynowego (procesy równoległe i notatki)

Ten zaawansowany szablon systemu przedstawia przepływ płatności w systemie e-commerce dla dużych firm. Wykorzystuje bloki równoległe (par) w celu pokazania równoległych routin wysyłania żądań API oraz zarządzania notatkami dotyczącymi blokowania bazy danych w całej architekturze.

sequenceDiagram
    uczestnik Web jako Interfejs WWW
    uczestnik Ord jako Orchestrator zamówień
    uczestnik Inv jako Usługa magazynowa
    uczestnik Pay jako Brama płatności

    Web->>+Ord: Wyślij żądanie zakupu
    Notatka nad Ord: Sprawdź dostępność towarów na stanie
    
    par Wysyłaj równoległe wywołania API
        Ord->>+Inv: Zablokuj pozycje magazynowe
        Inv-->-Ord: Zarezerwowano towar (stan zablokowany)
    i
        Ord->>+Pay: Zatwierdź opłatę kartą kredytową
        Pay-->-Ord: Zakończenie sukcesem (opłata rozliczona)
    koniec
    
    opcja Proces przypisania zakończył się niepowodzeniem
        Notatka po prawej stronie Ord: Wykonaj saga cofnięcia, jeśli któreś z wywołań nie powiedzie się
    koniec
    
    Ord-->-Web: 200 Sukces – potwierdzenie zakupu

Analiza składni: par / i kontener informuje silnik, aby grupował równoległe wykonania razem, dokumentując równoległe operacje w tle. Notatka nad oraz Notatka po prawej stronie tagi wstawiają techniczne wyjaśnienia czasu działania bezpośrednio na siatce rysunku, pomagając zespołom zrozumieć tło transakcji, takie jak blokowanie danych i saga cofnięcia, bez zatłoczenia głównych strzałek komunikatów.