Прежде чем приступать к конкретным архитектурным схемам, таким как сложные диаграммы потоков или хронологические временные линии, необходимо понимать основные правила, которые регулируютПрактическое руководство по Mermaid. Mermaid использует чистую, высоконаглядную систему текстовой нотации. Как только вы поймете, как движок инициализирует тип холста, называет структурные компоненты и направляет направляющие стрелки, написание любой сложной схемы системы становится полностью естественным.
Этот краткий обзор охватывает общие механики структурного синтаксиса, применимые ко всем типам диаграмм Mermaid в рабочей среде VPasCode.
1. Обязательные обертки для типов диаграмм
Каждый блок кода Mermaid должен начинаться с явного объявления его типа диаграммы на самой первой строке. Это сообщает парсеру VPasCode, какой именно структурный движок нужно запустить на холсте предварительного просмотра:
graph TD— Указывает на диаграмму потоков, организованную сверху вниз.sequenceDiagram— Указывает на хронологическую диаграмму временной линии выполнения.classDiagram— Указывает на структурный чертеж программного обеспечения с объектно-ориентированной архитектурой.
В отличие от других текстовых движков для диаграмм, Mermaid не требует закрывающих тегов. Парсер просто читает структурное объявление на первой строке и компилирует всё, что непосредственно находится ниже в контейнере вашего блока кода.
2. Объявление элементов: идентификаторы и отображаемые метки
При моделировании программной системы вы будете создавать различные структурные элементы, такие как компоненты, базы данных или микросервисы. В Mermaid вы объявляете элемент, определяя короткий внутренний буквенно-цифровой идентификатор, за которым сразу следует стиль в квадратных скобках, управляющий его визуальной формой, и удобное для пользователя отображаемое имя:
microservice_id[API обработки платежей]
db_id[(SQL-запросы пользовательских транзакций)]Почему это лучшая практика: Использование короткого, чистого внутреннего идентификатора (например,microservice_id) значительно ускоряет рисование линий связей позже. Если вам когда-либо понадобится изменить внешнюю метку с «API обработки платежей» на «Глобальная система оплаты», вам нужно будет изменить её только в одной строке объявления, а не обновлять десятки строк в вашем скрипте.
3. Освоение стрелок связей и направления маршрутизации
Связи между узлами системы рисуются с использованием комбинаций тире (-), знаков равенства (=), и угловых скобок стрелок (>). Стиль ваших линий даёт вам неявный контроль над тем, как автоматизированный движок компоновки масштабирует вашу диаграмму:
A --> Bрисует стандартную направленную стрелку, указывающую от элемента A прямо к элементу B.A --- Bрисует плоскую, ненаправленную линию связи без стрелки, идеально подходящую для простых ассоциаций.A -.-> Bсоздает пунктирную линию зависимости, которая является отраслевым стандартом для обозначения асинхронных зависимостей или вебхуков сети.A ==> Bсоздает толстую, жирную линию соединения, идеально подходящую для выделения основных путей обработки данных или критически важных связей инфраструктуры.
4. Добавление контекста в строке: метки и комментарии к коду
Четкая документация в значительной степени зависит от правильного контекста вокруг ваших визуальных линий и текстовых скриптов:
Метки для линий соединения
Вы можете добавить пояснительный текст непосредственно к любой линии соединения, вставив текстовую строку между двумя парами тире, или добавив символ вертикальной черты (“|Text|) сразу после вашего сопоставления отношений:
client_id -- "HTTPS POST /v1/checkout" --> api_id
client_id --> |HTTPS POST /v1/checkout| api_idНаписание комментариев к коду
Если вы хотите оставить административное примечание, кредит на дизайн или пояснение архитектуры внутри вашего скриптового файла, не отображая визуальную рамку на холсте, используйте двойные знаки процента (%%). Это сообщает движку пропустить анализ этой строки полностью:
%% TODO: Нам нужно обновить эту рамку границы после завершения миграции DevOps
[Устаревший монолит] --> [Новый микросервис]