NĂ€tverksdiagram som kod

Under de senaste Ären har jag blivit mer involverad i dokumentation. Att skriva en förklarande text om hur ett visst system fungerar Àr överlag ganska enkelt. Att rita en diagram som visar alla nyckelobjekt och relationer mellan dessa objekt Àr ocksÄ relativt lÀtt.

Men den största utmaningen Àr att hÄlla denna dokumentation uppdaterad. Det skulle vara okej om det bara var texten, men diagrammen... Eftersom all dokumentation Àr online, det vill sÀga i html-format, sÄ medföljer bilder i gif/jpeg/png-format som faktiskt visar diagrammen. Dessa diagram ritas i olika program som Visio eller online-tjÀnster som draw.io. DÀrefter exporterar man diagrammet i ett grafiskt format och fÀster det i html. Allt Àr enkelt.

Vad Àr problemet?

Diagrammen Àr vanligtvis enkla. Mer exakt, inte sÀrskilt svÄra. Ja, antal objekt Àr ett tiotal, antalet relationer Àr ungefÀr lika mÄnga. Plus etiketter och nÄgra symboler. Enkla diagram kan Àven beskrivas med ord, men alltför komplexa, ehm... (c) "kommer inte att förstÄ-s". Det finns mÄnga diagram, och förÀndringar mÄste göras periodiskt, det vill sÀga stÀndigt, eftersom de följer utvecklingen av vÄra produkter.

Man kan integrera html-tjÀnster. Har du försökt?

Ja, sjÀlvklart. Jag gillar till exempel grafikerna frÄn gliffy.com. Men för att göra Àndringar mÄste man gÄ till en extern tjÀnst och Àndra dÀr. Det Àr ocksÄ svÄrare att delegera Àndringar till en kollega.

Vad göra?

HÀromdagen snubblade jag över ett repository pÄ GitHub som rekommenderades för mig. github.com/RaoulMeyer/diagram-as-code. Diagram som kod. Det vill sÀga, vi beskriver det javascript som vi behöver för vÄrt diagram. Denna javascript skriver vi direkt i samma html dÀr övrig dokumentation finns.

För att nÀmna, jag skriver dokumentation inte helt i html. Vanligtvis Àr dokumentationen en uppsÀttning filer med markdown-text som sedan konverteras till en fullstÀndig dokumentationswebbplats av nÄgon motor, till exempel wintersmith. Eller ett wikisystem.

Det blir mycket bekvÀmt: vi skriver text, och sedan öppnas script-taggen dÀr js-koden för diagrammet Àr beskriven.

Vad Àr nu problemet?

Detta repository gillade jag, men det Àr inte det enda exemplet dÀr man ritar diagram med hjÀlp av kod eller textuella representationer. (I slutet av artikeln kommer det att finnas lÀnkar till projekt och artiklar som jag har hittat om diagram som kod.)

Och jag Ă€r inte ensam om att rĂ€tta dokumentationen. Ibland bidrar kollegor med sina insatser — genom att rĂ€tta ord, Ă€ndra beskrivningar eller införa nya bilder. 

DÀrför skulle jag vilja se diagrammet i ett lÀsbart och förstÄeligt textformat som inte krÀver lÄng inlÀrning. Ibland kan det Àven vara bra att helt enkelt kopiera och klistra in för att snabba upp tillÀgg av nya scheman. 

En annan kollega pÄpekade att kod Àr bra, men om man anvÀnder en struktur, kan allt bli mycket strikt och uttrycksfullt.

DÀrför försökte jag förestÀlla mig schemat som en uppsÀttning smÄ arrayer som beskriver noder, kopplingar, grupper av noder och Àven placeringen av noder. Det blev enligt min blygsamma Äsikt ganska praktiskt, Àven om smaken Àr som baken.

Hur ser diagrammet ut i en array?

  • Varje nod beskrivs med ett identifieringsnummer som entydigt definierar noden.
  • Man kan ocksĂ„ lĂ€gga till en ikon till noden samt ett label.
  • Mellan tvĂ„ noder kan man ange en koppling.
  • För kopplingen i schemat kan man ange fĂ€rg och label.
  • Kopplingens riktning definieras som frĂ„n kĂ€lla till mĂ„l. KĂ€lla och mĂ„l anges med nodernas identifierare.
  • En eller flera noder kan lĂ€ggas till i en grupp.
  • Kopplingen kan ocksĂ„ anges frĂ„n gruppen och till gruppen.

Genom att anvÀnda dessa enkla regler fÄr man ett sÄdant schema. Enkelt? Absolut.

NĂ€tverksdiagram som kod

Det beskrivs med följande js-kod. Det viktigaste hÀr Àr objektet elements. DÀr noderna anger nodes och kopplingarna edges.
 

  const elements = {
    nodes: [       // beskriver noder
      { id: 'client', type: 'smartphone', label: 'Mobilapp'},
      { id: 'server', type: 'server', label: 'Huvudserver'},
      { id: 'db1', type: 'database', label: 'DB 1'},
      { id: 'db2', type: 'database', label: 'DB 2'},
    ],
    edges: [       // anger kopplingar
      { source: 'client', target: 'server', label: 'begÀran' },
      { source: 'server', target: 'db1', label: 'begÀran' },
      { source: 'server', target: 'db2', label: 'begÀran' },
    ],
  };
  Diagram('scheme1', elements);

