Zanim przejdziemy do konkretnych układów architektonicznych, takich jak złożone schematy przepływu lub wykresy sekwencji czasowych, istotne jest zrozumienie podstawowych zasad, które regulująPodręcznik Mermaid. Mermaid opiera się na czystym, bardzo intuicyjnym systemie notacji tekstowej. Gdy zrozumiesz, jak silnik inicjuje typ płótna, nadaje nazwy elementom strukturalnym i kieruje strzałki kierunkowe, tworzenie dowolnego złożonego układu systemu staje się zupełnie naturalne.
Ten szybki przewodnik obejmuje globalne mechanizmy składni strukturalnej, które stosuje się we wszystkich typach wykresów Mermaid w środowisku VPasCode.
1. Obowiązkowe otoki typu wykresu
Każdy blok kodu Mermaid musi zaczynać się od jawnej deklaracji archetypu wykresu w pierwszym wierszu. Informuje to parser VPasCode, który silnik strukturalny ma uruchomić w oknie podglądu:
graph TD— Określa układ schematu przepływu ułożony od góry do dołu.sequenceDiagram— Określa wykres czasu działania chronologicznie.classDiagram— Określa strukturalny szkic oprogramowania opartego na obiektach.
W przeciwieństwie do innych silników konwertujących tekst na wykresy, Mermaid nie wymaga końcowych znaczników zamykających. Parser po prostu odczytuje deklarację strukturalną w pierwszym wierszu i kompiluje wszystko zagnieżdżone bezpośrednio poniżej w kontenerze bloku kodu.
2. Deklarowanie elementów: ID w porównaniu z etykietami wyświetlania
Podczas modelowania systemu oprogramowania tworzysz różne elementy strukturalne, takie jak komponenty, bazy danych lub mikroserwisy. W Mermaid deklarujesz element, definiując krótkie wewnętrzne ID alfanumeryczne, po którym od razu następuje styl nawiasów kontrolujący jego kształt wizualny, oraz przyjazną dla użytkownika nazwę wyświetlania:
microservice_id[API przetwarzania płatności]
db_id[(SQL transakcji użytkownika)]Dlaczego jest to najlepsza praktyka: Używanie krótkiego, czystego wewnętrznego ID (takiego jakmicroservice_id) znacznie przyspiesza rysowanie linii relacji w przyszłości. Jeśli kiedykolwiek trzeba zmienić etykietę widoczną dla klienta z „API przetwarzania płatności” na „Globalny serwis zakupowy”, wystarczy ją edytować tylko w jednym wierszu deklaracji, a nie aktualizować dziesiątek wierszy w całym skrypcie.
3. Opanowanie strzałek relacji i kierunkowego routingu
Połączenia między węzłami systemu rysuje się za pomocą kombinacji kresek (-), znaków równości (=), oraz nawiasów strzałek (>). Styl Twoich linii daje Ci pośredni kontrolę nad tym, jak silnik automatycznego układu skaluje Twój wykres:
A --> Brysuje standardową strzałkę skierowaną wskazującą od elementu A prosto do elementu B.A --- Brysuje płaską, niekierowaną linię połączenia bez główki strzałki, idealną do prostych powiązań.A -.-> Btworzy kreskowaną linię zależności, która jest standardem branżowym do oznaczania asynchronicznych zależności lub webhooków sieciowych.A ==> Btworzy grubą, pogrubioną linię połączenia, idealną do wyróżniania głównych ścieżek przetwarzania danych lub kluczowych połączeń infrastruktury.
4. Dodawanie kontekstu w linii: etykiety i komentarze kodu
Jasna dokumentacja bardzo dużo zależy na umieszczaniu odpowiedniego kontekstu wokół Twoich linii wizualnych i skryptów tekstowych:
Etykietowanie linii połączeń
Możesz dodać objaśniający tekst bezpośrednio do dowolnej linii połączenia, wstawiając ciąg tekstowy między dwie pary myślników, lub dodając znak pionowej kreski (“|Tekst|) tuż po swoim mapowaniu relacji:
client_id -- "HTTPS POST /v1/checkout" --> api_id
client_id --> |HTTPS POST /v1/checkout| api_idPisanie komentarzy kodu
Jeśli chcesz zostawić notatkę administracyjną, zasługę projektową lub wyjaśnienie architektoniczne w pliku skryptu bez rysowania pola wizualnego na płótnie, użyj podwójnych znaków procentu (%%). Informuje silnik, aby całkowicie pominął analizę tej linii:
%% TODO: Musimy zaktualizować ten pudełko graniczne, gdy zakończy się migracja DevOps
[Stary monolit] --> [Nowy mikroserwis]