Në dy vitet e fundit kam filluar të merrem më shumë me dokumentacionin. Për të shkruar një tekst shpjegues rreth asaj si funksionon një sistem i caktuar — në përgjithësi, kjo është mjaft e thjeshtë. Të vizatosh një skemë që do të shfaqë të gjitha objektet kyçe dhe lidhjet midis këtyre objekteve gjithashtu është mjaft e lehtë.
Por momenti më problematik është të mbash këtë dokumentacion në gjendje të azhurnuar. E mira do të ishte po të ishte vetëm teksti, por skemat… Duke qenë se gjithë dokumentacioni është online, dmth. në formatin html, tekstit i bashkëngjiten imazhe gif/jpg/png që tregojnë skemat. Dhe skemat vizatohen në programe të ndryshme si Visio ose shërbime online si draw.io. Më pas eksportoni skemën në format grafik dhe e bashkëngjitni në html. E gjitha është e thjeshtë.
Cila është problemi?
Skemat zakonisht janë të thjeshta. Më saktë, nuk janë shumë komplekse. Po, numri i objekteve është disa dhjetëra, numri i lidhjeve është afërsisht i njëjtë. Plus shënimet, ndonjë përcaktim. Skemat e thjeshta mund t'i përshkruajmë me fjalë, ndërsa ato shumë komplekse, uh… (c) "nuk do të kuptohen". Ka shumë skema, ndërrimet në to duhen bërë periodikisht, dmth. vazhdimisht, pasi ato ndiqen përpara zhvillimit të produkteve tona.
A mund t'i integrojmë skemat në html të shërbimit? A e ke provuar?
Po, sigurisht. Mua, për shembull, më pëlqejnë grafikat e gliffy.com. Por për ndryshimet duhet të shkoj në shërbimin e jashtëm, atje për të rregulluar. Dhe është më e vështirë të delegosh një koleg për të bërë ndryshimet.
Çfarë të bëjmë?
Së fundmi, më doli në rekomandime në github një depo . Diagrami si kod. Në kuptimin që ne përshkruajmë skemën që na nevojitet në js. Ky js e shkruajmë direkt në HTML-në ku ndodhet edhe teksti tjetër i dokumentacionit.
Për t'i thënë të vërtetën, unë nuk e shkruaj dokumentacionin krejtësisht në html. Zakonisht, dokumentacioni është një grup skedare me tekst markdown, i cili më pas konvertohet në një faqe të plotë dokumentacioni në ndonjë motor, për shembull wintersmith. Ose një sistem wiki.
Kjo është shumë e përshtatshme: ja, ne shkruajmë tekstin, më pas hapet etiketa script dhe aty është përshkruar kodi js i skemës.
Çfarë nuk është në rregull tani?
Kjo depo më pëlqeu, por nuk është shembulli i vetëm kur diagramet vizatohen me ndihmën e kodit ose paraqitjes tekstuale. (Në fund të artikullit do të jenë linket e projekteve dhe artikujve që kam gjetur në temën diagram as code.)
Dhe unë nuk jam i vetmi që redakton dokumentacionin. Ndonjëherë, kolegët e mi kontribuojnë gjithashtu — një fjalë për të rregulluar, për të ndryshuar përshkrimin, për të futur imazhe të reja.
Prandaj, do të doja të shihja diagramin në një format të lexueshëm dhe të kuptueshëm tekstual, për të cilin nuk do të duhej të mësoja gjatë. Disa herë, madje thjesht të bëj kopje dhe ngjitje për të përshpejtuar shtimin e një skeme të re.
Një koleg tjetër vuri re se kodi është me të vërtetë i mirë, por nëse përdorim strukturën, gjithçka mund të jetë shumë strikte dhe shprehëse.
Prandaj, përpiqesha ta paraqes diagramin si një grup disa masivash të vogla, të cilat përshkruajnë gjurmët, lidhjet, grupet e gjurmëve, si dhe vendosjen e gjurmëve. Më duket mjaft e përshtatshme, megjithatë, sigurisht, për shije dhe ngjyrë...
Si është ky diagram në masiv?
- Çdo gjurmë përshkruhet me një identifikues, i cili e përcakton qartë atë.
- Gjurmës gjithashtu mund t'i shtohet një ikonë, mund t'i shtohet një etikettë.
- Mes dy gjurmëve mund të tregoni një lidhje.
- Për lidhjen në diagram, mund të caktoni një ngjyrë, një etikettë.
- Drejtimi i lidhjes përcaktohet si nga burimi në destinacion. Burimi dhe destinacioni tregohen me identifikuesit e gjurmëve.
- Një ose më shumë gjurmë mund të shtohen në një grup.
- Lidhja gjithashtu mund të tregohet dhe nga grupi, dhe në grup.
Duke përdorur këto rregulla të thjeshta, e marrim një diagram të tillë. Thjesht? Plotësisht.
Ajo përshkruhet me këtë kod js. E rëndësishmja këtu është objekti elements. Në të janë treguar nodes - gjurmët, edges - lidhjet.
const elements = {
nodes: [ // përshkruajmë gjurmët
{ 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: [ // tregojmë lidhjet
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Sigurisht, vizatimin e diagramit nuk e kam shpikur vetë, por kam përdorur një bibliotekë — një mjet shumë i fuqishëm vizualizimi. Një pjesë të mundësive të saj e përdor vetëm në zgjidhjen time.
E kuptueshme, ky është një shembull i thjeshtë. A mund të jetë më i komplikuar?
Po, sigurisht. Për të treguar pozitat - ne përdorim positions, për të treguar grupet - specifikojmë listën e grupeve në groups, dhe për elementët e vet ne kemi atributin group.
Dhe ky është kodi:
<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>
Një diagram i tillë nga njëra anë - është pothuajse dy ekrane kodi në laptop, ndërsa struktura e tipit json lejon plotësimin e të dhënave duke u bazuar në analogji, shpejt dhe mund të bëhet kopje-ngjitje.
E pse pozitat janë nxjerrë veçmas nga gjurmët?
Kjo është më e lehtë. Së pari, ne shënojmë nodes. Pastaj mund të caktuam disa grupe dhe t'i përfshijmë ato në njësitë. Më pas, vendosim lidhjet. E më pas, kur objektet kryesore dhe lidhjet midis tyre janë vendosur, fillojmë me pozicionimin e këtyre objekteve në diagram. Ose përndryshe.
A është e mundur pa pozita?
Është e mundur edhe pa pozita. Por do të jetë paksa e zhurmshme, mund të shihni një variant të tillë në shembuj. Kjo ndodh për shkak se për cytoscape ka një algoritëm për vendosjen e njësive. , i cili gjithashtu merr parasysh praninë e grupeve. Caktimi i pozicioneve e bën diagramin më të kontrollueshëm, por në fazën e skicës fillestare mund të bëhet pa pozita.
Gjithashtu, pozitat mund të caktohen në stilin e Luftës së Dytë Botërore. Pra, një njësi është vendosur në a1, dhe tjetra në d5. Sidomos ndihmon fakti se cytoscape formon objektet në canvas si të lëvizshme, kështu që mund t'i lëvizim ato, të shohim variante të ndryshme të vendosjes, dhe më pas të fiksojmë në kod pozicionin që na pëlqen.
Në përgjithësi, është e qartë. Mund të provojmë?
Sigurisht, për të krijuar shpejt skemat kam bërë një të vogël , e cila përditëson automatikisht diagramin dhe ruan variantin e fundit në shfletues (në localStorage).
Keni provuar? Tani mund ta shtoni edhe në faqen tuaj.
Atëherë përsëri:
1. Lidhni skriptën
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Shtojmë në kodin 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. rregullojmë kodin sipas diagramit që na nevojitet (mendoj, kjo është më e lehtë se sa të vizatosh një huk 🙂
Edhe më në detaje në në GitHub.
Çfarë në përfundim?
Qëllimet e mia i kam arritur — të bëj shtimin e skemave inline në dokumentacion, formati është mjaft i thjeshtë dhe i kuptueshëm. Nuk është e përshtatshme për super skema, por për skema të vogla, që shpjegojnë strukturën e lidhjeve — është shumë i përshtatshëm. Gjithmonë është e mundur të rregullohet shpejt dhe të ndryshohet diçka me kalimin e kohës. Po, dhe kolegët mund ta rregullojnë vetë diçka në dokument, të paktën shënimet për objektet pa ndonjë trajnim të veçantë ))
Çfarë mund të përmirësohet?
Këtu ka sigurisht shumë mundësi. Të bëjmë shtimin e ikonave shtesë (të gjitha ato që ekzistojnë janë shtuar inline në skript). Të zgjedhim një set më të shprehur të ikonave. Të ofrojmë mundësinë e caktimit të stilit të linjave të lidhjeve. Të shtojmë një imazh sfondi.
Çfarë mendoni ju?
Unë kam disa ide për realizim në issues, ju gjithashtu shtoni të tuajat në komentet.
Zgjidhja ime është padyshim e aplikueshme në një spektrum të ngushtë detyrash, dhe ndoshta do të gjeni një mjet më të përshtatshëm për të vizatuar diagramet, thjesht duke i koduar ato — siç thuhet ‘më trego diagramin tënd si kod’
- (9 lloje diagramesh redaktori online)
- Dhe nëse ju pëlqejnë skemat super të detajuara dhe të komplikuara — ky projekt do t'ju impresionojë patjetër:
Burimi: habr.com
