Диаграммы из кода

Пишите на Mermaid, D2 или nwdiag и получайте настоящие фигуры на доске, которые синхронизируются с кодом в обе стороны.

В Doska диаграмма — это одновременно код и фигуры. Вы пишете на Mermaid, D2 или nwdiag, нажимаете «Применить», и код превращается в обычные объекты доски: фигуры, стрелки и рамки групп. Их можно двигать, перекрашивать и комментировать. Если потом поменять код, диаграмма обновится на месте, а ваша ручная раскладка сохранится.

#Какую нотацию выбрать

Язык определяется по коду: у Mermaid есть заголовок (flowchart, sequenceDiagram, architecture-beta), nwdiag начинается с nwdiag {, всё остальное читается как D2. Если в процессе есть пронумерованные шаги, берите sequenceDiagram: нумерованные стрелки в обычном графе быстро превращаются в кашу.

#Как создать диаграмму

1. На доске нажмите «Код» в верхней панели или ⌘/Ctrl+E, чтобы открыть панель кода.
2. Начните с шаблона («Процесс», «Архитектура», «AWS: VPC и подсети», «Последовательность», «Сеть» и другие) или напишите код сами.
3. Нажмите «Применить» или ⌘/Ctrl+Enter. Фигуры появятся на доске.

Ещё два способа: скопируйте код Mermaid и нажмите ⌘/Ctrl+V на доске или выделите нарисованные руками фигуры, стрелки и кадры и нажмите «В диаграмму» на панели выделения. Рисунок станет кодом, а всё останется на своих местах: если есть AWS-кадры или все фигуры — иконки, получится architecture-beta, иначе flowchart.

#Mermaid

Поддерживаются flowchart (или graph), sequenceDiagram и architecture-beta. Другие типы Mermaid (class, state, ER, gantt) отклоняются с ошибкой.

#flowchart

flowchart LR
  user([Клиент]) --> web[Веб-приложение]
  web -->|REST| api[API заказов]
  subgraph backend [Бэкенд]
    api --> db[(База заказов)]
    api -.-> queue[[Очередь событий]]
  end
  classDef hot fill:#fee2e2,stroke:#dc2626
  class db hot

• Направления: TB, TD, BT, LR, RL.
• Формы: [ ], ( ), ([ ]), [[ ]], [( )], (( )), { }, {{ }}, параллелограммы, трапеции и запись Mermaid 11 id@{ shape: cyl, label: "Заказы" }.
• Связи: -->, ---, -.->, ==>, --o, --x, <-->, ~~~ (невидимая). Подписи — -->|текст| или -- текст -->. Работают цепочки и a & b --> c. Запись a e1@--> b даёт связи стабильный ID.
• Группы: subgraph id [Название] … end становится рамкой вокруг своих узлов.
• Стили: classDef, class, :::class, style, linkStyle со свойствами fill, stroke, color, stroke-width, stroke-dasharray.

#sequenceDiagram

sequenceDiagram
  autonumber
  actor dev as DevOps
  participant api as kube-apiserver
  participant etcd@{ "type": "database" }
  dev->>api: kubectl apply
  api->>etcd: сохраняет объект
  etcd-->>api: ok
  alt успех
    api-->>dev: 201 Created
  else ошибка
    api--xdev: 500
  end

• Участники: participant, actor, participant id@{ "type": "database" }.
• Стрелки: ->> сплошная, -->> пунктир, -x / --x ошибка, -) асинхронное сообщение, -> без наконечника, <<->> в обе стороны.
• Блоки: loop, alt/else, opt, par/and, critical/option, break, rect rgb(…); заметки Note left of, right of, over a,b.

Раскладка задаётся кодом: участники идут колонками, сообщения — строками.

#architecture-beta

architecture-beta
    group region(aws:group-region)[eu-central-1]
    group vpc(aws:group-vpc)[VPC] in region
    group pub(aws:group-public-subnet)[Публичная подсеть] in vpc
    group priv(aws:group-private-subnet)[Приватная подсеть] in vpc

    service users(aws:users)[Пользователи]
    service alb(aws:alb)[ALB] in pub
    service app(aws:ecs)[Приложение] in priv
    service db(aws:aurora)[Aurora] in priv
    service s3(aws:s3)[Файлы в S3]

    users:R --> L:alb
    alb:R --> L:app
    app:R -- L:db
    db{group}:R --> L:s3

• group id(иконка)[Название] in родитель рисует рамку. Иконки групп AWS: aws:group-cloud, aws:group-region, aws:group-az, aws:group-vpc, aws:group-public-subnet, aws:group-private-subnet, aws:group-security-group, aws:group-asg, aws:group-account и другие.
• service id(иконка)[Название] in группа принимает любую иконку aws:* или встроенные иконки Mermaid cloud, database, disk, internet, server.
• a:R --> L:b соединяет стороны T, B, L, R; -- — без стрелок, <-- и <--> ставят стрелку в начале или с обеих сторон. a{group}:R начинает связь от рамки группы, где лежит a. Подписей у связей нет.

#D2

