In die laaste paar jaar het ek meer betrokke geraak by dokumentasie. Om 'n verduidelikende teks te skryf oor hoe 'n spesifieke stelsel werk, is oor die algemeen redelik eenvoudig. Om 'n diagram te teken wat al die sleutelobjekte en die verbindings tussen hierdie voorwerpe sal vertoon, is ook redelik maklik.
Maar die mees problematiese aspek is om hierdie dokumentasie op datum te hou. En die teks sal goed wees, maar die diagramme... Omdat... alle dokumentasie is aanlyn, m.a.w. in html-formaat, dan word die teks vergesel van gif/jpeg/png-prente, wat eintlik die diagramme wys. En diagramme word in verskeie programme soos Visio of aanlyndienste a la draw.io geteken. Dan voer jy die diagram uit na grafiese formaat en heg dit aan html. Dis eenvoudig.
Wat is die probleem?
Die skemas is gewoonlik eenvoudig. Meer presies, nie baie ingewikkeld nie. Ja, die aantal voorwerpe is 'n dosyn of twee, die aantal verbindings is ongeveer dieselfde. Plus handtekeninge, sommige benamings. Eenvoudige skemas kan in woorde beskryf word, maar te komplekse, ahem ... (c) "hulle sal nie verstaan nie, meneer." Daar is baie skemas, veranderinge moet periodiek, episodies daaraan aangebring word, m.a.w. voortdurend, want hulle volg die ontwikkeling van ons produkte.
U kan die html van die diens insluit. Het jy dit probeer?
Ja seker. Ek hou byvoorbeeld van die grafika van gliffy.com. Maar om veranderinge aan te bring, moet jy na 'n derdeparty-diens gaan en daar wysig. En dit is moeiliker om regstellings aan 'n kollega te delegeer.
Wat om te doen?
Ek het onlangs 'n bewaarplek op Github in die aanbevelings afgekom . Diagram as kode. Dié. ons beskryf die stroombaan wat ons benodig in js. Ons skryf hierdie js direk in dieselfde html waar die ander dokumentasie teks is.
Terloops, ek skryf dokumentasie nie heeltemal in html nie. Tipies is dokumentasie 'n stel lêers met afmerkteks, wat dan deur een of ander enjin, byvoorbeeld wintersmith, in 'n volwaardige dokumentasiewebwerf omgeskakel word. Of 'n wiki-stelsel.
Dit blyk baie gerieflik: ons het die teks geskryf, dan word die script tag oop en die JS-kode van die skema word daarin beskryf.
Wat is nou weer fout?
Ek het van hierdie bewaarplek gehou, maar dit is nie die enigste voorbeeld waar 'n diagram met kode of 'n teksvoorstelling geteken word nie. (Aan die einde van die artikel sal daar skakels wees na projekte en artikels wat ek oor die onderwerpdiagram as kode gegoogle het.)
En ek is nie die enigste een wat die dokumentasie redigeer nie. Soms dra kollegas ook by - korrigeer 'n woord, verander 'n beskrywing, voeg nuwe prentjies in.
Daarom wil ek graag die diagram in 'n leesbare, verstaanbare teksformaat sien wat nie 'n lang leerkurwe sal vereis nie. En op sommige plekke kan jy selfs net kopieer-plak om die byvoeging van 'n nuwe stroombaan te bespoedig.
En 'n ander kollega het opgemerk dat kode natuurlik goed is, maar as jy struktuur gebruik, kan alles baie streng en ekspressief wees.
Daarom het ek probeer om die diagram voor te stel as 'n stel van verskeie klein skikkings wat nodusse, verbindings, groepe nodusse, sowel as die ligging van nodusse beskryf. Dit blyk, na my beskeie mening, redelik gerieflik, hoewel die smaak en kleur natuurlik ...
Hoe is dit 'n grafiek in 'n skikking?
- Elke nodus word beskryf deur 'n identifiseerder wat die nodus uniek identifiseer.
- Jy kan ook 'n ikoon by die nodus voeg en 'n inskripsie byvoeg.
- Jy kan 'n verhouding tussen twee nodusse spesifiseer.
- Vir kommunikasie op die diagram, kan jy die kleur en inskripsie stel.
- Die rigting van kommunikasie word gedefinieer as van bron tot teiken. En die bron en teiken word deur nodusidentifiseerders aangedui.
- Een of meer nodusse kan by 'n groep gevoeg word.
- Die verhouding kan ook gespesifiseer word vanaf die groep en na die groep.
Deur hierdie eenvoudige reëls te gebruik, kry ons die volgende diagram. Net? Nogal.
En dit word beskryf deur die volgende js-kode. Die belangrikste ding hier is die elemente voorwerp. Waarin nodusse aangedui word - nodusse, rande - verbindings.
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);
Ek het natuurlik nie self met die tekening van die kring vorendag gekom nie, maar het die biblioteek gebruik is 'n baie kragtige visualiseringsinstrument. Ek gebruik net 'n fraksie van die moontlikhede in my oplossing.
Goed, dit is 'n eenvoudige voorbeeld. Kan dit meer ingewikkeld wees?
Ja asseblief. Om posisies aan te dui, gebruik ons posisies, om groepe aan te dui, dui ons 'n lys groepe in groepe aan, en die elemente self het 'n groepeienskap.
En dit is die kode:
<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>
Aan die een kant is so 'n skema amper 'n paar skerms kode op 'n skootrekenaar, aan die ander kant laat die struktuur a la json jou toe om al die data na analogie vinnig in te vul en jy kan kopieer-plak.
Waarom word posisies apart van nodusse geplaas?
Dit is gemakliker. Eerstens spesifiseer ons nodusse. Dan kan ons 'n paar groepe spesifiseer en hulle in nodusse aandui. Dan wys ons die verbindings aan. En eers dan, wanneer die hoofvoorwerpe en verbindings tussen hulle daar is, neem ons die ligging van hierdie voorwerpe op die diagram aan. Of andersom.
Is dit moontlik sonder posisies?
Dit is moontlik sonder posisies. Maar dit sal 'n bietjie verfrommel wees; jy kan hierdie opsie in die voorbeelde sien. Dit is te wyte aan die feit dat daar 'n algoritme is vir die ligging van nodusse vir sitoskap , wat ook die teenwoordigheid van groepe in ag neem. Die spesifikasie van posisies maak die diagram meer beheerbaar, maar in die stadium van die eerste konsep van die diagram is dit moontlik sonder posisies.
Posisies kan ook in die Battleship-styl gespesifiseer word. Dié. een nodus is geleë in a1, en die ander in d5. Dit help veral dat sitoskap die voorwerpe op die doek beweegbaar maak, m.a.w. ons kan hulle rondskuif, verskillende uitlegopsies sien en dan die rangskikking van die elemente waarvan ons hou in die kode regmaak.
Oor die algemeen is dit verstaanbaar. Jy kan ook probeer?
Natuurlik, om vinnig stroombane te skep, het ek myself 'n klein gemaak , wat self die skema opdateer en die nuutste weergawe in die blaaier stoor (in localStorage).
Het jy dit probeer? Jy kan dit nou by jou bladsy voeg.
Dan weer:
1. Verbind die skrif
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Voeg kode by 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. ons wysig die kode na die diagram wat ons nodig het (ek dink dit is makliker as om 'n uil te teken :)
Meer besonderhede by op github.
Die resultaat?
Ek het my doelwitte bereik - om inlyndiagramme by die dokumentasie te voeg, die formaat is redelik eenvoudig en verstaanbaar. Dit is nie geskik vir superstroombane nie, maar vir klein stroombane wat die struktuur van verbindings verduidelik, is dit absoluut goed. Jy kan altyd iets mettertyd vinnig aanpas en verander. Ja, en kollegas kan self iets in die beskuldigdebank regstel, ten minste byskrifte vir voorwerpe, sonder spesiale opleiding))
Wat kan verbeter word?
Hier is natuurlik baie opsies. Voeg bykomende ikone by (alle bestaande word inlyn by die skrif gevoeg). Kies 'n meer ekspressiewe stel ikone. Maak dit moontlik om die styl van die verbindingslyn te spesifiseer. Voeg 'n agtergrondprent by.
Wat dink jy?
Ek het reeds verskeie idees vir implementering in kwessies, jy kan joune ook byvoeg in die kommentaar.
My oplossing is beslis van toepassing in 'n nou reeks probleme, en miskien sal jy 'n geriefliker hulpmiddel vind om diagramme te teken deur dit eenvoudig te kodeer - soos hulle sê 'wys my jou diagram as kode'
- (9 tipes kaarte aanlyn redakteur)
- En as jy van super gedetailleerde en komplekse diagramme hou, sal jy beslis hierdie projek bewonder:
Bron: will.com