Sieťová schéma ako kód

V posledných pár rokoch som sa viac začal venovať dokumentácii. Napísať vysvetľujúci text o tom, ako funguje taký alebo onaký systém — to je vo všeobecnosti celkom jednoduché. Nakresliť schému, na ktorej budú zobrazené všetky kľúčové objekty a väzby medzi nimi, je tiež celkom ľahké.

Ale najproblémovejší moment — to je udržiavať túto dokumentáciu v aktuálnom stave. A keby to bol len text, ale schémy… Keďže celá dokumentácia je online, teda vo formáte html, k textu sú pripojené obrázky gif/jpeg/png, na ktorých sú vlastne zobrazené schémy. A schémy sa kreslia v rôznych programoch ako Visio alebo online službách ako draw.io. Potom exportuješ schému do grafického formátu a pripojíš k html. Všetko jednoduché.

Aký je problém?

Schémy sú zvyčajne jednoduché. Presnejšie, nie veľmi zložité. Áno, počet objektov je desať-dva, počet väzieb zhruba toľko. Plus popisky, nejaké označenia. Jednoduché schémy sa dajú opísať aj slovami, ale príliš zložité, ehm… (c) „nepochopia-s“. Schém je veľa, zmeny v nich treba zavádzať pravidelne-epizodicky, teda stále, pretože môžu byť v súlade s vývojom našich produktov.

Veď sa dajú vložiť html služby. Skúšal si?

Áno, samozrejme. Mne sa napríklad páčia grafiky na gliffy.com. Ale pre zmeny je potrebné ísť do externého servisu a tam upravovať. A je ťažšie delegovať, aby opravy vykonal kolega.

Čo robiť?

Nedávno mi na github-e padol do oka v odporúčaniach repozitár github.com/RaoulMeyer/diagram-as-code. Diagram ako kód. Teda, popíšte na js potrebnú nám schému. Tento js píšeme priamo v tom istom html, kde je aj ostatný text dokumentácie.

Mimochodom, ja nepíšem dokumentáciu úplne v html. Zvyčajne je dokumentácia súborom s markdown textom, ktorý sa potom konvertuje na plnohodnotný web dokumentácie nejakým motorom, napríklad wintersmith. Alebo wiki systém.

Vychádza to veľmi pohodlne: napíšeme text, potom otvoríme tag script a v ňom je opísaný js kód schémy.

Čo zase nie je v poriadku?

Tento repozitár sa mi páčil, ale to nie je jediný príklad, keď sa diagram kreslí pomocou kódu alebo textového vyjadrenia. (Na konci článku budú odkazy na projekty a články, ktoré som našiel na tému diagram ako kód.)

A predsa nie som sám, kto upravuje dokumentáciu. Niekedy prispievajú aj kolegovia - slovo opraviť, popis zmeniť, nové obrázky vložiť. 

Preto by som chcel vidieť diagram v čitateľnom a zrozumiteľnom textovom formáte, ktorému by netrebalo dlho rozumieť. A miestami by sa dalo aj jednoducho akoby skopírovať na urýchlenie pridávania nových schém. 

A ďalší kolega si všimol, že kód je určite dobrý, ale ak použijeme štruktúru, všetko môže byť veľmi striktne a expresívne.

Preto som sa pokúsil predstaviť schému ako súbor niekoľkých malých polí, ktoré popisujú uzly, väzby, skupiny uzlov a tiež umiestnenie uzlov. Podľa môjho skromného názoru to vyšlo celkom pohodlne, hoci, samozrejme, na chuť a farbu…

Ako je to schéma v poli?

  • Každý uzol je popísaný identifikátorom, ktorý jednoznačne určuje uzol.
  • K uzlu je tiež možné pridať ikonu a dodatočný text.
  • Medzi dvoma uzlami je možné uviesť väzbu.
  • Pre väzbu na schéme možno určiť farbu a text.
  • Smer väzby je určený od zdroja k cieli. A zdroj a cieľ sú uvedené identifikátormi uzla.
  • Jeden alebo viac uzlov môže byť pridaných do skupiny.
  • Väzbu je možné určiť aj zo skupiny a k skupine.

Používajúc tieto jednoduché pravidlá vznikne takáto schéma. Jednoduché? Celkom.

Sieťová schéma ako kód

