ProHoster > Blog > Administrazioa > Sare-diagrama kode gisa / Network diagram as code

Sare-diagrama kode gisa / Network diagram as code

Azken bi urteetan gehiago sartu naiz dokumentazioan. Sistema hau edo bestea nola funtzionatzen duen azaltzeko testu bat idaztea, oro har, nahiko erraza da. Objektu gako guztiak eta objektu horien arteko konexioak bistaratuko dituen diagrama bat marraztea ere nahiko erraza da.

Baina alderdirik problematikoena dokumentazio hau eguneratuta mantentzea da. Eta testua ondo legoke, baina diagramak... Zeren... dokumentazio guztia sarean dago, hau da. html formatuan, gero testua gif/jpeg/png irudiekin batera dator, diagramak benetan erakusten dituztenak. Eta diagramak hainbat programetan marrazten dira, hala nola Visio edo lineako zerbitzuak a la draw.io. Ondoren, diagrama formatu grafikora esportatzen duzu eta html-ra eransten duzu. Sinplea da.

Zein da arazoa?

Eskemak sinpleak izan ohi dira. Zehatzago esanda, ez oso konplikatua. Bai, objektu kopurua dozena bat edo bi da, konexio kopurua gutxi gorabehera berdina da. Gainera sinadurak, izendapen batzuk. Eskema sinpleak hitzez deskriba daitezke, baina konplexuegiak, ejem... (c) β€œez dute ulertuko, jauna”. Eskema asko daude, aldaketak egin behar zaizkie aldian-aldian, episodikoki, alegia. etengabe, zeren gure produktuen garapena jarraitzen dute.

Zerbitzuaren html txertatu dezakezu. Probatu al duzu?

Bai ziur. Adibidez, gliffy.com-eko grafikoak gustatzen zaizkit. Baina aldaketak egiteko, hirugarrenen zerbitzu batera joan eta bertan editatu behar duzu. Eta zailagoa da zuzenketak lankide bati delegatzea.

Zer egin?

Duela gutxi Github-en biltegi bat topatu dut gomendioetan github.com/RaoulMeyer/diagram-as-code. Diagrama kode gisa. Horiek. behar dugun zirkuitua js-en deskribatzen dugu. Js hau zuzenean idazten dugu beste dokumentazio testua dagoen html berean.

Bide batez, dokumentazioa ez dut guztiz html-n idazten. Normalean, dokumentazioa markdown testua duten fitxategi multzo bat da, eta, ondoren, motorren batek, adibidez, wintersmith-ek dokumentazio gune oso batean bihurtzen du. Edo wiki sistema bat.

Oso erosoa gertatzen da: testua idatzi dugu, gero script-etiketa irekitzen da eta eskemaren JS kodea deskribatzen da bertan.

Zer gertatzen da berriro?

Biltegi hau gustatu zait, baina hau ez da diagrama bat kodea edo testu irudikapena erabiliz marrazten den adibide bakarra. (Artikuluaren amaieran gaiaren diagraman Googlen bilatu ditudan proiektu eta artikuluetarako estekak egongo dira kode gisa.)

Eta ez naiz dokumentazioa editatzen duen bakarra. Batzuetan, lankideek ere laguntzen dute - hitz bat zuzendu, deskribapena aldatu, argazki berriak sartu. 

Hori dela eta, diagrama testu formatu irakurgarri eta ulergarrian ikustea gustatuko litzaidake, ikasketa kurba luzerik beharko ez lukeena. Eta leku batzuetan kopiatu-itsatsi ere egin dezakezu zirkuitu berri bat gehitzea bizkortzeko. 

Eta beste lankide batek adierazi zuen kodea, noski, ona dela, baina egitura erabiltzen baduzu, dena oso zorrotza eta adierazgarria izan daiteke.

Hori dela eta, diagrama nodoak, konexioak, nodo-taldeak eta nodoen kokapena deskribatzen dituen hainbat matrize txikiren multzo gisa imajinatzen saiatu nintzen. Nire uste apalean nahiko erosoa atera zitzaidan, nahiz eta, jakina, zaporea eta kolorea...

Nola da hau array bateko diagrama bat?

  • Nodo bakoitza nodoa modu esklusiboan identifikatzen duen identifikatzaile baten bidez deskribatzen da.
  • Nodoan ikono bat ere gehi dezakezu eta inskripzio bat gehi dezakezu.
  • Bi nodoen arteko erlazio bat zehaztu dezakezu.
  • Diagraman komunikaziorako, kolorea eta inskripzioa ezar ditzakezu.
  • Komunikazioaren norabidea iturburutik helburura bezala definitzen da. Eta iturburua eta helburua nodoen identifikatzaileen bidez adierazten dira.
  • Talde bati nodo bat edo gehiago gehi daitezke.
  • Harremana ere zehaztu daiteke bai taldetik eta baita taldearekin ere.

