За пределами статических изображений: раскрываем потенциал диаграмм как кода с помощью Mermaid и инструментов на базе ИИ
Кризис документации
Каждая инженерная команда знает эту боль. Вы проводите недели, проектируя красивую архитектуру микросервисов, тщательно создавая диаграммы в Visio, которые впечатляют заинтересованных лиц. Спустя шесть месяцев система эволюционировала: добавлены новые сервисы, базы данных перенесены, API-эндпоинты устарели, но диаграмма застыла во времени. Это реликвия. Даже ложь.
Это «документационная гниль», и это тихий убийца инженерной продуктивности. Когда диаграммы врут, разработчики игнорируют их. Когда разработчики игнорируют документацию, в дело вступает племенное знание. Когда единственный человек, знающий систему, уходит, вы остаётесь со сложной кодовой базой и без карты.
Диаграммы как код (DaC) — это решение. В его основе лежит Mermaid — инструмент для создания диаграмм на JavaScript, превращающий обычный текст в красивые визуализации.
Основная философия: относитесь к диаграммам как к программному обеспечению
Фундаментальный сдвиг при использовании подхода «диаграммы как код» заключается в том, чтобы относиться к вашим диаграммам с той же строгостью, что и к коду приложения. Это означает:
1. Контроль версий — это стандарт
Когда ваша диаграмма представляет собой файл .mermaid, она находится в вашем Git-репозитории рядом с исходным кодом. Каждое изменение отслеживается. Вы можете git blame, чтобы увидеть, кто добавил новый сервис, git diff, чтобы просмотреть изменения перед слиянием, и откатиться к любому предыдущему состоянию.
gitGraph
commit id: "Initial architecture"
commit id: "Add user service"
branch feature/order-service
commit id: "Order service v1"
commit id: "Add payment gateway"
checkout main
merge feature/order-service
commit id: "Update API gateway"
Пример: визуализация собственной истории Git вашей диаграммы с использованием синтаксиса Git Graph в Mermaid
2. Код-ревью для диаграмм
Запросы на слияние (pull requests) теперь нужны не только для кода. Когда разработчик предлагает новый сервис или изменяет поток данных, это изменение отображается как читаемый дифф в запросе на слияние. Рецензенты могут оставлять комментарии непосредственно к диаграмме, обеспечивая обсуждение и утверждение архитектурных решений до их слияния.
3. Интеграция с конвейерами CI/CD
Ваши диаграммы могут автоматически генерироваться и проверяться в вашем конвейере. Представьте действие GitHub, которое:
-
Рендерит все диаграммы Mermaid в формате PNG/SVG
-
Загружает их на ваш сайт документации
-
Прерывает сборку, если обнаружена некорректная синтаксис Mermaid
flowchart LR
A[Разработчик отправляет код] --> B[Запуск CI-конвейера]
B --> C[Выполнение тестов]
B --> D[Рендеринг диаграмм Mermaid]
D --> E{Валидный синтаксис?}
E -->|Да| F[Загрузка в документацию]
E -->|Нет| G[Сбой сборки и уведомление команды]
F --> H[Развёртывание приложения]
G --> I[Разработчик исправляет синтаксис]
I --> A
Пример: Рабочий процесс CI/CD для валидации диаграмм и развёртывания
Mermaid в действии: Реальные примеры
Давайте изучим типы диаграмм, которые поддерживает Mermaid, на практических примерах из реальной жизни.
Пример 1: Архитектура микросервисов (Поточная диаграмма)
Это самый распространённый сценарий использования — визуализация взаимодействия ваших сервисов.
flowchart TB
subgraph "Слой клиента"
MobileApp[Мобильное приложение]
WebApp[Веб-приложение]
end
subgraph "API-шлюз"
Gateway[API-шлюз]
end
subgraph "Микросервисы"
UserSvc[Сервис пользователей]
OrderSvc[Сервис заказов]
ProductSvc[Сервис товаров]
PaymentSvc[Сервис платежей]
end
subgraph "Слой данных"
UserDB[(База данных пользователей)]
OrderDB[(База данных заказов)]
ProductDB[(База данных товаров)]
Redis[(Кэш Redis)]
end
subgraph "Внешние сервисы"
Stripe[Платёж Stripe]
EmailAPI[Email API]
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
Пример: Полная архитектура микросервисов с кэшированием, базами данных и внешними зависимостями
Пример 2: Поток аутентификации пользователя (Диаграмма последовательности)
Диаграммы последовательности идеально подходят для документирования сложных взаимодействий между сервисами.
sequenceDiagram
autonumber
participant Пользователь
participant Фронтенд
participant AuthSvc как Сервис аутентификации
participant UserDB как База данных пользователей
participant Cache как Кэш Redis
participant EmailSvc как Сервис email
Пользователь->>Фронтенд: Ввести учётные данные
Фронтенд->>AuthSvc: POST /login (email, password)
AuthSvc->>UserDB: Запрос пользователя по email
UserDB-->>AuthSvc: Вернуть хешированный пароль и данные пользователя
AuthSvc->>AuthSvc: Проверить пароль с помощью bcrypt
alt Валидные учётные данные
AuthSvc->>AuthSvc: Сгенерировать JWT-токен
AuthSvc->>Cache: Сохранить сессию (ключ: user_id, ttl: 1 час)
AuthSvc-->>Фронтенд: 200 OK + JWT-токен
Фронтенд-->>Пользователь: Перенаправить на панель управления
else Неверные учётные данные
AuthSvc->>EmailSvc: Запустить уведомление о неудачной попытке входа
AuthSvc-->>Фронтенд: 401 Unauthorized
Фронтенд-->>Пользователь: Показать сообщение об ошибке
end
Note over AuthSvc,EmailSvc: После 5 неудачных попыток заблокировать аккаунт на 15 минут
Пример: Подробный поток аутентификации, показывающий пути успеха и неудачи, включая побочные эффекты, такие как кэширование и уведомления
Пример 3: Облачная инфраструктура на AWS (Классовая диаграмма)
Классовые диаграммы предназначены не только для кода — они могут моделировать облачные ресурсы и их взаимосвязи.
classDiagram
class VPC {
+string cidr_block
+string region
+createSubnet()
+deleteSubnet()
}
class Подсеть {
+string availability_zone
+string cidr_block
+boolean is_public
+attachRouteTable()
}
class EC2Instance {
+string instance_type
+string ami_id
+int storage_gb
+start()
+stop()
+reboot()
}
class RDSDatabase {
+string engine
+string version
+int storage_gb
+boolean multi_az
+takeSnapshot()
+restoreFromSnapshot()
}
class S3Bucket {
+string bucket_name
+string region
+boolean versioning_enabled
+uploadFile()
+downloadFile()
}
class IAMRole {
+string role_name
+string policy_document
+attachPolicy()
+detachPolicy()
}
VPC "1" --> "*" Подсеть
Подсеть "1" --> "*" EC2Instance
Подсеть "1" --> "0..1" RDSDatabase
VPC "1" --> "0..*" S3Bucket
EC2Instance --> IAMRole
RDSDatabase --> IAMRole
Пример: Моделирование инфраструктуры AWS в виде классов с свойствами и методами, полезно для документации и планирования Infrastructure-as-Code
Пример 4: Обработка заказов в электронной коммерции (Диаграмма состояний)
Диаграммы состояний отлично подходят для отображения того, как сущности переходят через различные статусы.
stateDiagram-v2
[*] --> Корзина: Пользователь добавляет товары
Корзина --> Оформление: Пользователь переходит к оформлению
Оформление --> ОжиданиеОплаты: Пользователь отправляет заказ
ОжиданиеОплаты --> ОбработкаОплаты: Инициализация платежного шлюза
ОбработкаОплаты --> Оплачено: Оплата успешна
ОбработкаОплаты --> ОшибкаОплаты: Отказ в оплате
ОшибкаОплаты --> Оформление: Пользователь повторяет попытку оплаты
ОшибкаОплаты --> [*]: Пользователь оставляет корзину
Оплачено --> ЗаказПодтвержден: Отправить подтверждение по электронной почте
ЗаказПодтвержден --> Подготовка: Назначить складу
Подготовка --> Отправлено: Передача перевозчику
Отправлено --> ВПутешествии: Перевозчик забирает груз
ВПутешествии --> Доставлено: Доставка подтверждена
Доставлено --> ЗапросОтзыва: Запросить отзыв у пользователя
ЗапросОтзыва --> [*]: Пользователь отправляет отзыв
Доставлено --> ЗапросВозврата: Пользователь инициирует возврат
ЗапросВозврата --> ВозвратОдобрено: Поддержка одобряет
ВозвратОдобрено --> ВозвратОбработан: Деньги возвращены
ВозвратОбработан --> [*]: Заказ закрыт
state "Проверка на мошенничество высокого риска" как FraudCheck {
[*] --> ПроверкаОценки
ПроверкаОценки --> НизкийРиск: Оценка < 50
ПроверкаОценки --> ВысокийРиск: Оценка >= 50
ВысокийРиск --> РучнаяПроверка: Пометить для команды
РучнаяПроверка --> НизкийРиск: Одобрено
РучнаяПроверка --> ОшибкаОплаты: Отклонено
}
ОжиданиеОплаты --> FraudCheck: Запущена оценка риска
FraudCheck --> ОбработкаОплаты: НизкийРиск
Пример: Полная машина состояний заказа электронной коммерции с вложенным состоянием обнаружения мошенничества
Пример 5: Планирование спринта с использованием задач GitHub (Граф Git)
Графы Git могут отображать рабочие процессы, выходящие за рамки самого Git.
gitGraph
commit id: "Планирование спринта" type: HIGHLIGHT
branch sprint-1
commit id: "Пользовательская история #101: Страница входа"
commit id: "Пользовательская история #102: Регистрация пользователя"
branch bugfix/hotfix
commit id: "Экстренное исправление: Истечение срока токена авторизации"
checkout sprint-1
merge bugfix/hotfix
commit id: "Пользовательская история #103: Сброс пароля"
checkout main
merge sprint-1 tag: "v1.0.0"
branch sprint-2
commit id: "Функция #201: Корзина покупок"
commit id: "Функция #202: Поток оформления заказа"
branch experiment/ai-recommendations
commit id: "POC: Движок рекомендаций на основе ML"
checkout sprint-2
commit id: "Функция #203: История заказов"
checkout main
merge sprint-2 tag: "v2.0.0"
commit id: "Примечания к выпуску: Спринты 1 и 2 завершены"
Пример: Визуализация управления проектами, спринтов и функциональных веток в виде графа Git
Революция ИИ в создании диаграмм
Несмотря на элегантность Mermaid, синтаксис может стать препятствием. Кто захочет отлаживать неправильно выровненную стрелку или отсутствующую скобку, когда вы пытаетесь документировать систему?
Именно здесь инструменты на базе ИИ меняют всё.
Автоисправление ИИ
Такие инструменты, как VPasCode (платформа Visual Paradigm для диаграмм как кода) и Mermaid Chart имеют интегрированные модели ИИ (такие как Google Gemini и OpenAI), которые могут:
-
Автоматически обнаруживать синтаксические ошибки
-
Исправлять сломанные диаграммы одним кликом
-
Предлагать улучшения структуры диаграмм
Давайте посмотрим на это в действии:
Сломанный код Mermaid:
flowchart LR
A[Frontend] --> B(API Gateway
B --> C[User Service]
C --> D[(Database
D --> E[Cache]
Исправленный ИИ код:
flowchart LR
A[Frontend] --> B(API Gateway)
B --> C[User Service]
C --> D[(Database)]
D --> E[Cache]
ИИ распознаёт отсутствующие закрывающие скобки и фигурные скобки, мгновенно исправляя их.
Из естественного языка в диаграмму
Возможно, самой мощной функцией является создание диаграмм на основе описаний на естественном языке. С помощью таких инструментов, как OpenDocs (платформа документации VP), вы можете просто описать, что хотите:
«Создайте блок-схему, показывающую вход пользователя. Если учётные данные верны, перенаправьте на панель управления. Если неверны, покажите ошибку и разрешите 3 попытки. После 3 неудач заблокируйте учётную запись.»
Сгенерированный ИИ Mermaid:
flowchart TD
Start([User Attempts Login]) --> EnterCreds[Enter Email & Password]
EnterCreds --> Validate{Validate Credentials}
Validate -->|Valid| Dashboard[Redirect to Dashboard]
Validate -->|Invalid| CheckAttempts{Attempts < 3}
CheckAttempts -->|Yes| Increment[Increment Attempt Counter]
Increment --> ShowError[Show Error Message]
ShowError --> EnterCreds
CheckAttempts -->|No| LockAccount[Lock Account for 15 min]
LockAccount --> SendAlert[Send Security Alert Email]
SendAlert --> End([Process Ends])
Dashboard --> End
Перевод между типами диаграмм
ИИ также может переводить между различными форматами диаграмм. Нужно преобразовать диаграмму PlantUML в Mermaid? Инструменты ИИ могут это сделать:
Входные данные PlantUML:
@startuml
actor User
participant "Frontend" as FE
participant "Backend" as BE
database "DB" as DB
User -> FE: Click Login
FE -> BE: POST /login
BE -> DB: SELECT user
DB --> BE: user data
BE --> FE: JWT token
FE --> User: Show Dashboard
@enduml
Преобразованный ИИ Mermaid:
sequenceDiagram
actor User
participant Frontend
participant Backend
participant Database
User->>Frontend: Click Login
Frontend->>Backend: POST /login
Backend->>Database: SELECT user
Database-->>Backend: user data
Backend-->>Frontend: JWT token
Frontend-->>User: Show Dashboard
Интеграция с интерактивным чат-ботом
Некоторые платформы теперь предлагают интерфейсы чат-ботов для создания диаграмм. Вы можете вести диалог:
Пользователь: «Добавьте новую службу под названием «Служба инвентаризации» в мою диаграмму архитектуры.»
ИИ: «Я добавлю Сервис инвентаризации, подключённый к вашим существующим Сервисам продуктов и заказов.»
Диаграмма обновляется автоматически
Пользователь: «На самом деле, заставь его также подключиться к новой базе данных под названием «InventoryDB».»
ИИ: «Готово. Сервис инвентаризации теперь подключён к Сервису продуктов, Сервису заказов и новой базе данных InventoryDB.»
Интеграция диаграмм как кода в ваш рабочий процесс
Шаг 1: Начните с малого
Не пытайтесь сразу нарисовать всю систему. Начните с одного компонента — например, с вашего потока аутентификации или новой функции, которую вы разрабатываете.
Шаг 2: Встраивание в документацию
Храните ваши .mermaid файлы рядом с вашей документацией (например, в папке /docs). Используйте инструменты, такие как mermaid-cli для их рендеринга в процессе сборки.
Шаг 3: Используйте унифицированный движок VPasCode
Если вы работаете в команде с разнообразными предпочтениями, VPasCode бесценен. Он поддерживает несколько языков диаграмм как код в одном месте:
# В VPasCode вы можете комбинировать:
diagrams/
├── architecture.mermaid
├── deployment.puml # PlantUML
├── database-erd.mermaid
└── workflow.d2 # Язык D2
Шаг 4: Автоматизация с помощью CI/CD
Добавьте шаг в ваши GitHub Actions или GitLab CI:
- name: Рендеринг диаграмм Mermaid
run: |
for file in $(find docs -name "*.mermaid"); do
npx @mermaid-js/mermaid-cli -i $file -o ${file%.mermaid}.png
done
- name: Загрузка на сайт документации
run: |
aws s3 sync docs/ s3://your-docs-bucket/
Шаг 5: Проверка в pull-запросах
Введите в политику правило: все изменения архитектуры требуют обновления диаграмм. Используйте комментарии в PR для обсуждения визуальных изменений:
Ревизор: «Не должна ли кеш-память находиться между Сервисом заказов и базой данных? В настоящее время она подключена только к Сервису пользователей.»
Автор: «Отличное замечание. Я обновлю диаграмму.»
Реальное влияние: кейс-стади
Рассмотрим финтех-стартап, который внедрил подход «Диаграммы как код» с использованием Mermaid и VPasCode:
-
До: 47 статических файлов Visio, большинство из которых старше 6 месяцев. Новым сотрудникам требовалось 3 недели, чтобы понять архитектуру.
-
После: 12 диаграмм Mermaid, все хранятся в Git и обновляются с каждой новой функцией. Новые сотрудники стали продуктивными уже в первую неделю.
Технический директор команды отметил: «Мы перешли от того, что диаграммы были просто галочкой для соответствия требованиям, к тому, что они стали живой частью нашего процесса разработки. Когда мы обсуждаем новую архитектуру, мы открываем редактор Mermaid и буквально набрасываем её в коде. Это меняет правила игры.»
Будущее: непрерывная документация
Конечная цель — «непрерывная документация», при которой диаграммы генерируются автоматически на основе вашей инфраструктуры или кода. Уже появляются инструменты, которые могут:
-
Сканировать манифесты Kubernetes и генерировать диаграммы топологии сервисов
-
Анализировать файлы OpenAPI/Swagger и создавать диаграммы потоков API
-
Мониторить облачные ресурсы и автоматически обновлять диаграммы архитектуры
Mermaid находится в центре этого движения, предоставляя простой текстовый формат, который могут генерировать машины и понимать люди.
Начните сегодня
Готовы выйти за рамки статических изображений? Вот ваш план действий:
-
Установите расширение Mermaid в вашей любимой среде разработки (VS Code, IntelliJ)
-
Создайте свою первую диаграмму в файле
.mdс использованием синтаксиса Mermaid -
Попробуйте бесплатный тариф VPasCode чтобы познакомиться с диаграммированием на базе ИИ
-
Начните создание живого репозитория документации рядом с вашей кодовой базой
-
Поделитесь этой статьёй со своей командой и начните обсуждение
Ваша архитектура заслуживает большего, чем пыльная диаграмма в забытой папке. Пора относиться к вашим диаграммам как к критически важным активам.
