În ultimii doi ani m-am implicat mai mult în documentare. Scrierea unui text explicativ despre cum funcționează un anumit sistem este, în general, destul de simplă. Desenarea unei diagrame care va afișa toate obiectele cheie și conexiunile dintre aceste obiecte este, de asemenea, destul de ușoară.
Dar cel mai problematic aspect este păstrarea la zi a acestei documentații. Și textul ar fi bine, dar diagramele... Pentru că... toată documentația este online, adică în format html, apoi textul este însoțit de imagini gif/jpeg/png, care arată de fapt diagramele. Și diagramele sunt desenate în diverse programe precum Visio sau servicii online a la draw.io. Apoi exportați diagrama în format grafic și o atașați la html. E simplu.
Care este problema?
Schemele sunt de obicei simple. Mai exact, nu foarte complicat. Da, numărul de obiecte este de o duzină sau două, numărul de conexiuni este aproximativ același. Plus semnături, câteva desemnări. Schemele simple pot fi descrise în cuvinte, dar cele prea complexe, ahem... (c) „nu vor înțelege, domnule”. Există multe scheme, trebuie făcute modificări periodice, episodice, adică. în mod constant, pentru că ele urmăresc dezvoltarea produselor noastre.
Puteți încorpora codul html al serviciului. Ai încercat?
Da sigur. De exemplu, îmi place grafica de la gliffy.com. Dar pentru a face modificări, trebuie să accesați un serviciu terță parte și să editați acolo. Și este mai dificil să delegați corecțiile unui coleg.
Ce să fac?
Recent am dat peste un depozit pe Github în recomandări . Diagrama ca cod. Acestea. descriem circuitul de care avem nevoie în js. Scriem acest js direct în același html în care se află celălalt text de documentație.
Apropo, eu scriu documentația nu în întregime în html. De obicei, documentația este un set de fișiere cu text de reducere, care este apoi convertit într-un site de documentare cu drepturi depline de către un motor, de exemplu Wintersmith. Sau un sistem wiki.
Se dovedește foarte convenabil: am scris textul, apoi se deschide eticheta de script și codul JS al schemei este descris în ea.
Ce sa întâmplat din nou?
Mi-a plăcut acest depozit, dar acesta nu este singurul exemplu în care o diagramă este desenată folosind cod sau o reprezentare text. (La sfârșitul articolului vor exista link-uri către proiecte și articole pe care le-am căutat pe Google pe diagrama subiectului ca cod.)
Și nu sunt singurul care editează documentația. Uneori contribuie și colegii - corectați un cuvânt, schimbați o descriere, introduceți imagini noi.
Prin urmare, aș dori să văd diagrama într-un format text ușor de citit și de înțeles, care nu ar necesita o curbă lungă de învățare. Și în unele locuri puteți chiar pur și simplu să copiați și lipiți pentru a accelera adăugarea unui circuit nou.
Și un alt coleg a remarcat că codul este, desigur, bun, dar dacă folosești structura, totul poate fi foarte strict și expresiv.
Prin urmare, am încercat să-mi imaginez diagrama ca un set de mai multe matrice mici care descriu noduri, conexiuni, grupuri de noduri, precum și locația nodurilor. S-a dovedit, după umila mea părere, destul de convenabil, deși, desigur, gustul și culoarea...
Cum este aceasta o diagramă într-o matrice?
- Fiecare nod este descris de un identificator care identifică unic nodul.
- De asemenea, puteți adăuga o pictogramă la nod și puteți adăuga o inscripție.
- Puteți specifica o relație între două noduri.
- Pentru comunicarea pe diagramă, puteți seta culoarea și inscripția.
- Direcția de comunicare este definită ca de la sursă la țintă. Și sursa și ținta sunt indicate prin identificatorii de nod.
- Unul sau mai multe noduri pot fi adăugate unui grup.
- Relația poate fi de asemenea specificată atât de la grup, cât și de la grup.
Folosind aceste reguli simple, obținem următoarea diagramă. Doar? Destul de.
Și este descris de următorul cod js. Principalul lucru aici este obiectul elementelor. În care sunt indicate noduri - noduri, margini - conexiuni.
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);
Bineînțeles, nu am venit eu cu desenul circuitului, ci am folosit biblioteca este un instrument de vizualizare foarte puternic. Folosesc doar o fracțiune din posibilitățile din soluția mea.
Bine, acesta este un exemplu simplu. Poate fi mai complicat?
Da, te rog. Pentru a indica poziții, folosim poziții, pentru a indica grupuri, indicăm o listă de grupuri în grupuri, iar elementele în sine au un atribut de grup.
Și acesta este codul:
<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>
Pe de o parte, o astfel de schemă este aproape câteva ecrane de cod pe un laptop, pe de altă parte, structura a la json vă permite să completați toate datele prin analogie, rapid și să puteți copia și lipi.
De ce pozițiile sunt plasate separat de noduri?
Este mai confortabil. Mai întâi specificăm nodurile. Apoi putem specifica câteva grupuri și le putem indica în noduri. Apoi desemnăm conexiunile. Și numai atunci, când principalele obiecte și conexiunile dintre ele sunt acolo, luăm locația acestor obiecte pe diagramă. Sau vice versa.
Este posibil fără posturi?
Este posibil fără posturi. Dar va fi puțin mototolită; puteți vedea această opțiune în exemple. Acest lucru se datorează faptului că există un algoritm pentru localizarea nodurilor pentru cytoscape , care ține cont și de prezența grupurilor. Specificarea pozițiilor face diagrama mai controlabilă, dar în etapa primei schițe a diagramei este posibil fără poziții.
Pozițiile pot fi specificate și în stilul Battleship. Acestea. un nod este situat în a1, iar celălalt în d5. Ajută în special faptul că cytoscape face obiectele de pe pânză mobile, adică. le putem muta, vedea diferite opțiuni de aspect și apoi remediază aranjarea elementelor care ne plac în cod.
În general, este de înțeles. Poti incerca si tu?
Desigur, pentru a crea rapid circuite, mi-am făcut un mic , care în sine actualizează schema și stochează cea mai recentă versiune în browser (în localStorage).
Ai încercat? Acum îl poți adăuga pe pagina ta.
Apoi din nou:
1. Conectarea scriptului
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Adăugați codul î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. edităm codul după diagrama de care avem nevoie (cred că este mai ușor decât să desenăm o bufniță :)
Mai multe detalii la pe github.
Rezultatul?
Mi-am atins obiectivele - pentru a adăuga diagrame inline la documentație, formatul este destul de simplu și de înțeles. Nu este potrivit pentru super circuite, dar pentru circuite mici care explică structura conexiunilor, este absolut în regulă. Poți oricând să modifici și să schimbi rapid ceva în timp. Da, iar colegii pot corecta ei înșiși ceva în andocare, măcar legendele pentru obiecte, fără pregătire specială))
Ce poate fi îmbunătățit?
Există, desigur, o mulțime de opțiuni aici. Adăugați pictograme suplimentare (toate cele existente sunt adăugate în script). Alegeți un set mai expresiv de pictograme. Faceți posibilă specificarea stilului liniei de conectare. Adăugați o imagine de fundal.
Ce crezi?
Am deja câteva idei de implementare în probleme, le poți adăuga și pe ale tale în comentarii.
Soluția mea este cu siguranță aplicabilă într-o gamă restrânsă de probleme și poate veți găsi un instrument mai convenabil pentru desenarea diagramelor prin simpla codificare - așa cum se spune „arată-mi diagrama ca cod”
- (9 tipuri de editor online de grafice)
- Și dacă vă plac diagramele super detaliate și complexe, atunci cu siguranță veți admira acest proiect:
Sursa: www.habr.com