Arau sinple hauek erabiliz, honako diagrama hau lortuko dugu. Besterik gabe? Nahiko.

Sare-diagrama kode gisa / Network diagram as code

Eta hurrengo js kodean deskribatzen da. Hemen gauza nagusia elementuen objektua da. Zein nodo adierazten diren - nodoak, ertzak - konexioak.
 

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

Noski, ez nuen nik neuk asmatu zirkuituaren marrazkia, baizik eta liburutegia erabili nuen cytoscape.js bisualizazio tresna oso indartsua da. Nire soluzioan aukeren zati bat baino ez dut erabiltzen. 

Ados, hau adibide sinple bat da. Konplikatuagoa izan al daiteke?

Bai mesedez. Posizioak adierazteko, posizioak erabiltzen ditugu, taldeak adierazteko, taldeen zerrenda adierazten dugu, eta elementuek berek talde-atributua dute.

Sare-diagrama kode gisa / Network diagram as code

Eta hau da kodea:

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

Alde batetik, halako eskema bat ordenagailu eramangarri batean kode-pantaila ia pare bat da, bestetik, a la json egiturak datu guztiak analogiaz betetzeko aukera ematen du, azkar eta kopiatu-itsatsi dezakezu.

Zergatik jartzen dira posizioak nodoetatik bereizita?

Erosoagoa da. Lehenik eta behin nodoak zehaztuko ditugu. Ondoren, pare bat talde zehaztu ditzakegu eta nodoetan adierazi. Ondoren, konexioak izendatzen ditugu. Eta orduan bakarrik, objektu nagusiak eta haien arteko loturak hor daudenean, objektu horien kokapena diagraman hartzen dugu. Edo alderantziz.

Posible al da posturik gabe?

Posible da posiziorik gabe. Baina pixka bat zimurtuta egongo da; aukera hau adibideetan ikus dezakezu. Zitoscaperako nodoak kokatzeko algoritmo bat dagoelako da hori fkose, taldeen presentzia ere kontuan hartzen duena. Posizioak zehazteak diagrama kontrolagarriagoa egiten du, baina diagramaren lehen zirriborroaren fasean posible da posiziorik gabe.

Postuak Battleship estiloan ere zehaztu daitezke. Horiek. nodo bat a1-en dago, eta bestea d5-en. Batez ere laguntzen du cytoscape-k mihiseko objektuak mugitzen dituela, hau da. mugitu ditzakegu, diseinu-aukera desberdinak ikusi eta gero kodean gustuko ditugun elementuen antolamendua konpondu.

Orokorrean, ulergarria da. Probatu ere egin dezakezu?
 
Noski, zirkuitu azkar sortzeko, txiki bat egin nuen editorea, berak eskema eguneratzen du eta azken bertsioa nabigatzailean gordetzen du (localStorage-n).

Probatu al duzu? Orain zure orrialdera gehi dezakezu.

Gero berriro:

1. Gidoia lotzen

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

2. Gehitu kodea html-ra

<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. kodea editatzen dugu behar dugun diagrama (uste dut hontza marraztea baino errazagoa dela :)

Xehetasun gehiago helbidean proiektuaren orria github-en.

Emaitza?

Nire helburuak lortu ditut: dokumentazioari lerroko diagramak gehitzea, formatua nahiko sinplea eta ulergarria da. Ez da egokia super zirkuituetarako, baina konexioen egitura azaltzen duten zirkuitu txikietarako, guztiz ondo dago. Denboraren poderioz zerbait aldatu eta aldatu dezakezu beti. Bai, eta lankideek beraiek zuzendu dezakete zerbait kaian, gutxienez objektuentzako epigrafeak, prestakuntza berezirik gabe))

Zer hobetu daiteke?

Hemen, noski, aukera asko daude. Gehitu ikono gehigarriak (lehendik dauden guztiak lerroan gehitzen dira scriptean). Aukeratu ikono multzo adierazgarriagoa. Konexio-lerroaren estiloa zehazteko aukera eman. Gehitu atzeko planoko irudi bat.

Zer uste duzu?
 
Dagoeneko baditut hainbat ideia gaietan ezartzeko, zurea ere gehi dezakezu iruzkinetan.

Nire irtenbidea arazo sorta estu batean aplikagarria da zalantzarik gabe, eta beharbada diagramak marrazteko tresna erosoago bat aurkituko duzu horiek kodetzea besterik gabe - "erakutsi zure diagrama kode gisa" esaten duten moduan.

  1. Aukera polita
  2. Zerbitzu bikaina (9 grafiko mota lineako editorea)
  3. Jakina, mermaid.js
  4. Eta diagrama oso zehatzak eta konplexuak gustatzen bazaizkizu, zalantzarik gabe miresten duzu proiektu hau: joan.marraztu.net

Iturria: www.habr.com

Gehitu iruzkin berria