Диаграммы как код: одна из лучших идей, которые разработка подхватила за последнее десятилетие. Диаграмму в текстовом файле можно проверить на ревью, сравнить через diff и откатить. Она путешествует вместе с кодом, который описывает, и никогда не теряется в чьей-то папке загрузок.
Есть одна загвоздка, и каждый, кто хранил диаграмму как код, точно знает какая. Текст прекрасно подходит, чтобы хранить диаграмму, и ужасно подходит, чтобы её раскладывать. Как только вы хотите сдвинуть один блок на два сантиметра влево, вы снова в синтаксисе: угадываете ранги, направления и невидимые правила раскладки и перерендериваете, пока движок наконец не поставит элемент туда, куда с самого начала хотел ваш глаз.
Доска: недостающая половина
Люди тянутся к доске потому, что она отвечает на другой вопрос. Код отвечает на вопрос «что является источником истины». Доска отвечает на вопрос «выглядит ли это правильно». Вы указываете на блок и тащите его. Обводите рискованный путь красным. Вы не думаете о том, как закодирована раскладка, потому что кодировки нет; есть только картинка и ваша рука.
Подход LetDraw: выбирать не нужно. Вставьте код диаграммы, и он станет настоящими редактируемыми фигурами на холсте. Не плоской картинкой, на которую можно только смотреть, а настоящими блоками и стрелками, которые можно взять. Вот такой исходник большинство команд уже хранит в репозитории:
graph TD A[Client] --> B[API Gateway] B --> C[Auth Service] B --> D[Orders Service] D --> E[(Database)]
Импортируйте этот Mermaid, и LetDraw выдаст вам не его картинку. Он выдаст граф в виде фигур, которые можно двигать:
Теперь рутина позади. Вы не настроили ни одной директивы раскладки. Первый вариант достался бесплатно, и всё на холсте можно менять.
Сдвинуть блок, поправить заметку, выделить путь
Поскольку импорт создаёт настоящие фигуры, половина «доска» просто работает. Вы делаете то, что мучительно в тексте и тривиально руками:
- Сдвинуть блок туда, куда хочет глаз, не перерендеривая для проверки
- Изменить стиль узла, чтобы важный выделялся среди остальных
- Добавить заметку рядом с частью, о которой ревьюеры всегда спрашивают
- Выделить путь, чтобы показать поток запросов, который важен сегодня
Стрелки помогают, а не мешают. Встроены собственные наконечники в начале и конце, а также полые UML-наконечники для наследования и кардинальность ER в нотации «воронья лапка» для работы со схемами. Вам никогда не придётся рисовать маркер от руки или изображать нотацию повёрнутым треугольником. А когда вы перетаскиваете блок через другой, умные соединители автоматически прокладывают стрелку в обход ваших фигур, и линия остаётся чистой, а не перерезает узел.
Текст: место, где диаграмма должна жить. Холст: место, где её нужно раскладывать. Выбирать одно из двух не придётся.
Весь смысл в обратном пути в Mermaid или D2
Вот что делает всё это честным. Закончив правки, вы экспортируете рисунок обратно в Mermaid или D2. Диаграмма возвращается в репозиторий как код, который проверяется в пул-реквесте, как всё остальное. Цикл выглядит так:
- Код в репозитории: источник истины, с diff и ревью
- Холст: место, где человек раскладывает диаграмму и делает её читаемой
- Снова код на выходе, чтобы улучшенная раскладка уходила как текст
Именно этот последний шаг отличает «я один раз импортировал диаграмму» от «диаграмм как кода, которые человек действительно готов поддерживать». Синтаксис перестаёт быть стеной. Вы сохраняете проверяемость кода и удобство доски, и ни одно не проигрывает.
Как попробовать визуальное редактирование Mermaid
Откройте холст, выберите «Создать из кода» и вставьте фрагмент Mermaid или D2, который у вас уже есть. Двигайте блоки, пока диаграмма не будет читаться так, как вы нарисовали бы её на стене. Затем экспортируйте обратно в код и положите в репозиторий. Весь путь, от кода к холсту и снова к коду, занимает примерно столько же, сколько чтение этого текста.