Dijagram mreže kao kod

U posljednjih nekoliko godina više se bavim dokumentacijom. Pisanje objašnjavajućeg teksta o tome kako funkcioniše neka ili druga sistema - u suštini, to je dovoljno jednostavno. Nacrtati dijagram koji prikazuje sve ključne objekte i veze između tih objekata također je prilično lako.

Ali najproblematičnija tačka je održavanje ove dokumentacije u ažuriranom stanju. Da je bar tekst u pitanju, ali dijagrami... Pošto je sva dokumentacija online, tj. u HTML formatu, uz tekst su priložene slike gif/jpg/png, na kojima su zapravo prikazani dijagrami. A dijagrami se crtaju u različitim programima poput Visio-a ili online servisima poput draw.io. Zatim se dijagram izvozi u grafički format i prilaže HTML-u. Sve je jednostavno.

U čemu je problem?

Dijagrami su obično jednostavni. Tačnije, nisu previše složeni. Da, broj objekata je desetak-dva, broj veza otprilike toliko. Plus natpisi, neka obeležavanja. Jednostavne dijagrame se može opisati i rečima, a previše složene, hm... (c) 'neće biti razumljivo'. Ima mnogo dijagrama, potrebno je povremeno-menjati ih, tj. stalno, jer idu u korak s razvojem naših proizvoda.

Možeš li ugraditi HTML servisa? Jesi li probavao?

Da, naravno. Meni, na primjer, se sviđaju grafike na gliffy.com. Ali za promjene trebaš otići u spoljni servis, tamo ispraviti. A teže je delegirati kolegi da napravi izmjene.

Šta uraditi?

Nedavno sam na githubu naišao u preporukama na repozitorij github.com/RaoulMeyer/diagram-as-code. Dijagram kao kod. Tj. opisujemo na js potrebni dijagram. Ovaj js pišemo direktno u istom HTML-u gdje je i ostali tekst dokumentacije.

Usput rečeno, ne pišem dokumentaciju potpuno u HTML-u. Obično je dokumentacija skup fajlova sa markdown tekstom, koji se kasnije konvertuje u potpuni web sajt dokumentacije nekim motorom, na primjer wintersmith. Ili wiki sistem.

Ispada vrlo praktično: napisali smo tekst, zatim se otvara script tag i u njemu je opisan js kod dijagrama.

Šta opet nije u redu?

Ovaj repozitorij mi se dopao, ali to nije jedini primjer kada dijagram crtaju pomoću koda ili tekstualnog prikaza. (Na kraju članka će biti linkova na projekte i članke koje sam pronašao na temu dijagram kao kod.)

I nisam jedini koji se bavi dokumentacijom. Ponekad se i kolege uključe — isprave neku reč, promene opis, dodaju nove slike. 

Zato bih voleo da dijagram vidim u čitljivom i razumljivom tekstualnom formatu, koji ne bi zahtevao dugo učenje. A ponekad čak jednostavno kopija-lepljenje da ubrza dodavanje nove šeme. 

A jedan kolega je primetio da je kod, naravno, dobar, ali ako se koristi struktura, sve može biti vrlo strogo i ekspresivno.

Zato sam pokušao da predstavim šemu kao skup nekoliko malih nizova koji opisuju čvorove, veze, grupe čvorova, kao i raspored čvorova. Izgleda dovoljno zgodno, iako, naravno, o ukusima se ne raspravlja…

Kako je to dijagram u nizu?

  • Svaki čvor se opisuje identifikatorom koji jednoznačno definiše čvor.
  • Takođe, čvoru se može dodati ikona, dodati natpis.
  • Između dva čvora može se označiti veza.
  • Za vezu na šemi može se odrediti boja, natpis.
  • Smer veze se određuje od izvora do cilja. A izvor i cilj se označavaju identifikatorima čvora.
  • Jedan ili više čvorova može se dodati grupi.
  • Veza se takođe može odrediti i od grupe i prema grupi.

Koristeći ova jednostavna pravila, dobijamo ovakvu šemu. Lako? Potpuno.

Dijagram mreže kao kod

