Przewodnik po składni diagramów stanów Mermaid.js

Co to jest diagram stanów?

A Diagram stanów (znany również jako diagram stanów) to diagram zachowania diagram UML który modeluje skończony cykl życia pojedynczego obiektu lub podsystemu. Uznawany za podstawowy typ diagramu UML, ilustruje dyskretne warunki (stany), które jednostka może zajmować, zewnętrzne zdarzenia lub wyzwalacze, które powodują przejście między tymi warunkami (przejścia), oraz rozgałęzienia warunkowe, które zmieniają ścieżki wykonania. To mapowanie jest kluczowe do śledzenia złożonych cyklów życia obiektów, takich jak postęp zamówienia od realizacji do dostawy, sekwencja wygaśnięcia sesji użytkownika lub pętla przełącznika sprzętu wbudowanego.

Za pomocą Mermaid.js, możesz definiować swoje maszyny stanów reaktywne przy użyciu deklaratywnego, opartego na tekście schematu. Silnik analizy automatycznie oblicza optymalne odstępy układu, obsługuje strzałki cykliczne, a także płynnie skaluje granice kontenerów stanów.

Podstawowy przewodnik składniowy: elementy i konstrukcje

Aby stworzyć dokładny, zgodny z normami diagram stanów UML w Mermaid, musisz opanować znaczniki wejścia/wyjścia, ciągi przejść, zagnieżdżanie złożone, oraz bloki wyboru warunkowego.

1. Definiowanie stanów wejścia, wyjścia i standardowych

Zainicjuj płótno stanów w pierwszym wierszu za pomocą słowa kluczowego stateDiagram-v2 słowo kluczowe. Cykle życia wymagają jasno określonych punktów początkowych i końcowych, które są oznaczane symbolem pełnego kółka ([*]):

• Stan początkowy (wejście): [*] --> NazwaStanu (oznacza początek cyklu życia).
• Stan końcowy (wyjście): NazwaStanu --> [*] (oznacza zakończenie cyklu życia).

stateDiagram-v2
    [*] --> Pusta
    Pusta --> [*]

2. Konfigurowanie wyzwalaczy przejścia i etykiet zdarzeń

Aby zmapować zmianę stanu, połącz zdefiniowane tokeny stanu za pomocą standardowej linii strzałki (-->). Aby zarejestrować dokładne zdarzenie, odpowiedź interfejsu API lub kliknięcie przycisku, które powoduje to przejście, dołącz dwukropek (:) a następnie ciąg opisowy:

stateDiagram-v2
    Aktywny --> Wstrzymany : PaymentFailed
    Wstrzymany --> Aktywny : InvoiceSettled

3. Wdrażanie bloków warunkowych wyboru

Aby obsłużyć rozgałęzione pętle oceny, użyj<<choice>> stereotypu. Powoduje to stworzenie wyraźnej kształtu diamentu na płótnie, który dzieli pojedynczą ścieżkę przychodzącego przejścia na wiele różnych wyjściowych ścieżek na podstawie sprawdzeń logiki w czasie wykonywania:

stateDiagram-v2
    state check_status <<choice>>
    [*] --> check_status
    check_status --> UżytkownikPremium : jeśli saldo >= 100
    check_status --> UżytkownikStandardowy : jeśli saldo < 100

4. Strukturyzowanie stanów złożonych (zagnieżdżonych)

Podczas modelowania złożonego systemu pojedynczy stan najwyższego poziomu może zawierać własny niezależny wewnętrzny cykl życia. Możesz stworzyć układ podstanów zagnieżdżonych, definiując stan nadrzędny, a następnie blok ciała otoczony klamrami:

stateDiagram-v2
    state PrzetwarzanieZamówienia {
        [*] --> Pakowanie
        Pakowanie --> Etykietowanie
    }

Najlepsze praktyki dla czystych układów maszyn stanów

• Utrzymuj tokeny stanów krótkie: Używaj krótkich ciągów tekstowych w stylu CamelCase dla tokenów stanów wewnętrznych (np. OczekiwanieNaZwrot). Jeśli potrzebujesz długiego opisowego tytułu na płótnie, użyjstan "Blok opisowy" jako Token składnia do tworzenia jawnego aliasu.
• Wymuszaj pojedynczy punkt wejścia: Zawsze zaczynaj swój diagram od pojedynczego [*] węzła. Posiadanie wielu punktów początkowych może wprowadzić użytkowników w błąd, próbując śledzić główny ślad inicjalizacji systemu.
• Zawsze używaj stateDiagram-v2: Zawsze wybieraj stateDiagram-v2 słowo kluczowe zamiast starszej wersji stateDiagram flagi. Silnik renderowania v2 używa uaktualnionego algorytmu układu, który zapewnia czystsze routowanie linii i lepsze wyrównanie zagnieżdżonych pól.

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

Przykład 1: Cykl życia transakcji portfela cyfrowego (gałęzie wyboru i pętle błędów)

Ten funkcjonalny szablon modeluje cykl życia transakcji płatności cyfrowej, pokazując, jak transakcja przechodzi od początkowego punktu wysłania przez rozgałęzienie sprawdzania oszustw do ostatecznych stanów księgi.

stateDiagram-v2
    stan fraud_check <<choice>>

    [*] --> TransSubmitted
    TransSubmitted --> fraud_check : ExecuteRiskAssessment

    fraud_check --> TransApproved : Niski wynik ryzyka
    fraud_check --> TransFlagged : Wysoki wynik ryzyka
    
    TransFlagged --> TransApproved : Przeciążenie ręczne przez menedżera
    TransFlagged --> TransDeclined : Przekroczony czas bezpieczeństwa
    
    TransApproved --> SettlementPending : Zatwierdź księgę
    SettlementPending --> TransCompleted : Sukces rozliczenia bankowego
    
    TransDeclined --> [*]
    TransCompleted --> [*]

Analiza składni: Ten przepływ wykorzystuje blok <<choice>> do oceny wyników bezpieczeństwa od razu na początku. Transakcja przechodzi po różnych ścieżkach w zależności od tych wyników, z jasnymi nazwami zdarzeń (takimi jak ExecuteRiskAssessment) zapisanymi bezpośrednio na strzałkach przejść.

Przykład 2: Przepływ realizacji zamówienia w e-commerce (złożone zagnieżdżone systemy)

Ten zaawansowany szablon przedsiębiorstwa opisuje pełny cykl wysyłki i zarządzania zamówieniami, używając zagnieżdżonych bloków złożonych do pokazania wewnętrznych operacji odbywających się w fazie realizacji.

stateDiagram-v2
    [*] --> OrderPlaced
    
    OrderPlaced --> InFulfillment : Zabranie płatności
    
    stan InFulfillment {
        [*] --> ItemPicking
        ItemPicking --> QualityAudit : Zbiorczo wybrane
        QualityAudit --> SecureBoxPacking : Audyt zakończony sukcesem
        SecureBoxPacking --> CarrierManifest Generated : Etykieta wydrukowana
    }
    
    InFulfillment --> Shipped : Uzgodnienie z kurierem
    Shipped --> Delivered : Potwierdzenie wysyłki
    
    Delivered --> [*]

Rozkład składni: Owrapowanie kroków wewnątrzstan InFulfillment {...} blok ciała tworzysz wyraźną strukturalną granicę na płótnie. Silnik traktuje ten blok jako pojedynczy skondensowany stan nadrzędny podczas renderowania jego wewnętrznych kroków przepływu pracy kolejno, co ułatwia nawigację po skomplikowanych wielowarstwowych cyklach życia.