Network diagram as code / Схема на мрежата като код

През последните няколко години се занимавам повече с документация. Да напиша обяснителен текст за това как работи дадена система — всъщност, това е доста лесно. Да нарисувам схема, на която ще бъдат показани всички ключови обекти и връзките между тях, също е напълно възможно.

Но най-проблемният момент е да поддържаш тази документация актуална. И не говорим само за текста, а и за схемите… Тъй като цялата документация е онлайн, т.е. в html формат, към текста се прикрепят картинки gif/jpeg/png, на които всъщност са изображени схемите. А схемите се рисуват в различни програми като Visio или онлайн услуги тип draw.io. След това експортираш схемата в графичен формат и я прикрепяш към html. Всичко звучи лесно.

В чем е проблемът?

Схемите обикновено са прости. По-точно, не особено сложни. Да, броят на обектите е десетина-два, а броят на връзките е приблизително толкова. Плюс надписи, някакви означения. Простите схеми могат да се опишат и с думи, а прекалено сложните, хм… (с) "не разбират-с". Има много схеми, трябва да се внасят периодични-епизодични промени, т.е. постоянно, тъй като те следват разработката на нашите продукти.

Може ли да вграждаш html на услугата? Пробвал ли си?

Да, разбира се. Например, на мен ми харесват графиките на gliffy.com. Но за промени трябва да отидеш в страничната услуга, там да редактираш. И е по-трудно да делегираш на колега да направи поправки.

Какво да правим?

Наскоро в GitHub ми попада в препоръките репозиторий github.com/RaoulMeyer/diagram-as-code. Диаграма като код. Т.е. описваме на js необходимата схема. Този js пишем направо в същия html, където е и останалият текст на документацията.

И да кажа, че не пиша документация изцяло в html. Обикновено документацията е набор от файлове с markdown текст, който след това се конвертира в напълно функциониращ сайт на документацията с помощта на някой движок, например wintersmith. Или wiki система.

Става много удобно: ето, написахме текста, след това отваряме таг script и в него се описва js кода на схемата.

Какво отново не е наред?

Този репозиторий ми харесва, но това не е единственият пример, когато схемата се рисува с помощта на код или текстово представяне. (В края на статията ще има линкове към проекти и статии, които намерих по темата diagram as code.)

И все пак, не съм единственият, който редактира документацията. Понякога и колегите допринасят — една дума да поправят, описание да променят, нови картинки да добавят. 

Поради това, бих искал да видя схемата в четим и разбираем текстов формат, който не изисква продължително обучение. А на места дори може просто да се направи copy-paste за ускоряване на добавянето на нова схема. 

Още един колега забеляза, че кодът е добре, но ако се използва структура, всичко може да бъде много строго и изразително.

Затова опитах да представя схемата като набор от няколко малки масива, които описват възли, връзки, групи от възли, както и положение на възлите. На мен ми се струва доста удобно, въпреки че, разбира се, на вкус и цвет...

Как е схемата в масив?

• Всеки възел се описва с идентификатор, който недвусмислено определя възела.
• Също така, на възела може да се добави икона и надпис.
• Между два възела може да се посочи връзка.
• За връзката на схемата може да се зададе цвят и надпис.
• Направлението на връзката се определя от източника към целта. А източникът и целта се указват с идентификаторите на възлите.
• Един или повече възли могат да бъдат добавени в група.
• Връзката също може да се указва и от група, и към група.

Потребявайки тези прости правила, се получава такава схема. Лесно? Напълно.

А тя се описва с този js код. Основното тук е обектът elements. В който са зададени nodes — възлите, edges — връзките.
 

  const elements = {
    nodes: [       // описваме възли
      { id: 'client', type: 'smartphone', label: 'Mobile App'},
      { id: 'server', type: 'server', label: 'Main Server'},
      { id: 'db1', type: 'database', label: 'DB 1'},
      { id: 'db2', type: 'database', label: 'DB 2'},
    ],
    edges: [       // указваме връзки
      { source: 'client', target: 'server', label: 'request' },
      { source: 'server', target: 'db1', label: 'request' },
      { source: 'server', target: 'db2', label: 'request' },
    ],
  };
  Diagram('scheme1', elements);

Разбира се, рисуването на схемата не съм го измислил сам, а ползвах библиотека. cytoscape.js — много мощен инструмент за визуализация. Част от възможностите ѝ в решението си използвам само. 

Ясно, това е прост пример. Може ли нещо по-сложно?

Да, моля. За указване на позиции — използваме positions, за указване на групи — указваме списък от групи в groups, а на самите елементи атрибут group.

А това е кодът:

