Poza statycznymi obrazami: Odblokowanie mocy Diagramów jako Kodu dzięki Mermaid i narzędziom AI
Kryzys dokumentacji
Każdy zespół inżynieryjny zna ten ból. Spędzasz tygodnie na projektowaniu pięknej architektury mikroserwisów, starannie tworząc diagramy w Visio, które zachwycają interesariuszy. Sześć miesięcy później system ewoluował – dodano nowe usługi, przeniesiono bazy danych, deprecjonowano punkty końcowe API – ale diagram zamarzł w czasie. To relikt. Wręcz kłamstwo.
To „rot dokumentacji”, cichy zabójca produktywności inżynieryjnej. Gdy diagramy kłamią, programiści je ignorują. Gdy programiści ignorują dokumentację, przejmują wiedzę plemienna. Gdy osoba, która zna system, odejdzie, zostajesz ze złożonym kodem i bez mapy.
Diagramy jako Kod (DaC) jest rozwiązaniem. A w jego sercu leży Mermaid, narzędzie do tworzenia diagramów oparte na JavaScript, które zamienia zwykły tekst w piękne wizualizacje.
Podstawowa filozofia: Traktuj diagramy jak oprogramowanie
Fundamentalna zmiana w podejściu Diagramy jako Kod polega na traktowaniu diagramów z taką samą rygorystycznością jak kodu aplikacji. Oznacza to:
1. Kontrola wersji jest standardem
Gdy twój diagram to plik .mermaid, znajduje się w twoim repozytorium Git obok kodu źródłowego. Każda zmiana jest śledzona. Możesz git blame, aby zobaczyć, kto dodał nową usługę, git diff, aby przeglądać zmiany przed scaleniem, oraz cofnąć się do dowolnego poprzedniego stanu.
gitGraph
commit id: "Architektura początkowa"
commit id: "Dodaj usługę użytkownika"
branch feature/order-service
commit id: "Usługa zamówień v1"
commit id: "Dodaj bramkę płatności"
checkout main
merge feature/order-service
commit id: "Zaktualizuj bramkę API"Przykład: Wizualizacja własnej historii Git diagramu przy użyciu składni Git Graph Mermaid
2. Przeglądy kodu dla diagramów
Pull requesty nie służą już tylko kodowi. Gdy programista proponuje nową usługę lub zmienia przepływ danych, ta zmiana pojawia się jako czytelny różnicowy (diff) w PR. Przeglądający mogą komentować sam diagram, zapewniając, że decyzje architektoniczne są omawiane i zatwierdzane przed scaleniem.
3. Integracja z potokami CI/CD
Twoje diagramy mogą być automatycznie generowane i walidowane w twoim potoku. Wyobraź sobie akcję GitHub, która:
-
Generuje wszystkie diagramy Mermaid jako PNG/SVG
-
Przesyła je na stronę z dokumentacją
-
Zawala budowanie, jeśli wykryto nieprawidłową składnię Mermaid
flowchart LR
A[Programista wysyła kod] --> B[Uruchomienie potoku CI]
B --> C[Uruchom testów]
B --> D[Rysowanie diagramów Mermaid]
D --> E{Poprawna składnia?}
E -->|Tak| F[Przesyłanie do dokumentacji]
E -->|Nie| G[Błąd budowania i powiadomienie zespołu]
F --> H[Wdrożenie aplikacji]
G --> I[Programista poprawia składnię]
I --> A
Przykład: Potok CI/CD do walidacji diagramów i wdrażania
Mermaid w akcji: Przykłady z życia wzięte
Przyjrzyjmy się typom diagramów obsługiwanych przez Mermaid, korzystając z praktycznych przykładów z życia wziętych.
Przykład 1: Architektura mikroserwisów (Diagram przepływu)
Jest to najczęstszy przypadek użycia — wizualizacja komunikacji między Twoimi usługami.
flowchart TB
subgraph "Warstwa klienta"
MobileApp[Applikacja mobilna]
WebApp[Applikacja webowa]
end
subgraph "Brama API"
Gateway[Brama API]
end
subgraph "Mikroserwisy"
UserSvc[Usługa użytkownika]
OrderSvc[Usługa zamówień]
ProductSvc[Usługa produktów]
PaymentSvc[Usługa płatności]
end
subgraph "Warstwa danych"
UserDB[(Baza danych użytkowników)]
OrderDB[(Baza danych zamówień)]
ProductDB[(Baza danych produktów)]
Redis[(Pamięć podręczna Redis)]
end
subgraph "Usługi zewnętrzne"
Stripe[Płatności Stripe]
EmailAPI[API e-mail]
end
MobileApp --> Gateway
WebApp --> Gateway
Gateway --> UserSvc
Gateway --> OrderSvc
Gateway --> ProductSvc
Gateway --> PaymentSvc
UserSvc --> UserDB
UserSvc --> Redis
OrderSvc --> OrderDB
OrderSvc --> Redis
ProductSvc --> ProductDB
ProductSvc --> Redis
PaymentSvc --> Stripe
OrderSvc --> EmailAPI
PaymentSvc --> EmailAPI
Przykład: Kompletna architektura mikroserwisów z pamięcią podręczną, bazami danych i zależnościami zewnętrznymi
Przykład 2: Proces autoryzacji użytkownika (Diagram sekwencji)
Diagramy sekwencji są idealne do dokumentowania złożonych interakcji między usługami.
sequenceDiagram
autonumber
participant Użytkownik
participant Frontend
participant AuthSvc jako Usługa autoryzacji
participant UserDB jako Baza danych użytkowników
participant Cache jako Pamięć podręczna Redis
participant EmailSvc jako Usługa e-mail
Użytkownik->>Frontend: Wprowadź dane logowania
Frontend->>AuthSvc: POST /login (email, hasło)
AuthSvc->>UserDB: Wyszukaj użytkownika po emailu
UserDB-->>AuthSvc: Zwróć zaszyfrowane hasło i dane użytkownika
AuthSvc->>AuthSvc: Zweryfikuj hasło za pomocą bcrypt
alt Poprawne dane logowania
AuthSvc->>AuthSvc: Wygeneruj token JWT
AuthSvc->>Cache: Zapisz sesję (klucz: user_id, ttl: 1h)
AuthSvc-->>Frontend: 200 OK + token JWT
Frontend-->>Użytkownik: Przekieruj do pulpitu
else Niepoprawne dane logowania
AuthSvc->>EmailSvc: Wywołaj alert nieudanej próby logowania
AuthSvc-->>Frontend: 401 Unauthorized
Frontend-->>Użytkownik: Wyświetl komunikat o błędzie
end
Note over AuthSvc,EmailSvc: Po 5 nieudanych próbach zablokuj konto na 15 minut
Przykład: Szczegółowy proces autoryzacji pokazujący ścieżki sukcesu i porażki, w tym skutki uboczne takie jak pamięć podręczna i alerty
Przykład 3: Infrastruktura chmurowa w AWS (Diagram klas)
Diagramy klas nie służą tylko do kodu — mogą modelować zasoby chmurowe i ich relacje.
classDiagram
class VPC {
+string cidr_block
+string region
+createSubnet()
+deleteSubnet()
}
class Podsieć {
+string strefa dostępności
+string cidr_block
+boolean jest_publiczna
+attachRouteTable()
}
class Ek2Instancja {
+string typ_instancji
+string ami_id
+int pamięć_gb
+start()
+stop()
+reboot()
}
class RDSDatabaza {
+string silnik
+string wersja
+int pamięć_gb
+boolean wielostrefowa
+takeSnapshot()
+restoreFromSnapshot()
}
class S3Bucket {
+string nazwa_bucketa
+string region
+boolean wersjonowanie_włączone
+uploadFile()
+downloadFile()
}
class RolaIAM {
+string nazwa_rola
+string dokument_polityki
+attachPolicy()
+detachPolicy()
}
VPC "1" --> "*" Podsieć
Podsieć "1" --> "*" Ek2Instancja
Podsieć "1" --> "0..1" RDSDatabaza
VPC "1" --> "0..*" S3Bucket
Ek2Instancja --> RolaIAM
RDSDatabaza --> RolaIAM
Przykład: Modelowanie infrastruktury AWS jako klas z właściwościami i metodami, przydatne do dokumentacji i planowania Infrastructure-as-Code
Przykład 4: Przetwarzanie zamówień w e-commerce (Diagram stanów)
Diagramy stanów świetnie pokazują, jak byty przechodzą przez różne stany.
stateDiagram-v2
[*] --> Koszyk: Użytkownik dodaje przedmioty
Koszyk --> Kasa: Użytkownik przechodzi do kasy
Kasa --> PłatnośćOczekująca: Użytkownik składa zamówienie
PłatnośćOczekująca --> PłatnośćPrzetwarzana: Uruchomienie bramki płatności
PłatnośćPrzetwarzana --> Zapłacono: Płatność udana
PłatnośćPrzetwarzana --> PłatnośćOdrzucona: Płatność odrzucona
PłatnośćOdrzucona --> Kasa: Użytkownik ponawia próbę płatności
PłatnośćOdrzucona --> [*]: Użytkownik porzuca koszyk
Zapłacono --> ZamówieniePotwierdzone: Wyślij e-mail potwierdzający
ZamówieniePotwierdzone --> Przygotowanie: Przypisz do magazynu
Przygotowanie --> Wysłane: Przekazanie przewoźnikowi
Wysłane --> WTransicie: Przewoźnik odbiera przesyłkę
WTransicie --> Dostarczone: Dostawa potwierdzona
Dostarczone --> ProśbaORecenzję: Poproś o recenzję użytkownika
ProśbaORecenzję --> [*]: Użytkownik submituje recenzję
Dostarczone --> WniosekOzwrot: Użytkownik inicjuje zwrot
WniosekOzwrot --> ZwrotZatwierdzony: Wsparcie zatwierdza
ZwrotZatwierdzony --> ZwrotPrzetworzony: Pieniądze zwrócone
ZwrotPrzetworzony --> [*]: Zamówienie zamknięte
state "Wysokoryzykowna weryfikacja oszustw" jako WeryfikacjaOszustw {
[*] --> SprawdźWynik
SprawdźWynik --> NiskiRyzyko: Wynik < 50
SprawdźWynik --> WysokiRyzyko: Wynik >= 50
WysokiRyzyko --> RecenzjaRęczna: Oznacz dla zespołu
RecenzjaRęczna --> NiskiRyzyko: Zatwierdzone
RecenzjaRęczna --> PłatnośćOdrzucona: Odrzucone
}
PłatnośćOczekująca --> WeryfikacjaOszustw: Wywołano ocenę ryzyka
WeryfikacjaOszustw --> PłatnośćPrzetwarzana: NiskiRyzyko
Przykład: Pełna maszyna stanów zamówień e-commerce z zagnieżdżonym stanem wykrywania oszustw
Przykład 5: Planowanie sprintu z użyciem problemów GitHub (Wykres Git)
Wykresy Git mogą reprezentować przepływy pracy wykraczające poza sam Git.
gitGraph
commit id: "Planowanie sprintu" type: HIGHLIGHT
branch sprint-1
commit id: "Historia użytkownika #101: Strona logowania"
commit id: "Historia użytkownika #102: Rejestracja użytkownika"
branch bugfix/hotfix
commit id: "Hotfix: Wygaśnięcie tokena uwierzytelniającego"
checkout sprint-1
merge bugfix/hotfix
commit id: "Historia użytkownika #103: Resetowanie hasła"
checkout main
merge sprint-1 tag: "v1.0.0"
branch sprint-2
commit id: "Funkcja #201: Koszyk zakupowy"
commit id: "Funkcja #202: Przepływ kasy"
branch experiment/ai-recommendations
commit id: "POC: Silnik rekomendacji ML"
checkout sprint-2
commit id: "Funkcja #203: Historia zamówień"
checkout main
merge sprint-2 tag: "v2.0.0"
commit id: "Notatki wydania: Sprint 1 i 2 zakończone"
Przykład: Wizualizacja zarządzania projektami, sprintów i gałęzi funkcjonalnych jako wykres Git
Rewolucja AI w tworzeniu diagramów
Mimo elegancji Mermaid, składnia może być barierą. Kto chce debugować źle wyrównaną strzałkę lub brakującą nawias, gdy próbuje udokumentować system?
To właśnie tutaj narzędzia napędzane przez AI zmieniają wszystko.
Automatyczne naprawianie przez AI
Narzędzia takie jak VPasCode (platforma Diagram as Code Visual Paradigm) oraz Mermaid Chart posiadają zintegrowane modele AI (takie jak Google Gemini i OpenAI), które mogą:
-
Automatycznie wykrywać błędy składni
-
Naprawiać uszkodzone diagramy jednym kliknięciem
-
Sugerować ulepszenia struktury diagramu
Zobaczmy to w działaniu:
Uszkodzony kod Mermaid:
flowchart LR
A[Frontend] --> B(API Gateway
B --> C[User Service]
C --> D[(Database
D --> E[Cache]
Kod naprawiony przez AI:
flowchart LR
A[Frontend] --> B(Brama API)
B --> C[Usługa użytkownika]
C --> D[(Baza danych)]
D --> E[Komórka pamięci podręcznej]
AI rozpoznaje brakujące nawiasy zamykające i klamry, naprawiając je natychmiast.
Język naturalny do diagramu
Być może najbardziej potężną funkcją jest generowanie diagramów na podstawie opisów w języku naturalnym. Dzięki takim narzędziom jak OpenDocs (platforma dokumentacji VP), możesz po prostu opisać, czego chcesz:
„Stwórz schemat blokowy pokazujący logowanie użytkownika. Jeśli dane uwierzytelniające są poprawne, przekieruj do pulpitu. Jeśli niepoprawne, wyświetl błąd i zezwól na 3 próby. Po 3 niepowodzeniach zablokuj konto.”
Mermaid wygenerowany przez AI:
flowchart TD
Start([Użytkownik próbuje się zalogować]) --> EnterCreds[Wpisz e-mail i hasło]
EnterCreds --> Validate{Zweryfikuj dane uwierzytelniające}
Validate -->|Poprawne| Dashboard[Przekieruj do pulpitu]
Validate -->|Niepoprawne| CheckAttempts{Liczba prób < 3}
CheckAttempts -->|Tak| Increment[Zwiększ licznik prób]
Increment --> ShowError[Pokaż komunikat o błędzie]
ShowError --> EnterCreds
CheckAttempts -->|Nie| LockAccount[Zablokuj konto na 15 minut]
LockAccount --> SendAlert[Wyślij powiadomienie o bezpieczeństwie]
SendAlert --> End([Proces zakończony])
Dashboard --> End
Tłumaczenie między typami diagramów
AI może również tłumaczyć między różnymi formatami diagramów. Potrzebujesz przekonwertowania diagramu PlantUML na Mermaid? Narzędzia AI mogą to obsłużyć:
Wejście PlantUML:
@startuml
actor User
participant "Frontend" as FE
participant "Backend" as BE
database "DB" as DB
User -> FE: Kliknij Logowanie
FE -> BE: POST /login
BE -> DB: SELECT user
DB --> BE: dane użytkownika
BE --> FE: Token JWT
FE --> User: Pokaż Pulpit
@enduml
Mermaid przekonwertowany przez AI:
sequenceDiagram
actor User
participant Frontend
participant Backend
participant Database
User->>Frontend: Kliknij Logowanie
Frontend->>Backend: POST /login
Backend->>Database: SELECT user
Database-->>Backend: dane użytkownika
Backend-->>Frontend: Token JWT
Frontend-->>User: Pokaż Pulpit
Integracja z interaktywnym chatbotem
Niektóre platformy oferują teraz interfejsy chatbotów do tworzenia diagramów. Możesz prowadzić rozmowę:
Użytkownik: „Dodaj nową usługę o nazwie ‘Usługa inwentaryzacji’ do mojego diagramu architektury.”
AI: „Dodam Serwis Magazynowy połączony z istniejącymi usługami Produktów i Zamówień.”
Diagram aktualizuje się automatycznie
Użytkownik: „Właściwie, niech połączy się również z nową bazą danych o nazwie ‘InventoryDB’.”
AI: „Gotowe. Serwis Magazynowy łączy się teraz z Usługą Produktów, Usługą Zamówień oraz nową bazą InventoryDB.”
Integracja Diagramów jako Kodu w Twoim Procesie Pracy
Krok 1: Zacznij od małego
Nie próbuj diagramować całego systemu na raz. Zacznij od pojedynczego komponentu – być może przepływu uwierzytelniania lub nowej funkcji, którą budujesz.
Krok 2: Osadź w dokumentacji
Przechowuj swoje .mermaid obok swojej dokumentacji (np. w folderze /docs). Używaj narzędzi takich jak mermaid-cli do ich renderowania w procesie budowania.
Krok 3: Wykorzystaj Zjednoczone Silnik VPasCode
Jeśli pracujesz w zespole o zróżnicowanych preferencjach, VPasCode jest nieoceniony. Obsługuje wiele języków diagramów jako kodu w jednym miejscu:
# W VPasCode możesz mieszać i dopasowywać:
diagrams/
├── architecture.mermaid
├── deployment.puml # PlantUML
├── database-erd.mermaid
└── workflow.d2 # język D2
Krok 4: Automatyzuj z CI/CD
Dodaj krok do swoich GitHub Actions lub GitLab CI:
- name: Renderuj Diagramy Mermaid
run: |
for file in $(find docs -name "*.mermaid"); do
npx @mermaid-js/mermaid-cli -i $file -o ${file%.mermaid}.png
done
- name: Prześlij na stronę dokumentacji
run: |
aws s3 sync docs/ s3://twoj-bucket-dokumentacji/
Krok 5: Przegląd w Pull Requestach
Wprowadź zasadę, że wszystkie zmiany w architekturze wymagają aktualizacji diagramów. Używaj komentarzy w PR do dyskusji nad zmianami wizualnymi:
Recenzent: „Czy cache nie powinien znajdować się między Order Service a bazą danych? Obecnie jest podpięty tylko do User Service.”
Autor: „Dobrze zauważone. Zaktualizuję diagram.”
Wpływ w praktyce: studium przypadku
Wyobraź sobie startup z branży fintech, który wdrożył podejście Diagram as Code z użyciem Mermaid i VPasCode:
-
Przed: 47 statycznych plików Visio, większość starsza niż 6 miesięcy. Nowi pracownicy spędzali 3 tygodnie na zrozumieniu architektury.
-
Po: 12 diagramów Mermaid, wszystkie przechowywane w Git, aktualizowane przy każdej funkcji. Nowi pracownicy byli produktywni już w pierwszym tygodniu.
CTO zespołu zauważył: „Przeszliśmy od traktowania diagramów jako formalnego wymogu do bycia żywą częścią naszego procesu deweloperskiego. Kiedy dyskutujemy o nowej architekturze, otwieramy edytor Mermaid i dosłownie szkicujemy ją w kodzie. To zmiana paradygmatu.”
Przyszłość: ciągła dokumentacja
Ostatecznym celem jest „ciągła dokumentacja”, w której diagramy są generowane automatycznie z infrastruktury lub kodu. Pojawiają się już narzędzia, które potrafią:
-
Skanować manifesty Kubernetes i generować diagramy topologii usług
-
Analizować pliki OpenAPI/Swagger i tworzyć diagramy przepływu API
-
Monitorować zasoby chmurowe i automatycznie aktualizować diagramy architektury
Mermaid stoi w centrum tego ruchu, zapewniając prosty, tekstowy format, który maszyny mogą generować, a ludzie rozumieć.
Zacznij już dziś
Gotowy, by wyjść poza statyczne obrazy? Oto Twój plan działania:
-
Zainstaluj rozszerzenie Mermaid w ulubionym środowisku IDE (VS Code, IntelliJ)
-
Stwórz swój pierwszy diagram w pliku
.mdużywając składni Mermaid -
Wypróbuj darmowy plan VPasCode aby poznać diagramowanie wspomagane przez AI
-
Rozpocznij repozytorium dokumentacji na żywo obok Twojego kodu źródłowego
-
Podziel się tym artykułem ze swoim zespołem i rozpocznij rozmowę
Twoja architektura zasługuje na coś lepszego niż zakurzony diagram w zapomnianym folderze. Czas traktować Twoje diagramy jako krytyczne zasoby, jakimi są.
