ProHoster > Blog > Amministrazione > Schema di rete cum'è codice / Diagramma di rete cum'è codice

Schema di rete cum'è codice / Diagramma di rete cum'è codice

In l'ultimi dui anni sò diventatu più implicatu in a documentazione. Scrivite un testu esplicativu nantu à cumu funziona un sistema particulari hè generalmente abbastanza simplice. Disegnu un diagramma chì mostrarà tutti l'uggetti chjave è e cunnessione trà questi ogetti hè ancu abbastanza faciule.

Ma l'aspettu più problematicu hè di mantene sta documentazione aghjurnata. È u testu saria bè, ma i diagrammi... Perchè... tutta a documentazione hè in linea, i.e. in u formatu html, allura u testu hè accumpagnatu da immagini gif/jpeg/png, chì in realtà mostranu i diagrammi. E diagrammi sò disegnati in diversi prugrammi cum'è Visio o servizii in linea à a draw.io. Allora exportate u diagramma in formatu graficu è aghjunghje à html. Hè simplice.

Chì ghjè u prublema?

I schemi sò generalmente simplici. Più precisamente, micca assai cumplicatu. Iè, u numeru di l'uggetti hè una decina o duie, u numeru di cunnessione hè apprussimatamente u listessu. In più firme, alcune designazioni. I schemi simplici ponu esse discritti in parolle, ma troppu cumplessi, ehm... (c) "ùn capiscenu micca, signore". Ci hè parechje schemi, i cambiamenti devenu esse fatti per elli periòdicamenti, episodiu, i.e. constantemente, perchè seguitanu u sviluppu di i nostri prudutti.

Pudete incrustà l'html di u serviziu. Avete pruvatu ?

Iè, sicuru. Per esempiu, mi piace u graficu di gliffy.com. Ma per fà cambiamenti, avete bisognu à andà in un serviziu di terzu è edità quì. È hè più difficiuli di delegate correzioni à un cullega.

Chì deve fà?

Recentemente aghju trovu un repository in Github in i cunsiglii github.com/RaoulMeyer/diagram-as-code. Diagramu cum'è codice. Quelli. descrivimu u circuitu chì avemu bisognu in js. Scrivemu stu js direttamente in u stessu html induve l'altru testu di documentazione hè.

Per via, scrivu a documentazione micca solu in html. Di genere, a documentazione hè un inseme di schedari cù u testu di marcatu, chì hè poi cunvertitu in un situ di documentazione cumpletu da qualchì mutore, per esempiu wintersmith. O un sistema wiki.

Ci hè assai cunvene: avemu scrittu u testu, dopu l'etichetta di script si apre è u codice JS di u schema hè descrittu in questu.

Chì ci hè di novu?

Mi piacia stu repository, ma questu ùn hè micca l'unicu esempiu induve un diagramma hè disegnatu cù u codice o una rappresentazione di testu. (À a fine di l'articulu ci saranu ligami per prughjetti è articuli chì aghju Googled nantu à u diagramma di tema cum'è codice.)

È ùn sò micca l'unicu chì edita a documentazione. Calchì volta i culleghi cuntribuiscenu ancu - corregge una parolla, cambia una descrizzione, inserisce novi ritratti. 

Dunque, mi piacerebbe vede u diagramma in un formatu di testu leggibile è comprensibile chì ùn deve micca bisognu di una longa curva d'apprendimentu. È in certi lochi pudete ancu simplice copia-incolla per accelerà l'aghjunghje un novu circuitu. 

È un altru cullegu hà nutatu chì u codice hè, sicuru, bonu, ma se utilizate struttura, tuttu pò esse assai strettu è espressivu.

Per quessa, aghju pruvatu à imaginà u diagramma cum'è un inseme di parechji picculi arrays chì descrizanu nodi, cunnessione, gruppi di nodi, è ancu u locu di nodi. Risultò, in u mo umile parè, abbastanza cunvene, ancu s'ellu, sicuru, u gustu è u culore ...

Cumu hè questu un graficu in un array?

  • Ogni node hè descrittu da un identificatore chì identifica unicu u node.
  • Pudete ancu aghjunghje un icona à u node è aghjunghje una inscription.
  • Pudete specificà una relazione trà dui nodi.
  • Per a cumunicazione nantu à u schema, pudete stabilisce u culore è l'inscription.
  • A direzzione di cumunicazione hè definita da a fonte à u destinazione. È a fonte è a destinazione sò indicati da identificatori di node.
  • Unu o più nodi ponu esse aghjuntu à un gruppu.
  • A relazione pò ancu esse specificatu da u gruppu è à u gruppu.

