Fl-aħħar ftit snin sirt aktar involut fid-dokumentazzjoni. Il-kitba ta' test ta' spjegazzjoni dwar kif taħdem din jew dik is-sistema ġeneralment hija pjuttost sempliċi. Tpinġija ta 'dijagramma li se turi l-oġġetti ewlenin kollha u l-konnessjonijiet bejn dawn l-oġġetti huwa wkoll pjuttost faċli.
Iżda l-aktar aspett problematiku huwa li żżomm din id-dokumentazzjoni aġġornata. U t-test ikun tajjeb, imma d-dijagrammi... Għax... id-dokumentazzjoni kollha hija online, i.e. f'format html, allura t-test ikun akkumpanjat minn stampi gif/jpeg/png, li fil-fatt juru d-dijagrammi. U dijagrammi huma mfassla f'diversi programmi bħal Visio jew servizzi online a la draw.io. Imbagħad tesporta d-dijagramma f'format grafiku u tehmeżha ma 'html. Huwa sempliċi.
X'inhi l-problema?
L-iskemi huma ġeneralment sempliċi. B'mod aktar preċiż, mhux ikkumplikat ħafna. Iva, in-numru ta 'oġġetti huwa tużżana jew tnejn, in-numru ta' konnessjonijiet huwa bejn wieħed u ieħor l-istess. Flimkien ma' firem, xi nominazzjonijiet. Skemi sempliċi jistgħu jiġu deskritti bil-kliem, iżda kumplessi wisq, ahem... (ċ) "mhux se jifhmu, sir." Hemm ħafna skemi, jeħtieġ li jsiru bidliet perjodikament, episodikament, i.e. kontinwament, għaliex huma jsegwu l-iżvilupp tal-prodotti tagħna.
Tista' tintegra l-html tas-servizz. Ippruvajtu?
Iva, żgur. Per eżempju, jogħġobni l-grafika minn gliffy.com. Iżda biex tagħmel bidliet, trid tmur f'servizz ta 'parti terza u teditja hemmhekk. U huwa aktar diffiċli li tiddelega korrezzjonijiet lil kollega.
X'għandek tagħmel?
Riċentement iltqajt ma' repożitorju fuq Github fir-rakkomandazzjonijiet . Dijagramma bħala kodiċi. Dawk. aħna niddeskrivu ċ-ċirkwit li għandna bżonn f'js. Aħna niktbu dan js direttament fl-istess html fejn it-test tad-dokumentazzjoni l-ieħor huwa.
Mill-mod, nikteb dokumentazzjoni mhux kompletament f'html. Tipikament, id-dokumentazzjoni hija sett ta 'fajls b'test markdown, li mbagħad jiġi kkonvertit f'sit ta' dokumentazzjoni sħiħ minn xi magna, pereżempju wintersmith. Jew sistema wiki.
Jirriżulta konvenjenti ħafna: ktibna t-test, imbagħad it-tikketta tal-iskrittura tiftaħ u l-kodiċi JS tal-iskema huwa deskritt fiha.
X'hemm ħażin mill-ġdid?
Għoġobni dan ir-repożitorju, iżda dan mhuwiex l-uniku eżempju fejn dijagramma hija mfassla bl-użu ta 'kodiċi jew rappreżentazzjoni ta' test. (Fl-aħħar tal-artiklu se jkun hemm links għal proġetti u artikoli li għidt fuq Google fuq id-dijagramma tas-suġġett bħala kodiċi.)
U jien mhux l-uniku wieħed li jeditja d-dokumentazzjoni. Xi drabi l-kollegi jikkontribwixxu wkoll - jikkoreġu kelma, ibiddlu deskrizzjoni, daħħal stampi ġodda.
Għalhekk, nixtieq nara d-dijagramma f'format ta 'test li jinqara u li jinftiehem li ma jkunx jeħtieġ kurva twila ta' tagħlim. U f'xi postijiet tista 'saħansitra sempliċement tikkopja-pejst biex tħaffef iż-żieda ta' ċirkwit ġdid.
U kollega ieħor innota li l-kodiċi huwa, ovvjament, tajjeb, imma jekk tuża l-istruttura, kollox jista 'jkun strett ħafna u espressiv.
Għalhekk, ippruvajt nimmaġina d-dijagramma bħala sett ta 'diversi arrays żgħar li jiddeskrivu nodi, konnessjonijiet, gruppi ta' nodi, kif ukoll il-post tan-nodi. Irriżulta, fl-opinjoni umli tiegħi, pjuttost konvenjenti, għalkemm, ovvjament, it-togħma u l-kulur...
Kif din hija chart f'firxa?
- Kull nodu huwa deskritt minn identifikatur li jidentifika b'mod uniku n-nodu.
- Tista 'wkoll iżżid ikona man-node u żżid iskrizzjoni.
- Tista' tispeċifika relazzjoni bejn żewġ nodi.
- Għall-komunikazzjoni fuq id-dijagramma, tista 'tissettja l-kulur u l-iskrizzjoni.
- Id-direzzjoni tal-komunikazzjoni hija definita bħala mis-sors għall-mira. U s-sors u l-mira huma indikati minn identifikaturi tan-nodi.
- Nodu wieħed jew aktar jistgħu jiġu miżjuda ma 'grupp.
- Ir-relazzjoni tista' tiġi speċifikata wkoll kemm mill-grupp kif ukoll mal-grupp.
Bl-użu ta 'dawn ir-regoli sempliċi, aħna tikseb id-dijagramma li ġejja. Biss? Pjuttost.
U huwa deskritt mill-kodiċi js li ġej. Il-ħaġa prinċipali hawnhekk hija l-oġġett tal-elementi. F'liema nodi huma indikati - nodi, truf - konnessjonijiet.
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);
Naturalment, jien ma ħriġtx bit-tpinġija taċ-ċirkwit, imma użajt il-librerija hija għodda ta 'viżwalizzazzjoni qawwija ħafna. Jiena nuża biss frazzjoni tal-possibilitajiet fis-soluzzjoni tiegħi.
Okay, dan huwa eżempju sempliċi. Jista 'jkun aktar ikkumplikat?
Iva jekk jogħġbok. Biex tindika pożizzjonijiet, nużaw pożizzjonijiet, biex nindikaw gruppi, aħna nindikaw lista ta 'gruppi fi gruppi, u l-elementi nfushom għandhom attribut ta' grupp.
U dan huwa l-kodiċi:
<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>
Min-naħa waħda, skema bħal din hija kważi ftit skrins ta 'kodiċi fuq laptop, min-naħa l-oħra, l-istruttura a la json tippermettilek timla d-dejta kollha b'analoġija, malajr u tista' tikkopja-pejst.
Għaliex il-pożizzjonijiet jitqiegħdu separatament min-nodi?
Huwa aktar komdu. L-ewwel aħna nispeċifikaw nodi. Imbagħad nistgħu nispeċifikaw ftit gruppi u nindikawhom f'nodi. Imbagħad aħna nnominaw il-konnessjonijiet. U mbagħad biss, meta l-oġġetti ewlenin u l-konnessjonijiet bejniethom ikunu hemm, nieħdu l-post ta 'dawn l-oġġetti fuq id-dijagramma. Jew viċi versa.
Huwa possibbli mingħajr pożizzjonijiet?
Huwa possibbli mingħajr pożizzjonijiet. Iżda se jkun ftit imkemmex; tista 'tara din l-għażla fl-eżempji. Dan huwa dovut għall-fatt li hemm algoritmu għall-post tan-nodi għal cytoscape , li tqis ukoll il-preżenza ta' gruppi. L-ispeċifikazzjoni tal-pożizzjonijiet tagħmel id-dijagramma aktar kontrollabbli, iżda fl-istadju tal-ewwel abbozz tad-dijagramma huwa possibbli mingħajr pożizzjonijiet.
Il-pożizzjonijiet jistgħu jiġu speċifikati wkoll fl-istil Battleship. Dawk. nodu wieħed jinsab f'a1, u l-ieħor f'd5. Jgħin speċjalment li cytoscape jagħmel l-oġġetti fuq il-kanvas mobbli, i.e. nistgħu nimxu madwarhom, naraw għażliet ta 'tqassim differenti, u mbagħad niffissaw l-arranġament tal-elementi li nħobbu fil-kodiċi.
B'mod ġenerali, jinftiehem. Tista' wkoll tipprova?
Naturalment, biex malajr noħolqu ċirkwiti, għamilt lili nnifsi żgħir , li huwa stess jaġġorna l-iskema u jaħżen l-aħħar verżjoni fil-browser (f'localStorage).
Ippruvajtu? Issa tista 'żżidha mal-paġna tiegħek.
Imbagħad għal darb'oħra:
1. Tqabbad l-iskrittura
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Żid il-kodiċi mal-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. aħna neditjaw il-kodiċi għad-dijagramma li għandna bżonn (naħseb li huwa aktar faċli milli tpinġi kokka :)
Aktar dettalji fuq fuq github.
Ir-riżultat?
Ksibt l-għanijiet tiegħi - biex inżid dijagrammi inline mad-dokumentazzjoni, il-format huwa pjuttost sempliċi u jinftiehem. Mhuwiex adattat għal ċirkwiti super, iżda għal ċirkwiti żgħar li jispjegaw l-istruttura tal-konnessjonijiet, huwa assolutament tajjeb. Inti tista 'dejjem malajr tweak u tibdel xi ħaġa maż-żmien. Iva, u l-kollegi jistgħu jikkoreġu xi ħaġa fil-baċir huma stess, għall-inqas captions għal oġġetti, mingħajr taħriġ speċjali))
X'jista' jittejjeb?
Hemm, ovvjament, ħafna għażliet hawn. Żid ikoni addizzjonali (dawk kollha eżistenti huma miżjuda inline mal-iskript). Agħżel sett aktar espressiv ta 'ikoni. Agħmel possibbli li jiġi speċifikat l-istil tal-linja tal-konnessjoni. Żid immaġni fl-isfond.
X'taħseb?
Diġà għandi diversi ideat għall-implimentazzjoni fi kwistjonijiet, tista 'wkoll iżżid tiegħek fil-kummenti.
Is-soluzzjoni tiegħi hija definittivament applikabbli f'firxa dejqa ta' problemi, u forsi ssib għodda aktar konvenjenti biex tfassal dijagrammi billi sempliċement tikkodifikahom - kif jgħidu 'urini d-dijagramma tiegħek bħala kodiċi'
- (9 tipi ta' editur onlajn ta' charts)
- U jekk tixtieq dijagrammi super dettaljati u kumplessi, allura żgur li tammira dan il-proġett:
Sors: www.habr.com