ProHoster > Blogs > Administrācija > Tīklu shēma kā kods

Tīklu shēma kā kods

Pēdējos divos gados esmu vairāk pievērsies dokumentācijai. UzrakstÄ«t skaidrojoÅ”u tekstu par to, kā darbojas sistēma, ir diezgan viegli. UzzÄ«mēt shēmu, kurā attēlotas visās galvenās objekti un to savienojumi, arÄ« ir pavisam viegli.

Bet pats problēmjautājums ir uzturēt Å”o dokumentāciju aktuālā stāvoklÄ«. Un vēl labi bÅ«tu, ja runātu tikai par tekstu, bet shēmāmā€¦ Tā kā visa dokumentācija ir tieÅ”saistē, t.i., HTML formātā, pie teksta pievienojas GIF/JPEG/PNG attēli, kuros faktiski attēlotas shēmas. Un shēmas tiek zÄ«mētas dažādās programmās, piemēram, Visio vai tieÅ”saistes pakalpojumos, kā draw.io. Pēc tam eksportē shēmu grafiskajā formātā un pievieno to HTML. Viss ir vienkārÅ”i.

Kas tad ir problēma?

Shēmas parasti ir vienkārÅ”as. PrecÄ«zāk, neveido pārāk sarežģītas. Jā, objekta skaits var bÅ«t desmit vai divpadsmit, un savienojumu skaits aptuveni tikpat. Plus piezÄ«mes, kaut kādi apzÄ«mējumi. VienkārÅ”as shēmas ir iespējams aprakstÄ«t arÄ« vārdos, bet pārāk sarežģītu, hmmmā€¦ (c) "neizpratÄ«s". Shēmu ir daudz, un izmaiņas tajās ir jāveic regulāri - tieÅ”i tāpēc, ka tās seko mÅ«su produktu attÄ«stÄ«bai.

Taču var taču iekļaut HTML no pakalpojuma. Tu izmēģināji?

Jā, protams. Man, piemēram, patÄ«k grafikas gliffy.com. Bet, lai veiktu izmaiņas, ir jādodas uz treÅ”o puÅ”u pakalpojumu, tur jāveic izmaiņas. Un ir grÅ«tāk deleģēt kolēģim, lai viņŔ veic labojumus.

Ko darīt?

Nesen GitHub man parādÄ«jās ieteikumu sarakstā repozitorijs github.com/RaoulMeyer/diagram-as-code. Diagramma kā kods. T.i., mēs aprakstām vajadzÄ«go shēmu js valodā. Å o js mēs rakstām tieÅ”i tajā paŔā HTML, kur arÄ« pārējais dokumentācijas teksts.

Jāsaka, ka es nesarakstu dokumentāciju Ä«sti HTML formātā. Parasti dokumentācija ir failu kopums ar markdown tekstu, kas pēc tam tiek pārvērsts par pilnvērtÄ«gu dokumentācijas vietni, izmantojot kādu motoriņŔ, piemēram, wintersmith. Vai wiki sistēmu.

Sanāk ļoti ērti: mēs uzrakstām tekstu, pēc tam atveram tagu script, un tajā ir aprakstīts shēmas js kods.

Kas atkal nav kārtībā?

Å is repozitorijs man ļoti patika, bet tas nav vienÄ«gais piemērs, kad diagrammu zÄ«mē, izmantojot kodu vai teksta pārstāvniecÄ«bu. (Raksta beigās bÅ«s saites uz projektiem un rakstiem, ko esmu atradis par diagrammas izmantoÅ”anu kā kodu.)

Un patiesÄ«bā es neesmu viens, kas rediģē dokumentāciju. Dažreiz savu ieguldÄ«jumu sniedz arÄ« kolēģi ā€” labojot vārdus, mainot aprakstus, pievienojot jaunas bildes.Ā 

Tāpēc es vēlētos redzēt diagrammu saprotamā teksta formātā, kurā nebÅ«tu jāmācās ilgstoÅ”i. Un dažreiz pat vienkārÅ”i veikt copy-paste, lai paātrinātu jaunas shēmas pievienoÅ”anu.Ā 

Un vēl viens kolēģis pamanīja, ka kods ir, protams, labs, bet, ja izmantos struktūru, viss var izklausīties ļoti stingri un izteiksmīgi.

Tādēļ es mēģināju attēlot shēmu kā vairākus mazus masīvus, kas apraksta mezglus, saites, mezglu grupas un mezglu novietojumu. Manuprāt, tas iznāca pietiekami ērti, lai gan, protams, par gaumi un krāsu...

Kā tas ir diagramma masīvā?

  • Katrs mezgls tiek aprakstÄ«ts ar identifikatoru, kas viennozÄ«mÄ«gi definē mezglu.
  • ArÄ« pie mezgla var pievienot ikonu, pievienot uzrakstu.
  • Starps diviem mezgliem var norādÄ«t saiti.
  • Saitēm shēmā var norādÄ«t krāsu, uzrakstu.
  • Saites virziens tiek definēts no avota uz mērÄ·i. Avots un mērÄ·is tiek norādÄ«ti ar mezglu identifikatoriem.
  • Vienu vai vairākus mezglus var pievienot grupai.
  • Saiti var norādÄ«t arÄ« no grupas un uz grupu.

Izmantojot Å”os vienkārÅ”os noteikumus, iznāk Ŕāda shēma. VienkārÅ”i? PilnÄ«gi.

Tīklu shēma kā kods

