De siste par årene har jeg engasjert meg mer i dokumentasjon. Å skrive en forklarende tekst om hvordan et bestemt system fungerer er generelt ganske enkelt. Å tegne et diagram som viser alle nøkkelobjektene og forbindelsene mellom disse objektene er også ganske enkelt.
Men det mest problematiske aspektet er å holde denne dokumentasjonen oppdatert. Og teksten ville vært fin, men diagrammene... Fordi... all dokumentasjon ligger på nett, dvs. i html-format, så er teksten ledsaget av gif/jpeg/png-bilder, som faktisk viser diagrammene. Og diagrammer tegnes i ulike programmer som Visio eller nettjenester a la draw.io. Deretter eksporterer du diagrammet til grafisk format og legger det ved html. Det er enkelt.
Hva er problemet?
Ordningene er vanligvis enkle. Mer presist, ikke veldig komplisert. Ja, antall objekter er et dusin eller to, antall tilkoblinger er omtrent det samme. Pluss signaturer, noen betegnelser. Enkle opplegg kan beskrives med ord, men for komplekse, ahem... (c) "de vil ikke forstå, sir." Det er mange ordninger, endringer må gjøres i dem med jevne mellomrom, episodisk, dvs. hele tiden, fordi de følger utviklingen av produktene våre.
Du kan bygge inn html-en til tjenesten. Har du prøvd det?
Ja sikkert. For eksempel liker jeg grafikken fra gliffy.com. Men for å gjøre endringer, må du gå til en tredjepartstjeneste og redigere der. Og det er vanskeligere å delegere rettelser til en kollega.
Hva gjør jeg?
Nylig kom jeg over et depot på Github i anbefalingene . Diagram som kode. De. vi beskriver kretsen vi trenger i js. Vi skriver denne js direkte i samme html der den andre dokumentasjonsteksten er.
Jeg skriver forresten dokumentasjon ikke helt i html. Vanligvis er dokumentasjon et sett med filer med markdown-tekst, som deretter konverteres til en fullverdig dokumentasjonsside av en eller annen motor, for eksempel wintersmith. Eller et wiki-system.
Det viser seg veldig praktisk: vi har skrevet teksten, så åpnes skriptkoden og JS-koden til ordningen er beskrevet i den.
Hva er galt igjen?
Jeg likte dette depotet, men dette er ikke det eneste eksemplet der et diagram er tegnet ved hjelp av kode eller en tekstrepresentasjon. (På slutten av artikkelen vil det være lenker til prosjekter og artikler som jeg googlet om emnediagrammet som kode.)
Og jeg er ikke den eneste som redigerer dokumentasjonen. Noen ganger bidrar også kollegaer – rett et ord, endre en beskrivelse, sett inn nye bilder.
Derfor vil jeg gjerne se diagrammet i et lesbart, forståelig tekstformat som ikke krever en lang læringskurve. Og noen steder kan du til og med ganske enkelt kopiere og lime inn for å øke hastigheten på å legge til en ny krets.
Og en annen kollega bemerket at kode selvfølgelig er bra, men hvis du bruker struktur, kan alt være veldig strengt og uttrykksfullt.
Derfor prøvde jeg å forestille meg diagrammet som et sett med flere små arrays som beskriver noder, forbindelser, grupper av noder, samt plasseringen av noder. Det viste seg, etter min ydmyke mening, ganske praktisk, selv om selvfølgelig smaken og fargen ...
Hvordan er dette et diagram i en matrise?
- Hver node er beskrevet av en identifikator som unikt identifiserer noden.
- Du kan også legge til et ikon til noden og legge til en inskripsjon.
- Du kan spesifisere et forhold mellom to noder.
- For kommunikasjon på diagrammet kan du angi farge og inskripsjon.
- Kommunikasjonsretningen er definert som fra kilde til mål. Og kilden og målet er indikert med nodeidentifikatorer.
- En eller flere noder kan legges til en gruppe.
- Relasjonen kan også spesifiseres både fra gruppen og til gruppen.
Ved å bruke disse enkle reglene får vi følgende diagram. Bare? Ganske.
Og det er beskrevet av følgende js-kode. Det viktigste her er elementobjektet. I hvilke noder er indikert - noder, kanter - forbindelser.
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);
Selvfølgelig kom jeg ikke opp med tegningen av kretsen selv, men brukte biblioteket er et veldig kraftig visualiseringsverktøy. Jeg bruker bare en brøkdel av mulighetene i min løsning.
Ok, dette er et enkelt eksempel. Kan det være mer komplisert?
Ja takk. For å indikere posisjoner bruker vi posisjoner, for å indikere grupper angir vi en liste over grupper i grupper, og selve elementene har et gruppeattributt.
Og dette er koden:
<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>
På den ene siden er et slikt opplegg nesten et par skjermer med kode på en bærbar datamaskin, på den annen side lar strukturen a la json deg fylle ut alle dataene analogt, raskt og du kan kopiere og lime inn.
Hvorfor plasseres posisjoner separat fra noder?
Det er mer behagelig. Først spesifiserer vi noder. Deretter kan vi spesifisere et par grupper og indikere dem i noder. Deretter utpeker vi forbindelsene. Og først da, når hovedobjektene og forbindelsene mellom dem er der, tar vi på oss plasseringen av disse objektene på diagrammet. Eller vice versa.
Er det mulig uten stillinger?
Det er mulig uten stillinger. Men det vil være litt krøllete; du kan se dette alternativet i eksemplene. Dette skyldes det faktum at det er en algoritme for plassering av noder for cytoscape , som også tar hensyn til tilstedeværelsen av grupper. Å spesifisere posisjoner gjør diagrammet mer kontrollerbart, men på stadiet av det første utkastet av diagrammet er det mulig uten posisjoner.
Posisjoner kan også spesifiseres i Battleship-stilen. De. en node er plassert i a1, og den andre i d5. Det hjelper spesielt at cytoscape gjør objektene på lerretet bevegelige, d.v.s. vi kan flytte dem rundt, se forskjellige layoutalternativer, og deretter fikse arrangementet av elementene vi liker i koden.
Generelt sett er det forståelig. Kan du også prøve?
Selvfølgelig, for raskt å lage kretser, laget jeg meg en liten , som selv oppdaterer skjemaet og lagrer den nyeste versjonen i nettleseren (i localStorage).
Har du prøvd det? Du kan nå legge den til på siden din.
Så igjen:
1. Koble til skriptet
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Legg til kode i 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. vi redigerer koden til diagrammet vi trenger (jeg tror det er enklere enn å tegne en ugle :)
Flere detaljer på på github.
Resultatet?
Jeg oppnådde målene mine - å legge til inline diagrammer i dokumentasjonen, formatet er ganske enkelt og forståelig. Det er ikke egnet for superkretser, men for små kretser som forklarer strukturen til tilkoblinger, er det helt greit. Du kan alltid raskt justere og endre noe over tid. Ja, og kolleger kan selv rette opp noe i kaien, i det minste bildetekster for objekter, uten spesiell opplæring))
Hva kan forbedres?
Det er selvfølgelig mange alternativer her. Legg til flere ikoner (alle eksisterende legges til i skriptet). Velg et mer uttrykksfullt sett med ikoner. Gjør det mulig å spesifisere stilen til tilkoblingslinjen. Legg til et bakgrunnsbilde.
Hva tror du?
Jeg har allerede flere ideer for implementering i saker, du kan også legge til dine i kommentarene.
Løsningen min er definitivt anvendelig i et smalt spekter av problemer, og kanskje vil du finne et mer praktisk verktøy for å tegne diagrammer ved ganske enkelt å kode dem - som de sier "vis meg diagrammet ditt som kode"
- (9 typer diagrammer online editor)
- Og hvis du liker superdetaljerte og komplekse diagrammer, vil du definitivt beundre dette prosjektet:
Kilde: www.habr.com