Схема на мрежата като код

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

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

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

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

Възможно е да вграждате HTML на услугата. Пробвахте ли?

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

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

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

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

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

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

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

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

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

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

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

Как е диаграмата в масива?

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

Като следвате тези прости правила, получавате следната схема. Лесно, нали? Напълно.

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

  const elements = {
    nodes: [       // описваме възли
      { id: 'client', type: 'smartphone', label: 'Мобилно приложение'},
      { id: 'server', type: 'server', label: 'Основен сървър'},
      { id: 'db1', type: 'database', label: 'База данни 1'},
      { id: 'db2', type: 'database', label: 'База данни 2'},
    ],
    edges: [       // указваме връзки
      { source: 'client', target: 'server', label: 'заявка' },
      { source: 'server', target: 'db1', label: 'заявка' },
      { source: 'server', target: 'db2', label: 'заявка' },
    ],
  };
  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.

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

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

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

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

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

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

Моето решение определено е приложимо в тесен спектър от задачи, и може би ще намерите по-удобен инструмент за рисуване на диаграми, просто като ги кодиране — както се казва „покажете ми диagrama си като код“

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

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