Viimase paari aasta jooksul olen rohkem keskendunud dokumentatsioonile. Selgitava teksti kirjutamine selle kohta, kuidas mingi süsteem töötab, on enamasti üsna lihtne. Skeemi joonistamine, kus on näidatud kõik võtmeobjektid ja nendevahelised seosed, on samuti täiesti teostatav.
Aga kõige probleemsem aspekt on selle dokumentatsiooni ajakohasena hoidmine. Ja kui tekst polegi probleem, siis skeemid… Kuna kogu dokumentatsioon on veebis, st HTML-formaadis, lisatakse tekstile gif/jpeg/png pilte, kus on kujutatud skeeme. Skeemid joonistatakse erinevates programmides nagu Visio või veebiteenustes nagu draw.io. Siis ekspordid skeemi graafikavormingusse ja lisad HTML-le. Kõik on lihtne.
Mis on probleem?
Skeemid on tavaliselt lihtsad. Täpsemalt, mitte väga keerulised. Jah, objekti arvu on tosin-kaks, sidemete arv on umbes sama. Pluss märgised, mingid tähistused. Lihtsaid skeeme saab ka sõnadega kirjeldada, aga liiga keerulisi, k-ex… (c) "ei saa aru-s". Skeeme on palju, neid tuleb aeg-ajalt perioodiliselt uuendada, st pidevalt, kuna need järgivad meie toodete arendust.
HTML teenust saab integreerida. Kas oled proovinud?
Jah, muidugi. Minu jaoks meeldivad näiteks gliffy.com diagrammid. Kuid muudatuste tegemiseks tuleb minna kolmandasse teenusesse ja seal neid redigeerida. Samuti on keerulisem volitada kolleegi muudatusi tegema.
Mis teha?
Hiljuti sattusin GitHubis soovitustes kokkuhoidlikku hoidla . Diagramm kui kood. St, kirjeldame vajalikku skeemi Javascriptis. Selle Javascripti kirjutame otse sinna HTML-i, kus on muu dokumentatsiooni tekst.
Muide, aga ma ei kirjuta dokumentatsiooni päris html-is. Üldjuhul on dokumentatsioon failide kogum markdown-tekstiga, mis seejärel konverteeritakse täielikuks dokumentatsioonileheks mingisuguse mootori, näiteks wintersmith abil. Või wiki-süsteem.
See on väga mugav: olgem, et me oleme teksti kirjutanud, siis avatakse scripti sild ja seal on kirjeldatud skeemi Javascripti kood.
Mis nüüd valesti on?
See hoidla meeldis mulle, kuid see ei ole ainus näide, kuidas diagrammi tõmmatakse koodi või tekstilise esitusviisi abil. (Artikli lõpus on lingid projektidele ja artiklitele, mida leidsin diagrammide kui koodi kohta.)
Ja ei ole ainus, kes dokumentatsiooni haldamisse panustab. Mõnikord teevad ka kolleegid oma osa – parandavad sõnu, muudavad kirjeldusi, lisavad uusi pilte.
Seetõttu sooviksin näha diagrammi arusaadavas ja loetavas tekstiformaadis, mille õppimiseks ei peaks kaua aega kulutama. Mõnel juhul saaks isegi lihtsalt copy-paste teha, et uue skeemi lisamist kiirendada.
Veel märkis üks kolleeg, et kood on muidugi hea, kuid kui kasutada struktuuri, on kõik väga rangelt ja väljendusrikkalt korraldatud.
Seetõttu proovisin kujutada skeemi kui mitme väikese massiivi kogumit, mis kirjeldavad sõlmi, seoseid, sõlmede gruppe ning sõlmede asukohti. Minu tagasihoidlikul arvamusel on see piisavalt mugav, kuigi maad on ka erinevad maitsed...
Kuidas see diagramm massiivis välja näeb?
- Iga sõlm on kirjeldatud identifikaatoriga, mis määratleb sõlme üheselt.
- Sõlmele saab ka lisada ikooni ja lisada sildi.
- Kaks sõlme võivad olla omavahel seotud.
- Seosele skeemis saab määrata värvi ja sildi.
- Seose suund on määratletud kui allikast sihtkohta. Allikas ja sihtkoht määratakse sõlme identifikaatoritega.
- Ühte või enam sõlme saab grupisse lisada.
- Seose saab määrata nii grupist kui grupi jaoks.
Nende lihtsate reeglitega saame sellise skeemi. Lihtne? Kindlasti.
Ja see kirjeldatakse järgmise js-koodiga. Peamine on objekt elements, milles on määratud nodes – sõlmed, edges – seosed.
const elements = {
nodes: [ // kirjeldame sõlmi
{ 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: [ // määrame seosed
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Muidugi, skeemi joonistamine ei ole minu idee, vaid kasutasin raamatukogu. — väga võimas visualiseerimise tööriist. Selle võimaluste osakese kasutan oma lahenduses.
Selge, see on lihtne näide. Kas midagi keerulisemat?
Jah, palun. Positsioonide määramiseks kasutame positions, grupi määramiseks loetleme grupid groups, ja elementide puhul on atribuut group.
Ja see on kood:
<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>
Selle diagrammi puhul on ühelt poolt tegemist peaaegu kahekordse koodiekraaniga sülearvutis, teiselt poolt json-sarnane struktuur võimaldab andmete sisestamist analoogia põhiselt, kiiresti ning hõlpsasti kopeerida ja kleepida.
Aga miks on positions välja toodud eraldi sõlmedest?
Nii on mugavam. Esmalt määrame sõlmed. Seejärel saame märkida paar gruppi ja viidata neile sõlmedes. Seejärel määrame seosed. Ja kui peamised objektid ja nende vahelised seosed on olemas, saame keskenduda nende objektide paigutusele diagrammil. Või vastupidi.
Kas saab ilma positions'ita?
Saab ka ilma positions'ita. Kuid see jääb natuke kokku surutud, näidetes võib sellist varianti näha. See tuleneb sellest, et cytoscape’il on sõlmede paigutamiseks algoritm. , mis arvestab ka gruppide olemasolu. Positions'i määramine teeb diagrammi kontrollitavamaks, kuid esimese visandi loomise etapis saab ka ilma positions'ita hakkama.
Samuti saab positions'e märkida nagu Meresõda. St. üks sõlm asub a1, teine d5. Eriti aitab see, et cytoscape loob objekti canvas'ile liikuva, st me saame neid liigutada, vaadata erinevaid paigutuse variante ja seejärel salvestada koodis meeldinud paigutuse.
Kokkuvõttes on selge. Kas saame proovida?
Muidugi, et kiiresti skeeme luua, tegin endale väikese , mis uuendab skeemi automaatselt ja salvestab viimase variandi brauseris (localStorage).
Kas olete proovinud? Nüüd saab seda ka oma lehele lisada.
Siis veel kord:
1. Ühendame skripti
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Lisame HTML koodi
<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. muudame koodi vajalikuks skeemiks (arvan, et see on lihtsam kui öökulli joonistamine 🙂
Veel üksikasjalikult GitHubis.
Mis on lõpptulemus?
Olen oma eesmärgid saavutanud — teha skeemide inline lisamine dokumentatsioonis, formaat on piisavalt lihtne ja arusaadav. Suuremate skeemide jaoks ei sobi, kuid väikestele skeemidele, mis selgitavad suhete struktuuri — väga hästi. Alati saab kiiresti midagi korrigeerida ja aja jooksul muuta. Ja kolleegid saavad dokumendis ise midagi kohandada, vähemalt objektide märke ilma eriliste õppeta ))
Mida võiks parandada?
Siin on palju võimalusi. Teha lisasümbolite lisamine (kõik olemasolevad on skeemi sees). Valida väljendusrikkam sümbolite komplekt. Luua võimalus määrata suhete joone stiil. Lisada taustapilt.
Aga mida teie arvate?
Mul on juba mitu ideed küsimustes rakendamiseks, lisage ka oma kommentaarides.
Minu lahendus on kindlasti rakendatav kitsas probleemide ringis, ja võib-olla leiate mugavama diagrammide joonistamise tööriista, kodeerides need lihtsalt - nagu öeldakse 'näita mulle oma diagrammi kui koodi'
- (9 tüüpi diagramme veebiredaktoris)
- Ja kui teile meeldivad ülihästi detailitud ja keerulised skeemid - siis see projekt kindlasti üllatab teid:
Allikas: habr.com
