En els darrers anys m'he implicat més en la documentació. Escriure un text explicatiu sobre com funciona un sistema en particular és generalment bastant senzill. Dibuixar un diagrama que mostrarà tots els objectes clau i les connexions entre aquests objectes també és bastant fàcil.
Però l'aspecte més problemàtic és mantenir aquesta documentació actualitzada. I el text estaria bé, però els diagrames... Perquè... tota la documentació està en línia, és a dir. en format html, llavors el text va acompanyat d'imatges gif/jpeg/png, que en realitat mostren els diagrames. I es dibuixen diagrames en diversos programes com Visio o serveis en línia a la draw.io. A continuació, exporteu el diagrama en format gràfic i l'adjunteu a html. És fàcil.
Quin és el problema?
Els esquemes solen ser senzills. Més precisament, no gaire complicat. Sí, el nombre d'objectes és una dotzena o dos, el nombre de connexions és aproximadament el mateix. A més de signatures, algunes designacions. Els esquemes simples es poden descriure amb paraules, però els massa complexos, ejem... (c) "no ho entendran, senyor". Hi ha molts esquemes, cal fer-hi canvis periòdicament, episòdicament, és a dir. constantment, perquè segueixen el desenvolupament dels nostres productes.
Podeu incrustar l'html del servei. Ho has provat?
Si, es clar. Per exemple, m'agraden els gràfics de gliffy.com. Però per fer canvis, heu d'anar a un servei de tercers i editar-hi. I és més difícil delegar les correccions a un company.
Què fer?
Recentment em vaig trobar amb un repositori a Github a les recomanacions . Diagrama com a codi. Aquells. descrivim el circuit que necessitem en js. Escrivim aquest js directament al mateix html on hi ha l'altre text de la documentació.
Per cert, escric documentació no totalment en html. Normalment, la documentació és un conjunt de fitxers amb text de reducció, que un motor, per exemple, Wintersmith, converteix en un lloc de documentació complet. O un sistema wiki.
Resulta molt convenient: hem escrit el text, després s'obre l'etiqueta de l'script i s'hi descriu el codi JS de l'esquema.
Què passa de nou?
M'ha agradat aquest dipòsit, però aquest no és l'únic exemple on es dibuixa un diagrama amb codi o una representació de text. (Al final de l'article hi haurà enllaços a projectes i articles que vaig buscar a Google sobre el diagrama del tema com a codi.)
I no sóc l'únic que edita la documentació. De vegades, els companys també contribueixen: corregiu una paraula, canvieu una descripció, inseriu imatges noves.
Per tant, m'agradaria veure el diagrama en un format de text llegible i entenedor que no requereixi una llarga corba d'aprenentatge. I en alguns llocs, fins i tot podeu simplement copiar i enganxar per accelerar l'addició d'un circuit nou.
I un altre company va assenyalar que el codi és, per descomptat, bo, però si feu servir l'estructura, tot pot ser molt estricte i expressiu.
Per tant, vaig intentar imaginar el diagrama com un conjunt de diverses matrius petites que descriuen nodes, connexions, grups de nodes, així com la ubicació dels nodes. Va resultar, a la meva humil opinió, força convenient, encara que, és clar, el gust i el color...
Com és això un gràfic en una matriu?
- Cada node està descrit per un identificador que identifica de manera única el node.
- També podeu afegir una icona al node i afegir una inscripció.
- Podeu especificar una relació entre dos nodes.
- Per a la comunicació al diagrama, podeu establir el color i la inscripció.
- La direcció de la comunicació es defineix com de l'origen a l'objectiu. I la font i la destinació s'indiquen mitjançant identificadors de nodes.
- Es poden afegir un o més nodes a un grup.
- La relació també es pot concretar tant des del grup com amb el grup.
Utilitzant aquestes senzilles regles, obtenim el següent diagrama. Només? Bastant.
I es descriu amb el següent codi js. El més important aquí és l'objecte dels elements. En què s'indiquen els nodes - nodes, vores - connexions.
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);
Per descomptat, no vaig fer el dibuix del circuit jo mateix, sinó que vaig fer servir la biblioteca és una eina de visualització molt potent. Només faig servir una part de les possibilitats de la meva solució.
D'acord, aquest és un exemple senzill. Pot ser més complicat?
Si, si us plau. Per indicar posicions, fem servir posicions, per indicar grups, indiquem una llista de grups en grups, i els mateixos elements tenen un atribut de grup.
I aquest és el codi:
<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>
D'una banda, aquest esquema és gairebé un parell de pantalles de codi en un ordinador portàtil, d'altra banda, l'estructura a la json us permet omplir totes les dades per analogia, ràpidament i podeu copiar-enganxar.
Per què es col·loquen les posicions per separat dels nodes?
És més còmode. Primer especifiquem els nodes. Aleshores podem especificar un parell de grups i indicar-los en nodes. Després designem les connexions. I només aleshores, quan els objectes principals i les connexions entre ells hi són, prenem la ubicació d'aquests objectes al diagrama. O viceversa.
És possible sense posicions?
És possible sense posicions. Però estarà una mica arrugat; podeu veure aquesta opció als exemples. Això es deu al fet que hi ha un algorisme per a la localització dels nodes per al cytoscape , que també té en compte la presència de grups. Especificar posicions fa que el diagrama sigui més controlable, però en l'etapa del primer esborrany del diagrama és possible sense posicions.
Les posicions també es poden especificar a l'estil Battleship. Aquells. un node es troba a a1 i l'altre a d5. Ajuda especialment que el cytoscape faci que els objectes del llenç siguin mòbils, és a dir. podem moure'ls, veure diferents opcions de disseny i després arreglar la disposició dels elements que ens agraden al codi.
En general, és comprensible. També pots provar?
Per descomptat, per crear circuits ràpidament, em vaig fer un petit , que actualitza l'esquema i emmagatzema la darrera versió al navegador (a localStorage).
Ho has provat? Ara pots afegir-lo a la teva pàgina.
Una altra vegada:
1. Connectant el guió
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Afegeix codi a 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. editem el codi al diagrama que necessitem (crec que és més fàcil que dibuixar un mussol :)
Més detalls a a github.
El resultat?
Vaig aconseguir els meus objectius: per afegir diagrames en línia a la documentació, el format és bastant simple i comprensible. No és adequat per a supercircuits, però per a circuits petits que expliquen l'estructura de les connexions, està absolutament bé. Sempre podeu modificar i canviar alguna cosa ràpidament amb el pas del temps. Sí, i els companys poden corregir alguna cosa al moll ells mateixos, almenys subtítols per a objectes, sense formació especial))
Què es pot millorar?
Per descomptat, hi ha moltes opcions aquí. Afegiu icones addicionals (totes les existents s'afegeixen en línia a l'script). Trieu un conjunt d'icones més expressiu. Permet especificar l'estil de la línia de connexió. Afegeix una imatge de fons.
Què penses?
Ja tinc diverses idees per implementar en temes, també podeu afegir les vostres als comentaris.
La meva solució és definitivament aplicable a una gamma reduïda de problemes, i potser trobareu una eina més convenient per dibuixar diagrames simplement codificant-los, com diuen "mostra'm el teu diagrama com a codi".
- (9 tipus d'editor en línia de gràfics)
- I si t'agraden els diagrames súper detallats i complexos, sens dubte admiraràs aquest projecte:
Font: www.habr.com