Диаграммы Mermaid Архитектура документа на Markdown без нажатия на что-либо

Ваша архитектурная диаграмма была точной тогда, когда вы её рисовали. Это было три спринта назад. Сейчас она находится в общей Google-презентации, которую никто не обновляет, и инженер, который создал сервис, описываемый в этой диаграмме, уже перешёл в другую команду. Звучит знакомо?

Диаграммы Mermaid решают эту проблему с другой стороны. Вместо драг-и-дроп-панели, которая находится вне вашего кода, вы пишете диаграммы в виде текста — простой синтаксис Markdown, который находится в README, подвергается контрольным версиям вместе с кодом и отображается там, где отображается Markdown. Когда архитектура изменяется, вы изменяете один текстовый файл. Разница в этом файле рассказывает всю историю.

Что такое Mermaid (и почему диаграммы как код важны)

Mermaid — это открытый язык для создания диаграмм, который отображает диаграммы из простого текста. Вы пишете диаграмму в защищённом блоке кода; рендерер (или просмотрщик, поддерживающий Mermaid) превращает её в диаграмму SVG. Не нужны учётные записи, не нужны шаги экспорта, не бывает «формат диаграммы не поддерживается на этом устройстве».

Подход «диаграммы как код» оправдывает себя несколькими конкретными способами:

• Контроль версий — диаграммы находятся в Git. Вы можете сравнивать их, откатывать и привязывать к той же ветке, что и код, описываемый диаграммой.
• Отсутствие зависимости от поставщика — простой текст является портативным. Вы можете переключиться на другой рендерер, перекомпилировать репозиторий, экспортировать в Confluence — исходный код всегда читаем.
• Близость к коду — диаграмма, находящаяся в том же репозитории, что и сервис, описываемый диаграммой, гораздо более вероятна, что она останется актуальной, чем диаграмма в общей презентации.
• Поддержка автоматизации — вы можете генерировать синтаксис Mermaid из кода (схемы баз данных, спецификации API, цепочки CI) с помощью скриптов или ИИ.

Перед тем как перейти к типам диаграмм, вы можете мгновенно просмотреть любую синтаксис Mermaid — без установки локально — с помощью Рендерера диаграмм Mermaid на iotools.cloud. Вставьте, посмотрите результат, итерируйте. Используйте это вместе с этой инструкцией, чтобы запустить каждый пример в режиме реального времени.

Флойчарты: основной инструмент

Флойчарты — наиболее распространённый тип диаграммы Mermaid, и это обусловлено тем, что они охватывают всё от простых деревьев решений до сложных потоков между сервисами. Вот синтаксис, охватывающий 90% реальных случаев использования:

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

Некоторые важные моменты о синтаксисе флойчартов:

• Направление: TD (сверху вниз), LR (слева направо), BT (снизу вверх), RL (справа налево)
• Формы узлов: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• Метки на рёбрах: -- label --> или -->|label|
• Подграфы: группируют связанные узлы визуально

Подграфы особенно полезны для показа границ сервисов:

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

Схемы последовательности: показывают потоки API-запросов

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

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

Твёрдые стрелки (->>) — запросы; пунктирные стрелки (-->>) — ответы. Строка participant управляют порядком появления блоков в верхней части диаграммы. Вы также можете использовать actor для участников человека, activate/deactivate чтобы показать время обработки, и loop или alt блоки для условных потоков.

Диаграммы сущностей и отношений: схемы баз данных в документации

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

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