<div id="scheme5" style="height:500px;width:800px;"></div>
<script>
  const elements5 = {
    groups: [
      { id: 'g1', label: 'Группа сервисов 1'},
      { id: 'g2', label: 'Группа сервисов 2'},
    ],
    nodes: [
      { id: 'man1', type: 'person', label: 'Человек'},
      { id: 'client', type: 'smartphone', label: 'Смартфон'},
      { id: 'agent-backend', type: 'server', group: 'g1', label: 'agent-backend'},
      { id: 'web', type: 'server', group: 'g1', label: 'Приложение admin'},
      { id: 'www', type: 'server', group: 'g1', label: 'страница загрузки'},
      { id: 'mongodb1', type: 'database', group: 'g1', label: 'Mongo DB 1'},
      { id: 'mongodb2', type: 'database', group: 'g1', label: 'Mongo DB 2'},
      { id: 'runner-integration1', type: 'worker', group: 'g1', label: 'отправка'},
      { id: 'runner-integration2', type: 'worker', group: 'g1', label: 'отправка'},
      { id: 'api', type: 'server', group: 'g1', label: 'API'},
      { id: 'server2', type: 'server', group:'g2', label: 'сервер'},
      { id: 'otherServer', type: 'server', group:'g2', label: 'сервер'},
      { id: 'firebase', type: 'cloud', label: 'Google Firebase'},
    ],
    edges: [
      { source: 'client', target: 'agent-backend', label: 'json', color: 'red' },
      { source: 'agent-backend', target: 'mongodb1', color: 'red' },
      { source: 'agent-backend', target: 'mongodb2',  color: 'red' },
      { source: 'mongodb1', target: 'runner-integration1', label: 'данные' },
      { source: 'mongodb2', target: 'runner-integration2', label: 'данные' },
      { source: 'mongodb1', target: 'web', label: 'данные для отображения' },
      { source: 'runner-integration1', target: 'server2', label: 'данные' },
      { source: 'runner-integration2', target: 'otherServer', label: 'данные' },
      { source: 'api', target: 'firebase', label: 'запросы', color: 'blue', },
      { source: 'firebase', target: 'client', label: 'push', color: 'blue'},
      { source: 'server2', target: 'api', label: 'уведомления', color: 'blue'},
      { source: 'man1', target: 'client', },
    ],
    positions: [
      { id: 'client', row: 2, col: 1,},
      { id: 'agent-backend', row: 2, col: 3,},
      { id: 'web', row: 6, col: 3,},
      { id: 'www', row: 1, col: 3,},
      { id: 'mongodb1', row: 1, col: 4,},
      { id: 'mongodb2', row: 2, col: 5,},
      { id: 'runner-integration1', row: 3, col: 3,},
      { id: 'runner-integration2', row: 4, col: 3,},
      { id: 'api', row: 5, col: 3,},
      { id: 'server2', row: 6, col: 7,},
      { id: 'otherServer', row: 4, col: 7,},
      { id: 'firebase', row: 5, col: 1,},
      { id: 'logger', row: 2, col: 7,},
      { id: 'crm', row: 5, col: 8,},
    ],
};
  Diagram('scheme5', elements5, {layout: 'grid'});
</script>

Тази схема от една страна — това е почти два екрана код на лаптоп, от друга страна структурата а-ля json позволява бързо попълване на всички данни по аналогия и може да се прави copy-paste.

А защо positions са отделени от възлите?

Така е по-удобно. Първо посочваме nodes. След това можем да посочим няколко групи и да ги обозначим в узлите. После определяме връзките. А едва след като имаме основните обекти и връзките между тях, се захващаме с разположението на тези обекти на схемата. Или обратно.

А може ли без positions?

Може и без positions. Но ще е малко накъсано, в примерите може да се види такава версия. Това е обусловено от факта, че за cytoscape съществува алгоритъм за разположение на узлите. fcose, който взема предвид наличието на групи. Посочването на positions прави схемата по-контролируема, но на етапа на първоначалния чертеж на схемата може и без positions.

Също така positions могат да се посочват в стил Морски бой. Т.е. един узел се разполага в a1, а друг в d5. Особено помага, че cytoscape формира обектите на canvas подвижни, т.е. можем да ги преместим, да видим различни варианти на разположение, а след това да фиксираме в кода предпочитаното разположение на елементите.

В общи линии, ясно. Може ли да пробваме?
 
Разбира се, за бързо създаване на схеми си направих малко редактор, което самостоятелно обновява схемата и в браузъра запазва последната версия (в localStorage).

Опитахте ли? Сега може да добавите и на вашата страница.

Тогава още веднъж:

1. Свързваме скрипта

<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>

2. Добавяме в HTML кода

<div id="scheme1" style="height:300px;width:800px;"></div>
<script>      
  const elements = {    
    nodes: [
      { id: 'client', type: 'smartphone', label: 'Mobile App'},
      { id: 'server', type: 'server', label: 'Main Server'},
      { id: 'db1', type: 'database', label: 'DB 1'},
      { id: 'db2', type: 'database', label: 'DB 2'},
    ],
    edges: [
      { source: 'client', target: 'server', label: 'request' },
      { source: 'server', target: 'db1', label: 'request' },
      { source: 'server', target: 'db2', label: 'request' },
    ],
  };
  Diagram('scheme1', elements);
</script>

3. поправяме кода до необходимата ни схема (мисля, че е по-просто от това да нарисувам сова 🙂

Още по-подробно на страницата на проекта на GitHub.

Какво в крайна сметка?

Своите цели постигнах — да направя добавянето на схеми inline в документацията, форматът е достатъчно прост и разбираем. За суперсхеми не подхожда, но за малки схеми, обясняващи структурата на връзките — много е удобно. Винаги може бързо да се поправи и нещо да се промени с течение на времето. Да, и колегите могат сами да поправят нещо в документацията, поне надписите към обектите без особено обучение ))

Какво може да се подобри?

Тук вариантите, разбира се, са много. Да се направи добавяне на допълнителни иконки (всички налични са добавени inline в скрипта). Да се подбере по-изразителен набор от иконки. Да се направи възможност за посочване на стил на връзките. Да се добави фоново изображение.

А какво мислите вие?
 
Имам вече няколко идеи за реализиране в issues, вие също добавете вашите в коментарите.

• Репозитория
• Примери
• Онлайн редактор

Моето решение определено е подходящо за тесен спектър от задачи и може би ще намерите по-удобен инструмент за рисуване на диаграми, просто кодирайки ги — както казват: ‘show me your diagram as code’

1. Добра подбрана колекция
2. Страхотен сервис (9 типа графики онлайн редактор)
3. Конечно, mermaid.js
4. И ако обичате супер детайлни и сложни схеми — то определено ще бъдете впечатлени от този проект: go.drawthe.net

Източник: habr.com