Mrežni dijagram kao kod

Posljednjih nekoliko godina sve više se posvećujem dokumentaciji. Napisati objašnjenje o tome kako radi određeni sustav – općenito, to je prilično lako. Nacrtati dijagram koji prikazuje sve ključne objekte, veze između tih objekata također je prilično jednostavno.

Ali najproblematičniji trenutak je održavanje te dokumentacije u aktualnom stanju. I dobro je kada je tekst u pitanju, ali dijagrami... Budući da 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 raznim programima poput Visio ili online servisima kao što je draw.io. Zatim izvezete dijagram u grafički format i priložite ga HTML-u. Sve jednostavno.

Koji je problem?

Dijagrami su obično jednostavni. Odnosno, nisu previše složeni. Da, broj objekata je desetak, broj veza otprilike toliko. Plus natpisi, neka označavanja. Jednostavne dijagrame možete opisati riječima, a previše složeni, hmm... (c) "neće razumjeti". Ima puno dijagrama, promjene u njima treba povremeno uvesti, tj. stalno, budući da idu uz razvoj naših proizvoda.

Možeš li ugraditi HTML servise? Jesi li probao?

Da, naravno. Meni se, na primjer, sviđaju grafike s gliffy.com. No za promjene treba ići na vanjsku uslugu, tamo se ispraviti. I teže je delegirati kolegi da napravi ispravke.

Što učiniti?

Nedavno mi se na GitHubu našao u preporukama repozitorij github.com/RaoulMeyer/diagram-as-code. Dijagram kao kod. Tj. opisujemo u JS-u potrebni dijagram. Taj JS pišemo direktno u istom HTML-u gdje je i ostali tekst dokumentacije.

Usput, dokumentaciju ne pišem potpuno u HTML-u. Obično dokumentacija uključuje skup datoteka s markdown tekstom, koji se zatim pretvara u punopravnu stranicu dokumentacije pomoću nekog engines, na primjer wintersmith. Ili wiki sustava.

Na kraju ispada jako zgodno: evo, napisali smo tekst, zatim se otvara script tag i u njemu je opisan JS kod dijagrama.

Što opet nije u redu?

Ovaj repozitorij mi se svidio, ali to nije jedini primjer kada se dijagram crta pomoću koda ili tekstualnog prikaza. (Na kraju članka bit će linkova projekata i članaka koje sam pronašao na temu dijagram kao kod.)

I ja nisam jedini koji uređuje dokumentaciju. Ponekad svoje doprinose daju i kolege – ispraviti riječ, promijeniti opis, umetnuti nove slike. 

Stoga bih volio da dijagram vidim u čitljivom i razumljivom tekstualnom formatu, kojem ne bi trebalo dugo učiti. Ponekad bih čak i jednostavno napravio copy-paste kako bih ubrzao dodavanje novog shema. 

Jedan kolega je također primijetio da je kod, naravno, dobar, ali ako se koristi struktura, sve može biti vrlo strogo i izražajno.

Stoga sam pokušao predstaviti shemu kao skup nekoliko malih nizova koji opisuju čvorove, veze, grupe čvorova, kao i raspored čvorova. Meni se, skromno gledajući, čini dovoljno praktično, iako, naravno, o ukusima se ne raspravlja...

Kako to utvrditi dijagram unutar niza?

  • Svaki čvor opisuje se identifikatorom koji nedvojbeno određuje čvor.
  • Također, čvoru se može dodati ikona, dodati natpis.
  • Između dva čvora može se naznačiti veza.
  • Za vezu u shemi može se odrediti boja, natpis.
  • Smjer veze određuje se kao od izvora prema cilju. Izvor i cilj označeni su identifikatorima čvora.
  • Jedan ili više čvorova može se dodati u grupu.
  • Veza se također može naznačiti i od grupe, i prema grupi.

Koristeći ova jednostavna pravila, dobiva se ovakva shema. Jednostavno? Posve.

Mrežni dijagram kao kod

