En la lastaj du jaroj mi pli okupiĝis pri dokumentado. Verki klarigan tekston pri kiel funkcias aparta sistemo estas ĝenerale sufiĉe simpla. Desegni diagramon kiu montros ĉiujn ŝlosilajn objektojn kaj la ligojn inter ĉi tiuj objektoj ankaŭ estas sufiĉe facila.
Sed la plej problema aspekto estas teni ĉi tiun dokumentaron ĝisdatigita. Kaj la teksto estus bone, sed la diagramoj... Ĉar... la tuta dokumentaro estas interreta, t.e. en formato html, tiam la teksto estas akompanata de bildoj gif/jpeg/png, kiuj efektive montras la diagramojn. Kaj diagramoj estas desegnitaj en diversaj programoj kiel Visio aŭ interretaj servoj al draw.io. Poste vi eksportas la diagramon en grafikan formaton kaj alfiksas ĝin al html. Ĝi estas simpla.
Kio estas la problemo?
La skemoj estas kutime simplaj. Pli precize, ne tre komplika. Jes, la nombro da objektoj estas dekduo aŭ du, la nombro da konektoj estas proksimume la sama. Plie subskriboj, kelkaj nomoj. Simplaj skemoj povas esti priskribitaj per vortoj, sed tro kompleksaj, ej... (c) "ili ne komprenos, sinjoro." Estas multaj skemoj, ŝanĝoj devas esti faritaj al ili periode, epizode, t.e. konstante, ĉar ili sekvas la evoluon de niaj produktoj.
Vi povas enigi la html-on de la servo. Ĉu vi provis ĝin?
Jes certa. Ekzemple, mi ŝatas la grafikaĵojn de gliffy.com. Sed por fari ŝanĝojn, vi devas iri al triaparta servo kaj redakti tie. Kaj estas pli malfacile delegi korektojn al kolego.
Kion mi faru?
Lastatempe mi renkontis deponejon sur Github en la rekomendoj . Diagramo kiel kodo. Tiuj. ni priskribas la cirkviton, kiun ni bezonas en js. Ni skribas ĉi tiun js rekte en la sama html kie estas la alia dokumenta teksto.
Cetere, mi skribas dokumentaron ne tute en html. Tipe, dokumentaro estas aro de dosieroj kun markdown-teksto, kiu tiam estas konvertita en plenrajtan dokumentarejon de iu motoro, ekzemple vintroforĝisto. Aŭ vikia sistemo.
Ĝi rezultas tre oportuna: ni skribis la tekston, tiam la skripto-etikedo malfermiĝas kaj la JS-kodo de la skemo estas priskribita en ĝi.
Kio estas denove malbona?
Mi ŝatis ĉi tiun deponejon, sed ĉi tio ne estas la sola ekzemplo, kie diagramo estas desegnita uzante kodon aŭ tekstan reprezenton. (Ĉe la fino de la artikolo estos ligiloj al projektoj kaj artikoloj, kiujn mi Guglos pri la temdiagramo kiel kodo.)
Kaj mi ne estas la sola, kiu redaktas la dokumentadon. Foje ankaŭ kolegoj kontribuas - korektu vorton, ŝanĝu priskribon, enmetu novajn bildojn.
Tial mi ŝatus vidi la diagramon en legebla, komprenebla tekstformato, kiu ne postulus longan lernkurbon. Kaj en kelkaj lokoj vi povas eĉ simple kopii-alglui por akceli aldoni novan cirkviton.
Kaj alia kolego rimarkis, ke kodo estas, kompreneble, bona, sed se vi uzas strukturon, ĉio povas esti tre strikta kaj esprimplena.
Tial mi provis imagi la diagramon kiel aron de pluraj malgrandaj tabeloj, kiuj priskribas nodojn, konektojn, grupojn de nodoj, kaj ankaŭ la lokon de nodoj. Montriĝis, laŭ mia humila opinio, sufiĉe oportuna, kvankam, kompreneble, la gusto kaj koloro...
Kiel ĉi tio estas diagramo en tabelo?
- Ĉiu nodo estas priskribita per identigilo kiu unike identigas la nodon.
- Vi ankaŭ povas aldoni ikonon al la nodo kaj aldoni surskribon.
- Vi povas specifi rilaton inter du nodoj.
- Por komunikado sur la diagramo, vi povas agordi la koloron kaj surskribon.
- La direkto de komunikado estas difinita kiel de fonto al celo. Kaj la fonto kaj celo estas indikitaj per nodaj identigiloj.
- Unu aŭ pluraj nodoj povas esti aldonitaj al grupo.
- La rilato ankaŭ povas esti precizigita kaj de la grupo kaj al la grupo.
Uzante ĉi tiujn simplajn regulojn, ni ricevas la sekvan diagramon. Nur? Tute.
Kaj ĝi estas priskribita per la sekva js-kodo. La ĉefa afero ĉi tie estas la elementoj objekto. En kiu nodoj estas indikitaj - nodoj, randoj - ligoj.
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);
Kompreneble, mi ne mem elpensis la desegnadon de la cirkvito, sed uzis la bibliotekon estas tre potenca bildiga ilo. Mi uzas nur frakcion de la eblecoj en mia solvo.
Bone, ĉi tio estas simpla ekzemplo. Ĉu ĝi povas esti pli komplika?
Jes bonvolu. Por indiki poziciojn, ni uzas poziciojn, por indiki grupojn, ni indikas liston de grupoj en grupoj, kaj la elementoj mem havas grupatributon.
Kaj jen la kodo:
<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>
Unuflanke, tia skemo estas preskaŭ kelkaj ekranoj de kodo sur tekkomputilo, aliflanke, la strukturo a la json permesas vin plenigi ĉiujn datumojn per analogio, rapide kaj vi povas kopii-alglui.
Kial pozicioj estas metitaj aparte de nodoj?
Ĝi estas pli komforta. Unue ni specifas nodojn. Tiam ni povas specifi kelkajn grupojn kaj indiki ilin en nodoj. Tiam ni nomumas la ligojn. Kaj nur tiam, kiam la ĉefaj objektoj kaj ligoj inter ili estas tie, ni prenas la lokon de ĉi tiuj objektoj sur la diagramo. Aŭ inverse.
Ĉu eblas sen postenoj?
Ĝi eblas sen pozicioj. Sed ĝi estos iom ĉifita; vi povas vidi ĉi tiun opcion en la ekzemploj. Ĉi tio estas pro la fakto ke ekzistas algoritmo por la loko de nodoj por citoscape , kiu ankaŭ konsideras la ĉeeston de grupoj. Specifante poziciojn faras la diagramon pli kontrolebla, sed en la stadio de la unua skizo de la diagramo eblas sen pozicioj.
Pozicioj ankaŭ povas esti precizigitaj en la Batalŝipo-stilo. Tiuj. unu nodo situas en a1, kaj la alia en d5. Precipe helpas, ke citoscape igas la objektojn sur la kanvaso moveblaj, t.e. ni povas movi ilin, vidi malsamajn aranĝajn opciojn, kaj poste ripari la aranĝon de la elementoj, kiujn ni ŝatas en la kodo.
Ĝenerale, ĝi estas komprenebla. Ĉu vi ankaŭ povas provi?
Kompreneble, por rapide krei cirkvitojn, mi faris min malgranda , kiu mem ĝisdatigas la skemon kaj konservas la lastan version en la retumilo (en loka Stokado).
Ĉu vi provis ĝin? Vi nun povas aldoni ĝin al via paĝo.
Tiam denove:
1. Konektante la skripton
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Aldonu kodon al 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. ni redaktas la kodon al la diagramo, kiun ni bezonas (mi pensas, ke ĝi estas pli facila ol desegni strigon :)
Pliaj detaloj ĉe sur github.
Kio en la fino?
Mi atingis miajn celojn - por aldoni enliniajn diagramojn al la dokumentaro, la formato estas sufiĉe simpla kaj komprenebla. Ĝi ne taŭgas por supercirkvitoj, sed por malgrandaj cirkvitoj, kiuj klarigas la strukturon de konektoj, ĝi estas tute bone. Vi ĉiam povas rapide ŝanĝi kaj ŝanĝi ion laŭlonge de la tempo. Jes, kaj kolegoj povas mem korekti ion en la doko, almenaŭ bildotekstojn por objektoj, sen speciala trejnado))
Kion oni povas plibonigi?
Estas, kompreneble, multaj ebloj ĉi tie. Aldonu pliajn ikonojn (ĉiuj ekzistantaj estas aldonitaj enlinie al la skripto). Elektu pli esprimplenan aron da ikonoj. Ebligu specifi la stilon de la koneksa linio. Aldonu fonbildon.
Kion vi pensas?
Mi jam havas plurajn ideojn por efektivigo en temoj, vi ankaŭ povas aldoni la viajn en la komentoj.
Mia solvo certe aplikeblas en malvasta gamo da problemoj, kaj eble vi trovos pli oportunan ilon por desegni diagramojn simple kodante ilin - kiel oni diras 'montru al mi vian diagramon kiel kodon'.
- (9 specoj de leteroj reta redaktilo)
- Kaj se vi ŝatas superdetalajn kaj kompleksajn diagramojn, tiam vi certe admiros ĉi tiun projekton:
fonto: www.habr.com