Обозначение кардинальности: || точно один, o| ноль или один, o{ ноль или много, |{ один или много. Метка отношения ("места", "содержит") помещается в кавычки в конце.

Диаграммы состояний: моделирование потоков и машин состояний

Каждый раз, когда у вас есть сущность, которая переходит из одного состояния в другое — заказ, подписка, задание CI — диаграмма состояний точнее, чем флойчарт. Синтаксис диаграммы состояний в Mermaid напрямую соответствует тому, как вы определяете машину состояний в коде:

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] обозначает начальное и конечное состояние. Переходы несут событие, которое их инициирует. Вы можете вложить состояния для составных состояний и использовать note блоки для аннотации переходов дополнительным контекстом.

Диаграммы классов: структуры ООП для инструкций по настройке

Диаграммы классов наиболее полезны при настройке инженеров в объектно-ориентированном коде или при документировании доменной модели. Mermaid охватывает наследование, интерфейсы, состав и сигнатуры методов:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean isIndoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

Модификаторы видимости следуют традиции UML: + публичный, - приватный, # защищённый. Стрелки отношений охватывают ассоциацию (-->), наследование (<|--), состав (*--) и агрегацию (o--).

Где Mermaid отображается по умолчанию

Главное преимущество Mermaid — его поддержка в уже используемых инструментах разработчиков:

• GitHub — защищённые блоки кода Mermaid (```mermaid) отображаются в README, заявках, описаниях веток и вики как с 2022 года.
• GitLab — поддержка Mermaid в файлах Markdown и вики-страницах.
• Notion — вставьте блок кода Mermaid в блок кода, установленный на «Mermaid», и он будет отображаться в тексте.
• VS Code — расширение «Поддержка Mermaid в предварительном просмотре Markdown» отображает диаграммы в встроенной панели предварительного просмотра.
• Obsidian — Mermaid отображается по умолчанию без каких-либо плагинов.
• Docusaurus, MkDocs, Astro — существуют плагины Mermaid для всех основных генераторов статических сайтов.
• Confluence — через приложение «Диаграммы Mermaid для Confluence».

Если вы пишете документацию, которая будет размещаться в GitHub или GitLab, диаграммы Mermaid работают без настройки.

Проблемы и случаи, когда стоит использовать что-то иное

Mermaid не подходит для всех ситуаций. Некоторые моменты, на которые стоит обратить внимание:

• Сложные разметки — алгоритм автоматической разметки Mermaid не всегда даёт чистые результаты для больших графов. Если у вас есть 50+ узлов с множеством пересекающихся рёбер, возможно, потребуется переструктурировать или вручную разбить диаграммы.
• Отображение в Confluence — Confluence не поддерживает Mermaid по умолчанию; требуется платное приложение. Если ваша команда использует Confluence, необходимо предусмотреть расходы на это или использовать draw.io.
• Нестандартные типы диаграмм — диаграммы сетей, диаграммы развертывания и диаграммы C4 архитектуры требуют обходных путей или не поддерживаются должным образом.
• Контроль стиля — опции тематики в Mermaid ограничены. Для диаграмм с брендированными цветами и шрифтами вам придётся тратить время на борьбу с рендерером.

Основные альтернативы, которые стоит знать:

• PlantUML — более старый, более громоздкий синтаксис, но более богатая поддержка UML и лучшее взаимодействие с Confluence. Требуется Java локально или серверный рендерер.
• D2 — современный инструмент «диаграммы как код» с более чистым контролем разметки и лучшим управлением большими диаграммами. Меньшая экосистема по сравнению с Mermaid, но быстро растёт.
• draw.io / Excalidraw — графические инструменты, когда вам нужно точное визуальное управление и вы не хотите, чтобы диаграмма находилась вне контроля версий.

Для большинства документов разработчиков — README сервисов, потоки API, руководства по настройке — Mermaid хорошо охватывает нужный сценарий, и поддержка GitHub по умолчанию делает его оправданным для изучения.

Предварительный просмотр Mermaid без установки ничего

Если вы экспериментируете с синтаксисом или хотите поделиться диаграммой с кем-то, у кого нет установленного локального рендерера, то Рендерера диаграмм Mermaid на iotools.cloud предоставляет вам живой просмотр без регистрации, без установки и без настройки. Вставьте свой код Mermaid, посмотрите отображаемую диаграмму и скопируйте результат.

Это полезно для проверки синтаксиса диаграммы перед коммитом, для передачи отображённой версии в сообщение в Slack или для прототипирования диаграммы, которую вы позже вставите в README.

Начните с флойчарта

Если вы никогда не писали диаграмму Mermaid, начните с флойчарта. Выберите процесс в вашем коде, который вы хотели бы документировать — жизненный цикл запроса, фоновая задача, пайплайн развертывания — и напишите его в синтаксисе Mermaid за 10 минут. Вставьте его в README в блоке ```mermaid и отправьте. GitHub автоматически отобразит его.

Одна диаграмма, контролируемая версиями и живущая рядом с кодом, описываемым диаграммой, стоит дороже слайд-документа, которого никто не доверяет.

Вам также может понравиться