Ona se opisuje sledećim js kodom. Osnovno ovde — to je objekat elements. U kojem su navedeni nodes — čvorovi, edges — veze.
 

  const elements = {
    nodes: [       // opisujemo čvorove
      { id: 'client', type: 'smartphone', label: 'Mobilna aplikacija'},
      { id: 'server', type: 'server', label: 'Glavni server'},
      { id: 'db1', type: 'database', label: 'DB 1'},
      { id: 'db2', type: 'database', label: 'DB 2'},
    ],
    edges: [       // navodimo veze
      { source: 'client', target: 'server', label: 'zahtev' },
      { source: 'server', target: 'db1', label: 'zahtev' },
      { source: 'server', target: 'db2', label: 'zahtev' },
    ],
  };
  Diagram('scheme1', elements);

Naravno, crtanje šeme nisam smislio sam, već sam se poslužio bibliotekom cytoscape.js — vrlo moćnim alatom za vizualizaciju. Od njenog spektra mogućnosti u svom rešenju koristim samo delić. 

Jasno, ovo je jednostavan primer. Može li biti složenije?

Da, naravno. Za označavanje pozicija — koristimo positions, za označavanje grupa — navodimo listu grupa u groups, a sami elementi imaju atribut group.

Dijagram mreže kao kod

A ovo je kod:

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

Ova shema s jedne strane — to su skoro dva ekrana koda na laptopu, a s druge strane struktura slična json-u omogućava brzo popunjavanje svih podataka po analogiji, uz mogućnost copy-paste.

Zašto su pozicije odvojene od čvorova?

Tako je lakše. Prvo navodimo čvorove. Zatim možemo navesti nekoliko grupa i uključiti ih u čvorove. Nakon toga označavamo veze. A tek kada imamo osnovne objekte i veze između njih, uzimamo se za raspored tih objekata na shemi. Ili obrnuto.

Može li i bez pozicija?

Može i bez pozicija. Ali će to biti malo zbunjujuće; u primerima možete videti takvu varijantu. To je zbog toga što za cytoscape postoji algoritam za raspoređivanje čvorova. fcose, koji takođe uzima u obzir prisustvo grupa. Navođenje pozicija čini shemu kontrolisanijom, ali u fazi prvog nacrta sheme može se i bez pozicija.

Takođe, pozicije se mogu navoditi u stilu Morskog boja. Tj. jedan čvor se nalazi u a1, a drugi u d5. Posebno pomaže što cytoscape formira objekte na platnu pokretnima, tj. možemo ih pomerati, razmatrati različite rasporede, a zatim fiksirati u kodu omiljeni raspored elemenata.

U celini, jasno je. Možemo li probati?
 
Naravno, za brzo kreiranje shema napravio sam sebi mali editor, koji samostalno ažurira shemu i u pretraživaču čuva poslednju verziju (u localStorage).

Jeste li probali? Sada možete dodati i na svoju stranicu.

Dakle, još jednom:

1. Povezujemo skriptu

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

2. Dodajemo u html kod

<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. prilagodimo kod do potrebne nam sheme (mislim da je ovo lakše nego naslikati sovu 🙂

Još tačnije na stranici projekta na github-u.

Šta na kraju?

Svojih ciljeva sam postigao — napraviti dodavanje shema inline u dokumentaciju, format je dovoljno jednostavan i razumljiv. Za super sheme nije pogodan, ali za male sheme koje objašnjavaju strukturu veza — itekako je dobar. Uvek se može brzo ispraviti i nešto menjati s vremenom. Da, i kolege mogu same nešto ispraviti u dokumentu, bar natpise na objektima bez posebnog obučavanja ))

Šta se može poboljšati?

Ovde, naravno, postoji mnoštvo opcija. Napraviti dodavanje dodatnih ikona (svi postojeći su dodani inline u skriptu). Odabrati izražajniji set ikona. Napraviti mogućnost navođenja stila linije veza. Dodati pozadinsku sliku.

A šta vi mislite?
 
Već imam nekoliko ideja za implementaciju u issues, slobodno dodajte svoje u komentare.

Moje rešenje je definitivno primenljivo na uskom spektru zadataka, a možda ćete pronaći pogodniji alat za crtanje dijagrama jednostavno ih kodirajući — kao što kažu ‘pokaži mi svoj dijagram kao kod’

  1. Dobar sastav
  2. Sjajna usluga (9 tipova grafikon online uređivač)
  3. Конечно, mermaid.js
  4. I ako volite super detaljne i složene dijagrame — onda će vas ovaj projekat definitivno oduševiti: go.drawthe.net

Izvor: habr.com

Kupite pouzdan hosting za sajtove uz zaštitu od DDoS, VPS VDS servere 🔥 Kupite pouzdan hosting za sajtove uz zaštitu od DDoS, VPS VDS servere | ProHoster