Utilizendu sti regule simplici, avemu u schema seguente. Solu? Piuttostu.

Schema di rete cum'è codice / Diagramma di rete cum'è codice

È hè discrittu da u codice js seguenti. A cosa principal quì hè l'uggettu di l'elementi. In quale nodi sò indicati - nodes, bordi - cunnessione.
 

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

Di sicuru, ùn aghju micca vinutu cù u disegnu di u circuitu stessu, ma aghju utilizatu a biblioteca cytoscape.js hè un strumentu di visualizazione assai putente. Aduprà solu una frazzioni di e pussibulità in a mo suluzione. 

Va bè, questu hè un esempiu simplice. Pò esse più cumplicatu?

Iè per piacè. Per indicà pusizioni, usemu pusizioni, per indicà gruppi, indicà una lista di gruppi in gruppi, è l'elementi stessi anu un attributu di gruppu.

Schema di rete cum'è codice / Diagramma di rete cum'è codice

È questu hè u codice:

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

Da una banda, un tali schema hè quasi un coppiu di schermi di codice in un laptop, da l'altra banda, a struttura a la json permette di riempie tutte e dati per analogia, rapidamente è pudete copià-incollà.

Perchè i pusizioni sò posti separatamente da i nodi?

Hè più còmode. Prima avemu specificà i nodi. Allora pudemu specificà un paru di gruppi è indicà in i nodi. Dopu avemu designatu e cunnessione. È solu allora, quandu l'uggetti principali è e ligami trà elli sò quì, pigliamu u locu di questi ogetti nantu à u schema. O viceversa.

Hè pussibule senza pusizioni?

Hè pussibule senza pusizioni. Ma serà un pocu sgrossatu; pudete vede sta opzione in l'esempii. Questu hè duvuta à u fattu chì ci hè un algoritmu per u locu di nodi per cytoscape fcose, chì piglia ancu in contu a prisenza di gruppi. A specificazione di pusizioni rende u diagramma più cuntrullable, ma in u stadiu di u primu abbozzu di u schema hè pussibule senza pusizioni.

E pusizioni ponu ancu esse specificate in u stilu Battleship. Quelli. un node hè situatu in a1, è l'altru in d5. Hè sopratuttu aiuta chì u cytoscape rende l'uggetti nantu à a tela mobile, i.e. pudemu spustà, vede diverse opzioni di layout, è poi riparà l'arrangiamentu di l'elementi chì ci piace in u codice.

In generale, hè comprensibile. Pudete ancu pruvà?
 
Di sicuru, per creà rapidamente circuiti, aghju fattu un picculu u editore, chì stessu aghjurnà u schema è guarda l'ultima versione in u navigatore (in localStorage).

Avete pruvatu ? Pudete avà aghjunghje à a vostra pagina.

Allora dinò:

1. Cunnettendu u script

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

2. Aghjunghjite u codice à 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. Editemu u codice à u diagramma chì avemu bisognu (Pensu chì hè più faciule ch'è di disegnu un gufo :)

Più dettagli à pagina di prughjettu nantu à github.

Ciò à a fine?

Aghju ottinutu i mo scopi - per aghjunghje diagrammi in linea à a documentazione, u furmatu hè abbastanza simplice è comprensibile. Ùn hè micca adattatu per i circuiti super, ma per i circuiti chjuchi chì spieganu a struttura di cunnessione, hè assolutamente bè. Pudete sempre aghjustà rapidamente è cambià qualcosa cù u tempu. Iè, è i culleghi ponu correggere qualcosa in u dock elli stessi, almenu didascalia per l'uggetti, senza furmazione speciale))

Chì pò esse migliuratu?

Ci hè, sicuru, assai opzioni quì. Aghjunghjite icone supplementari (tutti quelli esistenti sò aghjuntu in linea à u script). Sceglite un settore più espressivu di icone. Fate pussibule di specificà u stilu di a linea di cunnessione. Aghjunghjite una imagine di fondo.

Chi pensi?
 
Aghju digià parechje idee per l'implementazione in tematiche, pudete ancu aghjunghje u vostru in i cumenti.

A mo suluzione hè definitivamente applicabile in una gamma ristretta di prublemi, è forse truverete un strumentu più convenientu per disegnu diagrammi solu codificà - cum'è dicenu "mostrami u vostru diagramma cum'è codice"

  1. Bella scelta
  2. Gran serviziu (9 tipi di grafici editore in linea)
  3. Di sicuru, mermaid.js
  4. È se ti piace i diagrammi super detallati è cumplessi, allora ammirerete sicuramente stu prughjettu: vai.drawthe.net

Source: www.habr.com

Add a comment