Przewodnik po składni diagramów przepływu Mermaid.js

Czym jest diagram przepływu?

A Diagram przepływu to podstawowy schemat zachowania, który wizualizuje krok po kroku przebieg działania, procedurę algorytmiczną lub sekwencyjną logikę biznesową. Przedstawiając działania systemu jako odrębne kształty geometryczne i wyznaczając przepływ sterowania za pomocą strzałek kierunkowych, diagram przepływu ułatwia inżynierom oprogramowania i architektom systemów śledzenie ścieżek wykonywania warunkowego, izolowanie bloków jednopunktowych awarii oraz analizę pętli logiki systemu jeszcze przed napisaniem rzeczywistego kodu zaplecza.

Z Mermaid.js, nie musisz spędzać godzin na przeciąganiu pól, mikrouprawianiu linii siatki ani ponownym obliczaniu zmiennych wypełnienia. Silnik układu dynamicznie oblicza współrzędne węzłów na podstawie surowych skryptów deklaratywnych, pozwalając Ci skupić się całkowicie na podstawowej logice Twojego systemu.

Podstawowy przewodnik składniowy: elementy i konstrukcje

Aby stworzyć elegancki, łatwo czytelny diagram przepływu w Mermaid, musisz opanować wskaźniki kierunku płótna, geometryczne otoczenia węzłów, zmienne połączeń oraz podgrafy strukturalne.

1. Ustawianie kierunku płótna

Kierunek Twojego diagramu przepływu jest określany bezpośrednio w pierwszym wierszu przez parę słów kluczowych zastosowanych do obwodu graph lub flowchartobwodu. Możesz kontrolować kierunek skalowania wizualnego układu za pomocą czterech podstawowych kluczy kierunkowych:

• flowchart TD (Z góry na dół / orientacja pionowa)
• flowchart BU (Z dołu do góry)
• flowchart LR (Z lewej do prawej / orientacja pozioma)
• flowchart RL (Z prawej do lewej)

2. Dostosowywanie geometrii węzłów (kształty)

Domyślnie deklaracja prostego ID renderuje się jako ostro kątny prostokąt. Aby ułatwić skanowanie Twoich diagramów, użyj specjalnych nawiasów Mermaid, aby natychmiast wstrzyknąć kontekst wizualny do różnych kroków przepływu pracy. Każdy pojedynczy blok definicji musi być poprzedzony tokenem kierunku układu, aby został poprawnie przetworzony:

• Zaokrąglone krawędzie: id(Tekst) — Reprezentuje ogólny krok procesu.
• Kształt stadionu/kapsułowy: id([Tekst]) — Standardowy znacznik dla punktów granicznych początkowych i końcowych.
• Podprogram/Proces zdefiniowany z góry: id[[Tekst]] — Reprezentuje ujęty w opakowaniu systemowy podprogram lub zewnętrzny skrypt klasy.
• Walec/Baza danych: id[(Tekst)] — Reprezentuje trwałość bazy danych, pamięci podręczne lub magazyny danych.
• Romb/Diament decyzyjny: id{Tekst} — Reprezentuje warunkowe przełączniki, rozgałęzienia if/else lub punkty oceny.
• Równoległobok: id[/Tekst/] lub id[Tekst] — Rysuje pochyłe granice, aby przedstawić jawne dane wejścia/wyjścia (I/O).

diagram przepływu TD
    start_node([Start Execution])
    query_db[(Instancja PostgreSQL)]
    validate_check{Czy upoważniony?}

3. Zasady połączeń połączeń i etykiety wstawione w linii

Możesz dostosować linie połączeń, aby przedstawić różne relacje strukturalne i style komunikacji. Aby utrzymać wykresy w czystej formie, wstaw opisowe etykiety bezpośrednio na ścieżkach połączeń:

diagram przepływu TD
    %% Standardowy strzałkowy połączenie z etykietą tekstową
    A --> |"Ładunek JSON"| B

    %% Linia kropkowana/asynchroniczna z etykietą tekstową
    B -.-> |"Zdarzenie asynchroniczne"| C

    %% Gruba pogrubiona linia z etykietą tekstową
    C ==> |"Krytyczne zapisywanie"| D

4. Izolacja modułowa za pomocą podgrafów

Aby ustalić czyste granice sieci, grupować mikroserwisy lub izolować odpowiedzialności zespołów, grupuj swoje elementy wewnątrz strukturalnychpodgraf otoczeń. Definiujesz podgraf, przypisując mu wewnętrzny identyfikator, opcjonalny tytuł wyświetlany i zamykając go za pomocąkoniec znacznik:

