Viimase paari aasta jooksul olen hakanud rohkem tegelema dokumenteerimisega. Konkreetse süsteemi toimimise kohta selgitava teksti kirjutamine on üldiselt üsna lihtne. Samuti on üsna lihtne joonistada diagrammi, mis kuvab kõik võtmeobjektid ja nende objektidevahelised ühendused.
Kuid kõige problemaatilisem aspekt on selle dokumentatsiooni ajakohastamine. Ja tekst oleks hea, aga diagrammid... Sest... kogu dokumentatsioon on võrgus, st. html formaadis, siis on tekstiga kaasas gif/jpeg/png pildid, mis reaalselt näitavad diagramme. Ja diagramme joonistatakse erinevates programmides, nagu Visio või võrguteenused a la draw.io. Seejärel ekspordite diagrammi graafilisse vormingusse ja lisate selle html-i. See on lihtne.
Milles on probleem?
Skeemid on tavaliselt lihtsad. Täpsemalt, mitte väga keeruline. Jah, objekte on kümmekond või kaks, ühenduste arv on ligikaudu sama. Pluss allkirjad, mõned nimetused. Lihtsaid skeeme võib sõnadega kirjeldada, aga liiga keerulisi, ah... (c) "nad ei saa aru, söör." Skeeme on palju, neis tuleb muudatusi teha perioodiliselt, episoodiliselt, s.t. pidevalt, sest nad jälgivad meie toodete arengut.
Saate manustada teenuse html-i. Kas olete seda proovinud?
Jah muidugi. Näiteks meeldib mulle gliffy.com-i graafika. Kuid muudatuste tegemiseks peate minema kolmanda osapoole teenusesse ja muutma seal. Ja paranduste delegeerimine kolleegile on keerulisem.
Mida teha?
Hiljuti leidsin soovitustes Githubi hoidla . Diagramm koodina. Need. kirjeldame vajalikku vooluringi js-s. Kirjutame selle js-i otse samasse html-i, kus on muu dokumentatsiooni tekst.
Muide, ma ei kirjuta dokumentatsiooni täielikult html-is. Tavaliselt on dokumentatsioon allahindlustekstiga failide komplekt, mille seejärel mõni mootor, näiteks Winsmith, teisendab täisväärtuslikuks dokumentatsiooni saidiks. Või wiki süsteem.
See osutub väga mugavaks: oleme teksti kirjutanud, seejärel avaneb skripti silt ja selles kirjeldatakse skeemi JS-koodi.
Mis jälle lahti?
Mulle meeldis see hoidla, kuid see pole ainus näide, kus diagramm on koostatud koodi või teksti esituse abil. (Artikli lõpus on lingid projektidele ja artiklitele, mida ma teemaskeemil koodina googeldasin.)
Ja ma pole ainus, kes dokumente toimetab. Vahel panustavad ka kolleegid - paranda sõna, muuda kirjeldust, lisa uusi pilte.
Seetõttu sooviksin näha diagrammi loetavas, arusaadavas tekstivormingus, mis ei nõuaks pikka õppimiskõverat. Mõnes kohas saate uue vooluahela lisamise kiirendamiseks isegi lihtsalt kopeerida-kleepida.
Ja teine kolleeg märkis, et kood on muidugi hea, aga kui kasutada struktuuri, võib kõik olla väga range ja väljendusrikas.
Seetõttu püüdsin kujutada diagrammi mitme väikese massiivi kogumina, mis kirjeldavad sõlme, ühendusi, sõlmede rühmi ja ka sõlmede asukohta. See osutus minu tagasihoidliku hinnangu kohaselt üsna mugavaks, kuigi muidugi maitse ja värv...
Kuidas see diagramm massiivis on?
- Iga sõlme kirjeldab identifikaator, mis sõlme üheselt identifitseerib.
- Samuti saate sõlmele lisada ikooni ja lisada pealdise.
- Saate määrata seose kahe sõlme vahel.
- Diagrammil suhtlemiseks saate määrata värvi ja pealdise.
- Kommunikatsiooni suund on määratletud allikast sihtmärgini. Ja allikat ja sihtmärki tähistavad sõlme identifikaatorid.
- Rühma saab lisada ühe või mitu sõlme.
- Samuti saab suhet määrata nii grupist kui ka grupist.
Neid lihtsaid reegleid kasutades saame järgmise diagrammi. Lihtsalt? Päris.
Ja seda kirjeldab järgmine js-kood. Peamine on siin elementide objekt. Milles on näidatud sõlmed - sõlmed, servad - ühendused.
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);
Muidugi ei mõelnud ma ise vooluringi joonist välja, vaid kasutasin raamatukogu on väga võimas visualiseerimistööriist. Kasutan oma lahenduses vaid murdosa võimalustest.
Olgu, see on lihtne näide. Kas see võib olla keerulisem?
Jah palun. Positsioonide tähistamiseks kasutame positsioone, rühmade märkimiseks tähistame rühmade loendit ja elementidel endil on grupi atribuut.
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>
Ühest küljest on selline skeem peaaegu paar ekraani koodi sülearvutis, teisest küljest võimaldab struktuur a la json täita kõik andmed analoogia põhjal, kiiresti ja saate kopeerida-kleepida.
Miks paigutatakse positsioonid sõlmedest eraldi?
See on mugavam. Kõigepealt määrame sõlmed. Seejärel saame määrata paar rühma ja märkida need sõlmedesse. Seejärel määrame ühendused. Ja alles siis, kui peamised objektid ja nendevahelised ühendused on olemas, võtame diagrammil nende objektide asukoha. Või vastupidi.
Kas ilma positsioonideta on võimalik?
See on võimalik ilma positsioonideta. Kuid see on veidi kortsus; seda valikut näete näidetes. See on tingitud asjaolust, et tsütomaastiku jaoks on olemas algoritm sõlmede asukoha määramiseks , mis võtab arvesse ka rühmade olemasolu. Positsioonide määramine muudab diagrammi paremini juhitavaks, kuid diagrammi esimese mustandi staadiumis on võimalik ilma positsioonideta.
Positsioone saab määrata ka lahingulaeva stiilis. Need. üks sõlm asub punktis a1 ja teine sõlmpunktis d5. Eriti aitab see, et cytoscape muudab lõuendil olevad objektid liigutatavaks, s.t. saame neid liigutada, näha erinevaid paigutusvalikuid ja seejärel parandada meile meeldivate elementide paigutust koodis.
Üldiselt on see arusaadav. Kas sa saad ka proovida?
Muidugi, et kiiresti luua ahelaid, tegin endale väikese , mis ise värskendab skeemi ja salvestab brauserisse uusima versiooni (kohalikus salvestusruumis).
Kas olete seda proovinud? Nüüd saate selle oma lehele lisada.
Siis jälle:
1. Skripti ühendamine
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Lisage kood html-ile
<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 vajaliku diagrammi järgi (ma arvan, et see on lihtsam kui öökulli joonistamine :)
Täpsemalt aadressil githubis.
Ja tulemus?
Täitsin oma eesmärgid - lisada dokumentatsioonile inline diagrammid, formaat on üsna lihtne ja arusaadav. See ei sobi superahelate jaoks, kuid väikeste vooluahelate jaoks, mis selgitavad ühenduste struktuuri, on see täiesti korras. Saate alati kiiresti midagi aja jooksul kohandada ja muuta. Jah, ja kolleegid saavad dokis ise midagi parandada, vähemalt objektide pealdisi, ilma eriväljaõppeta))
Mida saab parandada?
Siin on muidugi palju võimalusi. Lisage täiendavaid ikoone (kõik olemasolevad lisatakse skripti sisse). Valige väljendusrikkam ikoonide komplekt. Võimaldab määrata ühendusliini stiili. Lisage taustpilt.
Mida sa arvad?
Mul on juba mitu ideed numbrites elluviimiseks, võite lisada ka oma kommentaaridesse.
Minu lahendus on kindlasti rakendatav kitsastes probleemides ja võib-olla leiate diagrammide joonistamiseks mugavama tööriista need lihtsalt kodeerides - nagu öeldakse "näita mulle oma diagrammi koodina".
- (9 tüüpi graafikute veebiredaktor)
- Ja kui teile meeldivad väga üksikasjalikud ja keerulised diagrammid, siis imetlete seda projekti kindlasti:
Allikas: www.habr.com