Në dy vitet e fundit jam marrë më shumë me dokumentacionin. Shkrimi i një teksti shpjegues për mënyrën se si funksionon një sistem i caktuar është përgjithësisht mjaft i thjeshtë. Vizatimi i një diagrami që do të shfaqë të gjitha objektet kryesore dhe lidhjet midis këtyre objekteve është gjithashtu mjaft i lehtë.
Por aspekti më problematik është mbajtja e këtij dokumentacioni të përditësuar. Dhe teksti do të ishte mirë, por diagramet... Sepse... i gjithë dokumentacioni është online, d.m.th. në format html, më pas teksti shoqërohet me foto gif/jpeg/png, të cilat në fakt tregojnë diagramet. Dhe diagramet vizatohen në programe të ndryshme si Visio ose shërbimet online a la draw.io. Më pas e eksportoni diagramin në formatin grafik dhe e lidhni atë në html. Është e thjeshtë.
Cili është problemi?
Skemat janë zakonisht të thjeshta. Më saktësisht, jo shumë e komplikuar. Po, numri i objekteve është një duzinë ose dy, numri i lidhjeve është afërsisht i njëjtë. Plus nënshkrime, disa emërtime. Skemat e thjeshta mund të përshkruhen me fjalë, por shumë komplekse, ah... (c) "ata nuk do të kuptojnë, zotëri." Ka shumë skema, duhet të bëhen ndryshime në to në mënyrë periodike, episodike, d.m.th. vazhdimisht, sepse ata ndjekin zhvillimin e produkteve tona.
Mund të futni html të shërbimit. E keni provuar?
Po sigurisht. Për shembull, më pëlqejnë grafika nga gliffy.com. Por për të bërë ndryshime, duhet të shkoni te një shërbim i palës së tretë dhe të modifikoni atje. Dhe është më e vështirë të delegosh korrigjime te një koleg.
Çfarë duhet të bëni?
Kohët e fundit kam hasur në një depo në Github në rekomandimet . Diagrami si kod. Ato. ne përshkruajmë qarkun që na nevojitet në js. Ne e shkruajmë këtë js drejtpërdrejt në të njëjtin html ku është teksti tjetër i dokumentacionit.
Nga rruga, unë shkruaj dokumentacion jo plotësisht në html. Në mënyrë tipike, dokumentacioni është një grup skedarësh me tekst shënjues, i cili më pas konvertohet në një faqe dokumentacioni të plotë nga disa motorë, për shembull dimërpunues. Ose një sistem wiki.
Rezulton shumë i përshtatshëm: ne kemi shkruar tekstin, pastaj hapet etiketa e skriptit dhe kodi JS i skemës përshkruhet në të.
Çfarë nuk shkon përsëri?
Më pëlqeu ky depo, por ky nuk është shembulli i vetëm ku një diagram vizatohet duke përdorur kodin ose një paraqitje teksti. (Në fund të artikullit do të ketë lidhje me projektet dhe artikujt që kam kërkuar në Google në diagramin e temës si kod.)
Dhe nuk jam i vetmi që redaktoj dokumentacionin. Ndonjëherë kolegët kontribuojnë gjithashtu - korrigjoni një fjalë, ndryshoni një përshkrim, futni fotografi të reja.
Prandaj, unë do të doja ta shihja diagramin në një format teksti të lexueshëm dhe të kuptueshëm që nuk do të kërkonte një kurbë të gjatë mësimi. Dhe në disa vende mund edhe thjesht të kopjoni-ngjisni për të shpejtuar shtimin e një qarku të ri.
Dhe një koleg tjetër vuri në dukje se kodi është, natyrisht, i mirë, por nëse përdorni strukturën, gjithçka mund të jetë shumë strikte dhe ekspresive.
Prandaj, u përpoqa ta imagjinoja diagramin si një grup i disa grupeve të vogla që përshkruajnë nyjet, lidhjet, grupet e nyjeve, si dhe vendndodhjen e nyjeve. Doli, për mendimin tim modest, mjaft i përshtatshëm, megjithëse, natyrisht, shija dhe ngjyra ...
Si është kjo një tabelë në një grup?
- Çdo nyje përshkruhet nga një identifikues që identifikon në mënyrë unike nyjen.
- Ju gjithashtu mund të shtoni një ikonë në nyje dhe të shtoni një mbishkrim.
- Ju mund të specifikoni një marrëdhënie midis dy nyjeve.
- Për komunikim në diagram, mund të vendosni ngjyrën dhe mbishkrimin.
- Drejtimi i komunikimit përcaktohet nga burimi në objektiv. Dhe burimi dhe objektivi tregohen nga identifikuesit e nyjeve.
- Një ose më shumë nyje mund të shtohen në një grup.
- Marrëdhënia gjithashtu mund të specifikohet si nga grupi ashtu edhe tek grupi.
Duke përdorur këto rregulla të thjeshta, marrim diagramin e mëposhtëm. Vetëm? Mjaft.
Dhe përshkruhet nga kodi i mëposhtëm js. Gjëja kryesore këtu është objekti i elementeve. Në të cilat tregohen nyjet - nyjet, skajet - lidhjet.
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);
Sigurisht, nuk dola vetë me vizatimin e qarkut, por përdora bibliotekën është një mjet vizualizimi shumë i fuqishëm. Unë përdor vetëm një pjesë të mundësive në zgjidhjen time.
Mirë, ky është një shembull i thjeshtë. A mund të jetë më e ndërlikuar?
Po të lutem. Për të treguar pozicionet, ne përdorim pozicionet, për të treguar grupet, ne tregojmë një listë grupesh në grupe dhe vetë elementët kanë një atribut grupi.
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>
Nga njëra anë, një skemë e tillë është pothuajse disa ekrane kodi në një laptop, nga ana tjetër, struktura a la json ju lejon të plotësoni të gjitha të dhënat me analogji, shpejt dhe mund të kopjoni-ngjisni.
Pse pozicionet vendosen veçmas nga nyjet?
Është më komode. Së pari ne specifikojmë nyjet. Pastaj ne mund të specifikojmë disa grupe dhe t'i tregojmë ato në nyje. Pastaj caktojmë lidhjet. Dhe vetëm atëherë, kur objektet kryesore dhe lidhjet midis tyre janë aty, ne marrim vendndodhjen e këtyre objekteve në diagram. Ose anasjelltas.
A është e mundur pa pozicione?
Është e mundur pa pozicione. Por do të jetë pak e thërrmuar; këtë opsion mund ta shihni në shembuj. Kjo për faktin se ekziston një algoritëm për vendndodhjen e nyjeve për cytoscape , e cila merr parasysh edhe praninë e grupeve. Specifikimi i pozicioneve e bën diagramin më të kontrollueshëm, por në fazën e hartimit të parë të diagramit është e mundur pa pozicione.
Pozicionet mund të specifikohen gjithashtu në stilin Battleship. Ato. njëra nyje ndodhet në a1 dhe tjetra në d5. Ndihmon veçanërisht që cytoscape i bën objektet në kanavacë të lëvizshme, d.m.th. ne mund t'i lëvizim ato, të shohim opsione të ndryshme të paraqitjes dhe më pas të rregullojmë renditjen e elementeve që na pëlqejnë në kod.
Në përgjithësi, është e kuptueshme. Mund të provoni gjithashtu?
Sigurisht, për të krijuar shpejt qarqe, e bëra veten të vogël , i cili vetë përditëson skemën dhe ruan versionin më të fundit në shfletues (në localStorage).
E keni provuar? Tani mund ta shtoni në faqen tuaj.
Pastaj perseri:
1. Lidhja e skenarit
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Shtoni kodin në 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. ne modifikojmë kodin në diagramin që na nevojitet (mendoj se është më e lehtë sesa të vizatoni një buf :)
Më shumë detaje në në github.
Rezultati?
I arrita qëllimet e mia - për të shtuar diagrame inline në dokumentacion, formati është mjaft i thjeshtë dhe i kuptueshëm. Nuk është i përshtatshëm për super qarqe, por për qarqe të vogla që shpjegojnë strukturën e lidhjeve, është absolutisht në rregull. Ju gjithmonë mund të ndryshoni shpejt diçka me kalimin e kohës. Po, dhe kolegët mund të korrigjojnë diçka në bankën e të akuzuarve vetë, të paktën titrat për objektet, pa trajnim të veçantë))
Çfarë mund të përmirësohet?
Këtu, natyrisht, ka shumë opsione. Shtoni ikona shtesë (të gjitha ato ekzistuese janë shtuar në linjë në skript). Zgjidhni një grup ikonash më ekspresive. Bëni të mundur specifikimin e stilit të linjës së lidhjes. Shtoni një imazh të sfondit.
Çfarë mendoni ju?
Unë tashmë kam disa ide për zbatimin në çështje, ju gjithashtu mund të shtoni tuajat në komente.
Zgjidhja ime është padyshim e zbatueshme në një gamë të ngushtë problemesh dhe ndoshta do të gjeni një mjet më të përshtatshëm për vizatimin e diagrameve thjesht duke i koduar ato - siç thonë ata 'më trego diagramin tënd si kod'
- (9 lloje të redaktuesve të grafikëve në internet)
- Dhe nëse ju pëlqejnë diagramet super të detajuara dhe komplekse, atëherë patjetër që do ta admironi këtë projekt:
Burimi: www.habr.com