Мрежова диаграма като код / ​​Мрежова диаграма като код

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

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

Какъв е проблемът?

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

Можете да вградите html на услугата. Опитвали ли сте го?

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

Какво да правя?

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

Между другото, аз пиша документация не изцяло в html. Обикновено документацията е набор от файлове с текст за маркиране, който след това се преобразува в пълноценен документационен сайт от някакъв двигател, например Wintersmith. Или уики система.

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

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

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

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

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

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

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

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

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

Използвайки тези прости правила, получаваме следната диаграма. Просто? Съвсем.

И се описва със следния js код. Основното тук е обектът на елементите. В кои възли са посочени - възли, ръбове - връзки.
 

  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 е много мощен инструмент за визуализация. Използвам само малка част от възможностите в моето решение. 

Добре, това е прост пример. Може ли да е по-сложно?

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

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

<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>

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

Защо позициите се поставят отделно от възлите?

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

Може ли без позиции?

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

Позициите също могат да бъдат определени в стила на Battleship. Тези. единият възел се намира в a1, а другият в d5. Особено помага, че cytoscape прави обектите върху платното подвижни, т.е. можем да ги местим, да виждаме различни опции за оформление и след това да коригираме подредбата на елементите, които харесваме в кода.

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

Опитвали ли сте го? Вече можете да го добавите към страницата си.

След това отново:

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

<script src="https://unpkg.com/@antirek/[email protected]/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.

Какъв е резултатът?

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

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

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

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

• хранилище
• Примеры
• Онлайн редактор

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

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

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