diagram przepływu TD
    podgraf auth_sub["Granica zabezpieczeń"]
        gateway[Bramka interfejsu API] --> auth_worker(Weryfikator tokenu)
    koniec

Najlepsze praktyki dla czystych schematów blokowych

• Rozdziel układy poziomo: Dla długich, wieloetapowych potoków inżynieryjnych, wybierz diagram przepływu LR kierunek. Skaluje się znacznie lepiej na standardowych szerokopasmowych monitorach w orientacji poziomej niż długi układ pionowy.
• Wyodrębnij złożone pętle: Jeśli przepływ pracy zawiera ciężką pętlę powtarzania, jasno oznacz połączenie wsteczne (np. powtórz --> |"Próba zresetowania"| start) aby zapobiec myleniu pętli z typowym ścieżką w przód.
• Unikaj mieszania typów grafów: Używaj nowoczesnego diagram przepływu słowa kluczowego zamiast przestarzałego graf flagi podczas renderowania złożonych map. Silnik diagram przepływu używa uaktualnionego algorytmu układu, który obsługuje zaawansowane kombinacje strzałek i bardziej czyste routowanie ścieżek.

Przykłady rzeczywistych schematów blokowych Mermaid.js

Przykład 1: Sieć mikroserwisów oparta na zdarzeniach (architektura od lewej do prawej)

To funkcjonalny szablon modeluje usługę zbierania danych telemetrycznych z sieci web. Pokazuje, jak łączyć wejścia danych, diamenty decyzyjne i kształty bazy danych w chmurze na wyraźnym poziomym płótnie.

diagram przepływu LR
    %% Zdefiniuj węzły elementów z jawnymi kształtami geometrycznymi
    init([Wyzwolony Webhook]) --> input_io[/Zapisz żądanie HTTP/]
    input_io --> auth_check{Weryfikuj token}
    
    auth_check --> |"Nieprawidłowy token"| err_stop([Zwróć 401 Nieautoryzowany])
    auth_check --> |"Prawidłowy JWT"| write_queue[[Opublikuj w kolejce Kafka]]
    
    write_queue --> worker_proc(Demon konsumenta)
    worker_proc --> db_store[(Klastrowy TimescaleDB)]
    db_store --> term([Zakończony przepływ])

    %% Szybkie niestandardowe nadpisywanie stylów
    style auth_check wypełnienie:#fff3cd,kolor: #ffc107,szerokość: 2px
    style err_stop wypełnienie:#f8d7da,kolor: #dc3545,szerokość: 1px

Rozkład składni: Ten diagram płynnie przepływa z lewa do prawa. Krok weryfikacji używa żółtego kształtu diamentu decyzyjnego (auth_check{Weryfikacja tokenu}), który wyciąga ścieżkę wykonania w sposób wyraźny na dwa różne wyniki. Magazyny danych są od razu rozpoznawalne dzięki ich niestandardowym cylindrom komputerowym ([(Klastery TimescaleDB)]), a także równoległobokowym wejściom.

Przykład 2: Silnik rejestracji użytkownika w wielowarstwowej architekturze przedsiębiorstwa (pionowy z zagnieżdżonymi podgrafami)

Ten zaawansowany szablon przedsiębiorstwa mapuje proces rejestracji aplikacji. Organizuje kroki pionowo wzdłuż trzech oddzielnych podgrafów strukturalnych, aby przedstawić różne warstwy architektoniczne.

flowchart TD
    subgraph Client_Tier["Warstwa interfejsu użytkownika"]
        app[Interfejs aplikacji mobilnej]
        web[Frontend SPA Web]
    end

    subgraph Service_Tier["Główny router bramy"]
        proxy[[Odwrócony serwer proxy Nginx]]
        auth_svc({Pracownik usługi uwierzytelniania})
    end

    subgraph Persistence_Tier["Zabezpieczony centrum danych"]
        main_db[(Główna baza danych kont użytkowników)]
        cache_node[(Bufor sesji Redis)]
    end

    %% Zdefiniuj ścieżki komunikacji między warstwami podsystemów
    app -- "Żądanie HTTPS" --> proxy
    web -- "Żądanie HTTPS" --> proxy
    
    proxy --> |"Przekieruj /v1/auth"| auth_svc
    
    auth_svc --> |"Weryfikuj sesję"| cache_node
    auth_svc --> |"Zatwierdź konto"| main_db

Rozkład składni: Wskaźnik orientacji od góry do dołu (flowchart TD), który zmusza silnik układu do układania komponentów wyraźnie od góry do dołu. Bloki ograniczające grupują powiązane komponenty w oddzielnych warstwach (Klient, Usługa i Przechowywanie), nadając całej architekturze intuicyjny, bardzo uporządkowany wygląd.