A opisana je sljedećim js-kodom. Glavna stavka ovdje je objekt 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: 'zahtjev' },
      { source: 'server', target: 'db1', label: 'zahtjev' },
      { source: 'server', target: 'db2', label: 'zahtjev' },
    ],
  };
  Diagram('scheme1', elements);

Naravno, crtanje sheme nisam smislio sam, već sam iskoristio biblioteku cytoscape.js — vrlo moćan alat za vizualizaciju. Dio mogućnosti koje u svom rješenju samo djelomično koristim. 

Razumljivo, ovo je jednostavan primjer. Može li biti malo složenije?

Da, naravno. Za navođenje pozicija — koristimo positions, za navođenje grupa — navodimo popis grupa u groups, a za same elemente atribut group.

Mrežni dijagram 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>

Takva shema s jedne strane — to je skoro dva ekrana koda na laptopu, s druge strane struktura nalik jsonu omogućuje brzu popunu svih podataka po analogiji, lako i može se copy-paste.

A zašto su positions izdvojene od čvorova?

Tako je lakše. Prvo navodimo čvorove. Zatim možemo navesti nekoliko grupa i uključiti ih u čvorove. Potom označavamo veze. Tek kada su osnovni objekti i veze među njima definisani, posvetimo se rasporedu tih objekata na dijagramu. Ili obrnuto.

Da li može bez pozicija?

Može i bez pozicija. No, izgledat će malo zbrkano; u primjerima se može vidjeti takva opcija. To je zbog toga što za cytoscape postoji algoritam za raspored čvorova. fcose, koji također uzima u obzir prisutnost grupa. Određivanje pozicija čini dijagram kontroliranijim, ali u fazi prvog nacrta dijagrama može se i bez pozicija.

Također se pozicije mogu odrediti u stilu Morskog boja. T.j. jedan čvor se nalazi u a1, a drugi u d5. Posebno pomaže što cytoscape formira objekte na platnu kao pokretne, t.j. možemo ih pomerati, isprobati različite rasporede, a zatim zabeležiti u kodu omiljeni raspored elemenata.

U principu, jasno. Mogu li probati?
 
Naravno, za brzo kreiranje dijagrama napravio sam sebi mali uređivač, koji samostalno ažurira dijagram 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. Uključujemo 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. uredimo kod do željenog dijagrama (mislim da je to lakše nego nacrtati sovu 🙂

Još detaljnije na stranici projekta github-u.

Što na kraju?

Svojih ciljeva sam postigao — omogućiti dodavanje dijagrama inline u dokumentaciju, format je dovoljno jednostavan i razumljiv. Ne odgovara za super dijagrame, ali za male dijagrame koji objašnjavaju strukturu veza — vrlo je dobar. Uvijek možete brzo ispraviti i nešto promijeniti tokom vremena. Da, a kolege mogu u dokumentu same malo nešto ispraviti, barem natpise na objektima bez posebnog obučavanja. ))

Što se može poboljšati?

Opcija je, naravno, mnogo. Napraviti dodavanje dodatnih ikona (sve postojeće su dodane inline u skriptu). Izabrati izražajniji set ikona. Napraviti mogućnost određivanja stila linije veza. Dodati pozadinsku sliku.

Što vi mislite?
 
Već imam nekoliko ideja za realizaciju u issues, vi također dodajte svoje u komentare.

Moje rješenje doista se može primijeniti u uskom spektru zadataka, a možda ćete pronaći pogodniji alat za crtanje dijagrama jednostavno kodirajući ih — kao što kažu ‘okažite mi svoj dijagram kao kod’

  1. Dobar izbor
  2. Sjajna usluga (9 vrsta grafova online urednika)
  3. Конечно, mermaid.js
  4. I ako volite super detaljne i kompleksne sheme — ovaj projekt će vas sigurno oduševiti: go.drawthe.net

Izvor: habr.com

Kupite pouzdan hosting za web stranice s DDoS zaštitom, VPS VDS servere 🔥 Kupite pouzdan hosting za web stranice s DDoS zaštitom, VPS VDS servere | ProHoster