Naturligtvis uppfann jag inte sjĂ€lva ritningen av schemat sjĂ€lv, utan anvĂ€nde ett bibliotek. cytoscape.js — ett mycket kraftfullt visualiseringsverktyg. Jag anvĂ€nder endast en brĂ„kdel av dess möjligheter i min lösning. 

SjÀlvklart, det hÀr Àr ett enkelt exempel. Kan vi göra det lite mer komplicerat?

Ja, sjÀlvklart. För att ange positioner anvÀnder vi positions, för att ange grupper anger vi en lista över grupper i groups, och för sjÀlva elementen har vi attributet group.

NĂ€tverksdiagram som kod

Och hÀr Àr koden:

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

Ett sÄdant schema frÄn ena sidan Àr nÀstan ett par skÀrmar kod pÄ en bÀrbar dator, Ä andra sidan gör strukturen liknande json det möjligt att fylla i alla data pÄ analogt sÀtt, snabbt och gÄr att kopiera och klistra in.

Och varför Àr positions separerade frÄn noderna?

Det Àr enklare. Först anger vi noder. Sedan kan vi ange ett par grupper och ange dem i noderna. DÀrefter markerar vi relationerna. Och först nÀr de grundlÀggande objekten och relationerna mellan dem finns, sÀtter vi oss ner för att placera dessa objekt pÄ diagrammet. Eller tvÀrtom.

Kan man göra utan positions?

Ja, man kan göra utan positions. Men det blir lite klumpigt, i exemplen kan man se ett sÄdant alternativ. Detta beror pÄ att det finns en algoritm för att placera noder i cytoscape. fcose, som ocksÄ tar hÀnsyn till grupper. Angivande av positions gör diagrammet mer kontrollerat, men i det första utkastet av diagrammet kan man klara sig utan positions.

Positions kan ocksÄ anges i stil med Sjöslag. Dvs. en nod placeras i a1, och en annan i d5. Speciellt hjÀlpsamt Àr att cytoscape formar objekt pÄ canvasen som Àr flyttbara, dvs. vi kan flytta dem, se olika placeringsalternativ och sedan fixa det vi gillar i koden.

Överlag, förstĂ„tt. Kan vi försöka?
 
SjÀlvklart, för att snabbt skapa diagram har jag gjort mig en liten redigeraren, som sjÀlv uppdaterar diagrammet och sparar den senaste versionen i webblÀsaren (i localStorage).

Har ni provat? Nu kan ni ocksÄ lÀgga till det pÄ er egen sida.

DÄ en gÄng till:

1. Anslut skriptet

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

2. LĂ€gg till i html-koden

<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. justera koden till det diagram vi vill ha (jag tror att det Ă€r enklare Ă€n att rita en uggla 🙂

Ännu mer detaljerat pĂ„ projektets sida pĂ„ GitHub.

Vad blir resultatet?

Mina mÄl har jag uppnÄtt - att göra det enkelt att lÀgga till diagram inline i dokumentationen, formatet Àr tillrÀckligt enkelt och begripligt. Det passar inte för superdiagram, men för smÄ diagram som förklarar strukturera relationer - Àr det helt okej. Man kan snabbt justera och nÄgot Àndras över tid. Ja, och kollegor kan sjÀlva rÀtta till nÄgot i dokumentet, Ätminstone rubriker till objekten utan sÀrskild utbildning :)

Vad kan förbÀttras?

Det finns naturligtvis mÄnga alternativ. Göra tillÀgg av ytterligare ikoner (alla befintliga Àr tillagda inline i skriptet). VÀlja en mer uttrycksfull uppsÀttning ikoner. Göra det möjligt att ange stil för relationernas linjer. LÀgga till en bakgrundsbild.

Vad tycker ni?
 
Jag har redan nÄgra idéer för genomförande i issues, ni kan ocksÄ lÀgga till era egna i kommentarerna.

Min lösning Ă€r definitivt tillĂ€mplig inom ett smalt spektrum av uppgifter, och du kanske hittar ett mer praktiskt verktyg för att rita diagram genom att helt enkelt koda dem — som man sĂ€ger 'show me your diagram as code'

  1. Bra samling
  2. Fantastisk tjÀnst (9 typer av diagram online-redigerare)
  3. ĐšĐŸĐœĐ”Ń‡ĐœĐŸ, mermaid.js
  4. Och om du Ă€lskar super detaljerade och komplexa scheman — sĂ„ kommer definitivt detta projekt att imponera pĂ„ dig: go.drawthe.net

KĂ€lla: habr.com

Köp pĂ„litlig webbhotell med DDoS-skydd, VPS VDS-servrar đŸ”„ Köp pĂ„litlig webbhotell med DDoS-skydd, VPS VDS-servrar | ProHoster