A opisuje sa nasledujúcim js-kódom. Hlavný element je tu objekt elements. V ktorom sú uvedené nodes – uzly, edges – väzby.
 

  const elements = {
    nodes: [       // opisujeme uzly
      { id: 'client', type: 'smartphone', label: 'Mobilná aplikácia'},
      { id: 'server', type: 'server', label: 'Hlavný server'},
      { id: 'db1', type: 'database', label: 'DB 1'},
      { id: 'db2', type: 'database', label: 'DB 2'},
    ],
    edges: [       // uvádzame väzby
      { source: 'client', target: 'server', label: 'žiadosť' },
      { source: 'server', target: 'db1', label: 'žiadosť' },
      { source: 'server', target: 'db2', label: 'žiadosť' },
    ],
  };
  Diagram('scheme1', elements);

Samozrejme, kreslenie schémy som nevymyslel sám, ale využil som knižnicu cytoscape.js — veľmi mocný nástroj na vizualizáciu. Z niektorých jej možností v svojom riešení využívam len časť. 

Je jasné, že toto je jednoduchý príklad. Môže byť ťažší?

Áno, prosím. Na určenie pozícií používame positions, na určenie skupín uvádzame zoznam skupín v groups a pre samotné prvky atribút group.

Sieťová schéma ako kód

A toto je kód:

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

Takáto schéma je z jednej strany takmer dva obrazovky kódu na notebooku, z druhej strany štruktúra a la json umožňuje rýchlo vyplniť všetky údaje na podobnom princípe a dá sa to kopírovať a vkladať.

A prečo sú positions uvedené oddelene od uzlov?

Takto je to pohodlnejšie. Najprv uvedieme uzly. Potom môžeme uviesť pár skupín a zahrnúť ich do uzlov. Následne určíme väzby. A až potom, keď sú hlavné objekty a väzby medzi nimi definované, začneme s umiestnením týchto objektov na schéme. Alebo naopak.

A dá sa aj bez pozícií?

Dá sa aj bez pozícií. Ale bude to trochu neprehľadné, v príkladoch si môžete pozrieť takúto variantu. Je to spôsobené tým, že pre cytoscape existuje algoritmus na umiestňovanie uzlov. fcose, ktorý tiež zohľadňuje prítomnosť skupín. Určenie pozícií robí schému viac kontrolovateľnou, ale v štádiu prvého náčrtu schémy sa dá aj bez pozícií.

Pozície sa dajú tiež určovať v štýle lodného boja. T.j. jeden uzol je umiestnený v a1, a druhý v d5. Obzvlášť pomáha, že cytoscape vytvára objekty na plátne pohyblivými, t.j. môžeme ich posúvať, pozrieť si rôzne varianty umiestnenia, a potom zafixovať v kóde preferované umiestnenie prvkov.

Celkom jasné. Môžeme to skúsiť?
 
Samozrejme, na rýchle vytvorenie schém som si urobil malý editor, ktorý sám aktualizuje schému a v prehliadači uchováva poslednú verziu (v localStorage).

Skúsili ste? Teraz to môžete pridať aj na svoju stránku.

Takže ešte raz:

1. Pripojíme skript

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

2. Pridáme do html kódu

<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. upravený kód do požadovanej schémy (myslím, že je to jednoduchšie ako nakresliť sovu 🙂

Podrobnejšie na stránke projektu na gite.

Aký je výsledok?

Dosiahol som svoje ciele — spraviť pridanie schém inline do dokumentácie, formát je dostatočne jednoduchý a prehľadný. Pre super schémy to nie je vhodné, ale pre malé schémy, ktoré objasňujú štruktúru väzieb — to je veľmi dobré. Vždy sa dá rýchlo upraviť a niečo v priebehu času zmeniť. A kolegovia môžu v dokumente sami niečo upraviť, minimálne popisy objektov bez zvláštneho školenia ))

Čo by sa dalo zlepšiť?

Variácie sú samozrejme nekonečné. Pridať ďalšie ikony (všetky existujúce sú pridané inline do skriptu). Vybrať výstižnejší súbor ikon. Umožniť nastavenie štýlu čiar väzieb. Pridať pozadí.

A čo si myslíte vy?
 
Mám už niekoľko nápadov na realizáciu v issues, pridajte aj svoje do komentárov.

Moje riešenie je určite použiteľné v úzkom spektre úloh, a možno nájdete pohodlnejší nástroj na kreslenie diagramov, jednoducho ich zakódovaním — ako sa hovorí: ‘ukážte mi svoj diagram ako kód’

  1. Dobrý výber
  2. Skvelá služba (9 typov grafov online editora)
  3. Конечно, mermaid.js
  4. A ak sú vám blízke super podrobné a zložité schémy — tento projekt vás určite oslní: go.drawthe.net

Zdroj: habr.com

Kúpte si spoľahlivý hosting pre webové stránky s ochranou proti DDoS, VPS VDS servery 🔥 Kúpte si spoľahlivý hosting pre webové stránky s ochranou proti DDoS, VPS VDS servery | ProHoster