Мрежни дијаграм као код / ​​Мрежни дијаграм као код

Последњих пар година више сам се бавио документацијом. Писање текста са објашњењем о томе како одређени систем функционише је генерално прилично једноставно. Цртање дијаграма који ће приказати све кључне објекте и везе између ових објеката је такође прилично лако.

Али најпроблематичнији аспект је одржавање ове документације ажурном. И текст би био у реду, али дијаграми... Јер... сва документација је онлајн, тј. у хтмл формату, онда је уз текст гиф/јпег/пнг слике, које заправо приказују дијаграме. А дијаграми се цртају у разним програмима као што су Висио или онлајн сервиси а ла драв.ио. Затим извозите дијаграм у графички формат и приложите га хтмл-у. То је једноставно.

Шта је проблем?

Шеме су обично једноставне. Тачније, не много компликовано. Да, број објеката је десетак или два, број веза је приближно исти. Плус потписи, неке ознаке. Једноставне шеме се могу описати речима, али оне превише сложене, хем... (ц) „неће разумети, господине.“ Постоји много шема, потребно их је периодично, епизодично, мењати, тј. стално, јер прате развој наших производа.

Можете да уградите хтмл услуге. Јесте ли пробали?

Да сигуран. На пример, свиђа ми се графика са глиффи.цом. Али да бисте извршили измене, потребно је да одете на услугу треће стране и тамо уредите. И теже је делегирати исправке колеги.

Шта да радим?

Недавно сам наишао на спремиште на Гитхуб-у у препорукама гитхуб.цом/РаоулМеиер/диаграм-ас-цоде. Дијаграм као код. Оне. описујемо коло које нам је потребно у јс. Овај јс пишемо директно у истом хтмл-у где је и други текст документације.

Иначе, пишем документацију не у потпуности у хтмл-у. Типично, документација је скуп датотека са текстом за означавање, који се затим конвертује у потпуну локацију за документацију од стране неког механизма, на пример винтерсмитх-а. Или вики систем.

Испада веома згодно: написали смо текст, затим се отвара ознака скрипте и у њој је описан ЈС код шеме.

Шта опет није у реду?

Свидело ми се ово спремиште, али ово није једини пример где је дијаграм нацртан коришћењем кода или текстуалног приказа. (На крају чланка ће бити везе до пројеката и чланака које сам пронашао на Гоогле дијаграму теме као код.)

И нисам једини који уређује документацију. Понекад доприносе и колеге – исправи реч, промени опис, убаци нове слике. 

Стога бих желео да видим дијаграм у читљивом, разумљивом текстуалном формату који не би захтевао дугу криву учења. А на неким местима чак можете једноставно копирати и залепити да бисте убрзали додавање новог кола. 

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

Због тога сам покушао да замислим дијаграм као скуп неколико малих низова који описују чворове, везе, групе чворова, као и локацију чворова. Испоставило се, по мом скромном мишљењу, прилично згодно, иако, наравно, укус и боја...

Како је ово графикон у низу?

• Сваки чвор је описан идентификатором који јединствено идентификује чвор.
• Такође можете додати икону у чвор и додати натпис.
• Можете одредити однос између два чвора.
• За комуникацију на дијаграму можете поставити боју и натпис.
• Правац комуникације је дефинисан као од извора до циља. А извор и циљ су назначени идентификаторима чворова.
• У групу се може додати један или више чворова.
• Однос се такође може специфицирати и из групе и за групу.

Користећи ова једноставна правила, добијамо следећи дијаграм. Само? Прилично.

И то је описано следећим јс кодом. Овде је главна ствар објект елемената. У којима су назначени чворови - чворови, ивице - везе.
 

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

Наравно, нисам сам смислио цртеж кола, већ сам користио библиотеку цитосцапе.јс је веома моћан алат за визуелизацију. Користим само делић могућности у свом решењу. 

У реду, ово је једноставан пример. Може ли бити компликованије?

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

А ово је код:

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

С једне стране, таква шема је скоро неколико екрана кода на лаптопу, са друге стране, структура а ла јсон вам омогућава да попуните све податке по аналогији, брзо и можете копирати-пасте.

Зашто се позиције постављају одвојено од чворова?

Удобније је. Прво наведемо чворове. Затим можемо одредити неколико група и означити их у чворовима. Затим означавамо везе. И тек онда, када су главни објекти и везе између њих тамо, преузимамо локацију ових објеката на дијаграму. Или обрнуто.

Да ли је могуће без позиција?

Могуће је и без позиција. Али то ће бити мало згужвано, можете видети ову опцију у примерима. Ово је због чињенице да постоји алгоритам за локацију чворова за цитосцапе фцосе, који такође узима у обзир присуство група. Одређивање позиција чини дијаграм лакшим за контролу, али у фази првог нацрта дијаграма могуће је без позиција.

Позиције се такође могу специфицирати у стилу бојног брода. Оне. један чвор се налази у а1, а други у д5. Посебно помаже то што цитосцапе чини објекте на платну покретним, тј. можемо их померати, видети различите опције распореда, а затим поправити распоред елемената који нам се допадају у коду.

Генерално, то је разумљиво. Можете ли покушати?
 
Наравно, да бих брзо направио кола, направио сам себи мали уредник, који сам ажурира шему и чува најновију верзију у претраживачу (у лоцалСтораге).

Јесте ли пробали? Сада га можете додати на своју страницу.

Онда поново:

1. Повезивање скрипте

<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>

2. Додајте код у хтмл

<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. уређујемо код у дијаграм који нам је потребан (мислим да је лакше него цртати сову :)

Више детаља на страница пројекта на гитхуб-у.

Резултат?

Постигао сам своје циљеве - да додам инлине дијаграме у документацију, формат је прилично једноставан и разумљив. Није погодан за супер кола, али за мала кола која објашњавају структуру веза, сасвим је у реду. Увек можете брзо нешто да подесите и промените током времена. Да, и колеге могу сами да исправе нешто на доку, барем натписе за објекте, без посебне обуке))

Шта се може побољшати?

Овде, наравно, постоји много опција. Додајте додатне иконе (све постојеће се додају у скрипту). Изаберите изражајнији скуп икона. Омогућите одређивање стила линије везе. Додајте слику за позадину.

Шта мислиш?
 
Већ имам неколико идеја за имплементацију у издањима, можете додати и своје у коментарима.

• репозиторијум
• Примери
• Онлине едитор

Моје решење је дефинитивно применљиво у уском опсегу проблема, и можда ћете наћи погоднији алат за цртање дијаграма једноставним кодирањем - како кажу 'покажите ми свој дијаграм као код'

1. добар избор
2. Одлична услуга (9 типова онлајн уређивача графикона)
3. Наравно, мермаид.јс
4. А ако волите супер детаљне и сложене дијаграме, онда ћете се сигурно дивити овом пројекту: го.дравтхе.нет

Извор: ввв.хабр.цом