To apraksta Ŕāds js-kods. Galvenais Å”eit ir objekts elements. Kurā norādÄ«ti mezgli ā€” mezgli, malas ā€” saites.
Ā 

  const elements = {
    nodes: [       // aprakstām mezglus
      { 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: [       // norādām saites
      { source: 'client', target: 'server', label: 'request' },
      { source: 'server', target: 'db1', label: 'request' },
      { source: 'server', target: 'db2', label: 'request' },
    ],
  };
  Diagram('scheme1', elements);

Protams, shēmas attēloÅ”anu es neizdomāju pats, bet izmantoju bibliotēku cytoscape.js ā€” ļoti jaudÄ«gs vizualizācijas rÄ«ks. Daļu iespēju, ko savā risinājumā izmantoju, Å”aurināts.Ā 

Saprotams, tas ir vienkārÅ”s piemērs. Vai var nedaudz sarežģītāk?

Jā, lÅ«dzu. Lai norādÄ«tu pozÄ«cijas ā€” mēs izmantojam positions, lai norādÄ«tu grupas ā€” norādām grupu sarakstu groups, bet paÅ”iem elementiem atribÅ«tu group.

Tīklu shēma kā kods

Un Ŕis ir kods:

<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 shēma no vienas puses ir gandrīz divi ekrāni koda uz portatīvā datora, no otras puses, struktūra a`la json ļauj ātri aizpildīt visus datus pēc analoģijas, ātri un var veikt copy-paste.

Un kāpēc positions ir izdalÄ«ts atseviŔķi no mezgliem?

Tas ir ērtāk. Sākumā mēs norādām mezglus. Pēc tam varam norādÄ«t vairākas grupas un iekļaut tās mezglos. Pēc tam iegÅ«stam attiecÄ«bas. Un tad, kad galvenie objekti un to attiecÄ«bas ir definētas, mēs pievērÅ”amies Å”o objektu izvietojumam shēmā. Vai arÄ« pretēji.

Bet vai var bez pozīcijām?

Var arÄ« bez pozÄ«cijām. Bet tas bÅ«s nedaudz sasteigts; piemēros var redzēt tādu variantu. Tas ir saistÄ«ts ar to, ka cytoscape piedāvā mezglu izvietojuma algoritmu. fcose, kas arÄ« ņem vērā grupu esamÄ«bu. PozÄ«ciju norādÄ«Å”ana padara shēmu kontrolētāku, bet pirmā skices posmā var iztikt arÄ« bez pozÄ«cijām.

PozÄ«cijas var norādÄ«t arÄ« jÅ«ras kaujas stilā. T.i., viens mezgls atrodas a1, bet otrs d5. ÄŖpaÅ”i noderÄ«gi, ka cytoscape veido objektus uz kanvas kā kustÄ«gus, t.i., mēs varam tos pārvietot, aplÅ«kot dažādus izvietojuma variantus, un pēc tam fiksēt kodā patÄ«kamo elementu izvietojumu.

Kopumā viss ir skaidrs. Varam pamēģināt?
Ā 
Protams, ātrai shēmu izveidei es izveidoju mazliet redaktors, kas automātiski atjauno shēmu un pārlūkprogrammā saglabā pēdējo variantu (localStorage).

Pamēģinājāt? Tagad varam pievienot arī pie savas lapas.

Tad vēlreiz:

1. Pievienojam skriptu

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

2. Pievienojam 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. pārveidojam kodu lÄ«dz vajadzÄ«gajai shēmai (domāju, tas ir vieglāk nekā uzzÄ«mēt pÅ«ci šŸ™‚

Vēl sīkāk par to projekta lapu uz GitHub.

Ko mēs iegūstam?

Es esmu sasniedzis savus mērÄ·us ā€” izveidot shēmu pievienoÅ”anu tieÅ”saistē dokumentācijā, formāts ir gana vienkārÅ”s un saprotams. Super shēmām tas nederēs, bet nelielām shēmām, kas izskaidro attiecÄ«bu struktÅ«ru ā€” ir visai noderÄ«gi. Vienmēr var ātri koreģēt un laika gaitā kaut ko mainÄ«t. Jā, un kolēģi var paÅ”i dokumentācijā kaut ko labot, vismaz objektu apzÄ«mējumus bez Ä«paÅ”as apmācÄ«bas ))

Ko varētu uzlabot?

Te noteikti ir vesela virkne iespēju. Izveidot iespēju pievienot papildu ikonām (visas esoŔās ir pievienotas tieÅ”saistē skriptā). Atrast izteiksmÄ«gāku ikonu komplektu. Izveidot iespēju norādÄ«t saistÄ«bu lÄ«niju stilu. Pievienot fona attēlu.

Un kādas ir jūsu domas?
Ā 
Man jau ir dažas idejas realizÄ“Å”anai jautājumos, jÅ«s arÄ« pievienojiet savas komentāros.

Mans risinājums noteikti ir piemērojams Å”auram uzdevumu spektram, un, iespējams, jÅ«s atradÄ«siet ērtāku diagrammu zÄ«mÄ“Å”anas rÄ«ku, vienkārÅ”i to kodējot ā€” kā saka 'rādi man savu diagrammu kā kodu'

  1. Laba izlase
  2. Lielisks pakalpojumsĀ (9 veidu grafiku tieÅ”saistes redaktors)
  3. ŠšŠ¾Š½ŠµŃ‡Š½Š¾, mermaid.js
  4. Un, ja jums patÄ«k super detalizētas un sarežģītas shēmas ā€” tad Å”is projekts noteikti jÅ«s pārsteigs: go.drawthe.net

Avots: habr.com

Iegādājieties uzticamu tÄ«mekļa hostingu ar DDoS aizsardzÄ«bu, VPS VDS serveriem šŸ”„ Iegādājieties uzticamu tÄ«mekļa hostingu ar DDoS aizsardzÄ«bu, VPS VDS serveriem | ProHoster