direction: right
devops: DevOps { shape: person }
aws: AWS Cloud {
  icon: aws:group-cloud
  vpc: VPC {
    icon: aws:group-vpc
    api: kube-apiserver { icon: aws:eks }
    db: etcd { shape: cylinder }
    api -> db: состояние
  }
}
ecr: ECR { icon: aws:ecr }
devops -> aws.vpc.api: kubectl apply
ecr -> aws.vpc.api: pull { style.stroke-dash: 4 }

• Узлы и контейнеры: ключ: Подпись — узел, ключ: Подпись { … } — контейнер, он рисуется рамкой. Путь a.b.c указывает внутрь контейнеров, _ — на родителя. direction задаётся для всей схемы и для отдельного контейнера.
• Связи: ->, <-, <->, --, цепочки, подписи a -> b: текст.
• Свойства: shape (rectangle, cylinder, queue, diamond, oval, circle, hexagon, page, document, person…), icon (ID группы AWS на контейнере рисует рамку AWS), style со свойствами fill, stroke, font-color, stroke-width, stroke-dash.
• Не поддерживается (будет предупреждение): classes, vars, imports, layers, scenarios, steps, grid, near, шаблоны *, ссылки на связи.

#nwdiag

nwdiag описывает сетевую топологию: офисную сеть, VLAN, DMZ, план адресов.

nwdiag {
  internet [shape = cloud];
  internet -- fw;
  network dmz {
    address = "10.0.1.0/24";
    fw [address = "10.0.1.1", icon = net:firewall];
    web01 [address = "10.0.1.10"];
  }
  network internal {
    address = "10.0.2.0/24";
    label = "Внутренняя сеть";
    web01 [address = "10.0.2.10"];
    db01 [address = "10.0.2.20", description = "PostgreSQL"];
  }
  group { label = "Веб"; color = "#fef3c7"; web01; }
}

• Сеть — это полоса с именем и диапазоном; хосты подключены к ней линиями с адресом. Хост, указанный в двух сетях, соединяет их. a -- b; — прямая связь двух хостов.
• Хосты: address (можно несколько через запятую), label, description, icon или shape. Без иконки устройство угадывается по имени (router1, fw, sw1, db01), остальные рисуются серверами.
• Сети: address, label, description, color. Группы: label, color.
• Проверки: адрес вне диапазона своей сети, один адрес у двух хостов, неверный диапазон.

#Иконки

• aws:* — сервисы и рамки групп AWS, например aws:lambda, aws:s3, aws:rds, aws:dynamodb, aws:api-gateway, aws:alb, aws:sqs, aws:eks, aws:users.
• net:* — обычные сетевые устройства: net:router, net:switch, net:firewall, net:vpn, net:wifi, net:server, net:internet, net:laptop, net:load-balancer, net:cloud, net:database, net:user, net:storage, net:proxy.

Во flowchart иконка задаётся формой icon из Mermaid 11:

flowchart LR
  api@{ icon: "aws:api-gateway", label: "API Gateway" }
  fn@{ icon: "aws:lambda", label: "Обработчик" }
  db@{ icon: "aws:dynamodb", label: "Заказы" }
  api --> fn --> db

Чтобы узнать ID, откройте библиотеку иконок (клавиша I) и наведите курсор на иконку. В редакторе после icon: " работает автодополнение. Неизвестная иконка даёт предупреждение, а узел становится прямоугольником.

#Синхронизация кода и холста

#Из кода на холст

Код определяет, какие узлы, связи и группы существуют, их подписи и принадлежность к группам. Формы, цвета и стили линий из кода тоже применяются, но заменяют ручную правку, только если вы поменяли их в коде. На холсте остаются позиции, размеры, маршруты стрелок и всё оформление, которого нет в коде.

При применении нового кода неизменившиеся элементы не двигаются, новые узлы ставятся рядом с соседями, а удалённые из кода исчезают с доски (ваши собственные стрелки к ним отвязываются, но не удаляются). Другие объекты доски не затрагиваются никогда. Заново расставляет все узлы только команда «Перераскладка».

#С холста в код

Для Mermaid flowchart и architecture-beta структурные правки на доске сразу записываются в код. Меняются только затронутые строки, комментарии и стили остаются.

Правка на холсте и изменение кода — один шаг отмены. Позиции и цвета остаются на доске и в код не пишутся. D2, nwdiag и sequenceDiagram меняются только в коде.

#Подсветка и предпросмотр

Узел или связь под курсором в коде подсвечивается на доске, а выделенное на доске отмечается в коде. Перед применением доска показывает изменения: новые элементы — зелёным пунктиром, изменённые — жёлтым, удаляемые — красным.

Код можно править вместе, курсоры других людей видны. В «Истории» хранятся последние 30 применённых версий. Как обновлять диаграмму из CI, описано в разделе API.

#Ошибки и лимиты

Ошибки и предупреждения показываются рядом со строками, клик по ним переводит к нужной строке. Пока в коде есть ошибки, «Применить» недоступно, а на доске остаётся последняя рабочая версия.

Не поддерживаются: click и callback-и, директивы %%{init}%%, анимации связей, другие CSS-свойства, иконки вне aws:* и net:*, картинки в узлах.