Руководство по синтаксису диаграмм Mermaid.js

Что такое диаграмма потоков?

A Диаграмма потоков — это основной поведенческий карта, визуализирующая пошаговый рабочий процесс, алгоритмическую процедуру или последовательную бизнес-логику. Представляя действия системы в виде различных геометрических фигур и отображая поток управления с помощью направляющих стрелок, диаграмма потоков позволяет программистам и архитекторам систем легко отслеживать условные пути выполнения, выделять блоки, являющиеся узкими местами, и анализировать циклы логики системы до написания фактического кода серверной части.

С помощью Mermaid.js, вам не нужно тратить часы на перетаскивание блоков, микроменеджмент линий сетки или пересчет переменных отступов. Двигатель компоновки динамически вычисляет координаты узлов из ваших исходных декларативных скриптов, позволяя вам полностью сосредоточиться на лежащей в основе логике вашей системы.

Руководство по основному синтаксису: элементы и конструкции

Чтобы создать элегантную, легко читаемую диаграмму потоков в Mermaid, необходимо овладеть индикаторами направления холста, геометрическими обрамлениями узлов, переменными соединений и структурными подграфами.

1. Установка направления холста

Ориентация вашей диаграммы потоков определяется непосредственно в первой строке с помощью пары ключевых слов, применяемых к обертке graph или flowchartобертке. Вы можете управлять направлением визуального масштабирования своей компоновки, используя четыре основных ключа ориентации:

• flowchart TD (сверху вниз / вертикальная ориентация)
• flowchart BU (снизу вверх)
• flowchart LR (слева направо / горизонтальная ориентация)
• flowchart RL (справа налево)

2. Настройка геометрии узлов (формы)

По умолчанию объявление простого идентификатора отображается как острый прямоугольный блок. Чтобы сделать ваши диаграммы более легко читаемыми, используйте специализированные скобки Mermaid, чтобы мгновенно добавить визуальный контекст к различным этапам рабочего процесса. Каждый блок определения должен быть предварён токеном направления компоновки для правильного синтаксического анализа:

• Скруглённые края: id(Текст) — Представляет общий этап процесса.
• Форма стадиона/капсулы: id([Текст]) — Стандартный маркер для начальных и конечных контрольных точек границ.
• Подпрограмма/Предопределенный процесс: id[[Текст]] — Представляет инкапсулированную системную подпрограмму или внешний скрипт класса.
• Цилиндр/База данных: id[(Текст)] — Представляет постоянное хранение в базе данных, кэши или хранилища данных.
• Ромб/Диаграмма принятия решений: id{Текст} — Представляет условные переключатели, ветвления if/else или точки оценки.
• Параллелограмм: id[/Текст/] или id[Текст] — Отображает наклонные границы для представления явного ввода/вывода данных (I/O).

flowchart TD
    start_node([Запуск выполнения])
    query_db[(Экземпляр PostgreSQL)]
    validate_check{Авторизовано?}

3. Правила подключения линий и встроенные метки

Вы можете настроить линии соединения для отображения различных структурных отношений и стилей коммуникации. Чтобы сохранить чистоту ваших диаграмм, добавьте описательные метки непосредственно на пути соединений:

flowchart TD
    %% Стандартная стрелка соединения с текстовой меткой
    A --> |"Полезная нагрузка JSON"| B

    %% Пунктирная/асинхронная линия с текстовой меткой
    B -.-> |"Асинхронное событие"| C

    %% Толстая жирная линия с текстовой меткой
    C ==> |"Критическая запись"| D

4. Модульная изоляция с помощью подграфов

Чтобы установить четкие границы сети, объединить микросервисы или изолировать ответственность команд, объедините ваши элементы внутри структурныхподграфоберток. Вы определяете подграф, присваивая ему внутренний идентификатор, необязательный заголовок отображения и закрывая его с помощьюконец тег:

flowchart TD
    subgraph auth_sub["Граница безопасности"]
        gateway[Шлюз API] --> auth_worker(Валидатор токенов)
    end

Лучшие практики для чистых диаграмм

• Разделяйте макеты горизонтально: Для длинных многоэтапных инженерных пайплайнов выберите flowchart LR направление. Это масштабируется намного чище на стандартных широкоэкранных мониторах в ландшафтном режиме, чем длинный вертикальный макет.
• Выделяйте сложные циклы: Если рабочий процесс содержит интенсивный цикл повторений, ясно обозначьте обратный соединитель (например, retry --> |"Повторная попытка"| start) чтобы читатели не путали цикл со стандартным прямым путём.
• Избегайте смешивания типов графов: Придерживайтесь современного flowchart ключевого слова вместо устаревшего graph флага при отрисовке сложных карт. Двигатель flowchart использует обновлённый алгоритм размещения, который поддерживает сложные комбинации стрелок и более чистое прохождение путей.

Примеры диаграмм Mermaid.js из реальной жизни

Пример 1: Микросервисная архитектура на основе событий (архитектура слева направо)

Этот функциональный чертёж моделирует сервис приёма веб-телеметрии. Он показывает, как объединять входные данные, ромбы с решениями и формы облачных баз данных на чётком горизонтальном холсте.

flowchart LR
    %% Определение узлов элементов с явными геометрическими формами
    init([Сработал вебхук]) --> input_io[/Перехват HTTP-запроса/]
    input_io --> auth_check{Проверка токена}
    
    auth_check --> |"Неверный токен"| err_stop([Вернуть 401 Неавторизовано])
    auth_check --> |"Действительный JWT"| write_queue[[Публикация в очередь Kafka]]
    
    write_queue --> worker_proc(Демон-потребитель)
    worker_proc --> db_store[(Кластер TimescaleDB)]
    db_store --> term([Завершённый поток])

    %% Быстрые переопределения стилей
    style auth_check fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style err_stop fill:#f8d7da,stroke:#dc3545,stroke-width:1px

Разбор синтаксиса: Этот диаграмма плавно течет слева направо. Шаг проверки использует желтую форму ромба с решением (auth_check{Проверка токена}), что четко разделяет путь выполнения на два различных результата. Хранилища данных мгновенно узнаваемы благодаря их пользовательским цилиндрам баз данных ([(Кластер TimescaleDB)]), а также параллелограммным входам.

Пример 2: Многоуровневая система регистрации пользователей для предприятия (вертикальная с вложенными подграфами)

Этот продвинутый корпоративный чертеж отображает путь регистрации приложения. Он организует шаги вертикально по трем отдельным структурным подграфам, чтобы представить различные архитектурные уровни.

flowchart TD
    subgraph Client_Tier["Слой пользовательского интерфейса"]
        app[Интерфейс мобильного приложения]
        web[Веб-фронтенд SPA]
    end

    subgraph Service_Tier["Основной маршрутизатор шлюза"]
        proxy[[Обратный прокси Nginx Ingress]]
        auth_svc(Рабочий процесс службы аутентификации)
    end

    subgraph Persistence_Tier["Защищённый центр обработки данных"]
        main_db[(Основная база данных учетных записей пользователей)]
        cache_node[(Кэш сессий Redis)]
    end

    %% Определение каналов связи между подсистемами
    app -- "Запрос HTTPS" --> proxy
    web -- "Запрос HTTPS" --> proxy
    
    proxy --> |"Перенаправить /v1/auth"| auth_svc
    
    auth_svc --> |"Проверить сессию"| cache_node
    auth_svc --> |"Записать учетную запись"| main_db

Разбор синтаксиса: Указатель ориентации сверху вниз (flowchart TD), который заставляет движок компоновки аккуратно размещать компоненты сверху вниз. Группирующие блоки объединяют связанные компоненты в отдельные слои (клиентский, сервисный и хранение данных), придавая общей архитектуре интуитивное и высокоструктурированное ощущение.