Nos últimos dous anos participei máis na documentación. Escribir un texto explicativo sobre como funciona un sistema en particular é xeralmente bastante sinxelo. Debuxar un diagrama que mostrará todos os obxectos clave e as conexións entre estes obxectos tamén é bastante sinxelo.
Pero o aspecto máis problemático é manter esta documentación actualizada. E o texto estaría ben, pero os diagramas... Porque... toda a documentación está en liña, é dicir. en formato html, entón o texto vai acompañado de imaxes gif/jpeg/png, que en realidade mostran os diagramas. E os diagramas son debuxados en varios programas como Visio ou servizos en liña a la draw.io. A continuación, exporta o diagrama a formato gráfico e adxuntao a html. É sinxelo.
Cal é o problema?
Os esquemas adoitan ser sinxelos. Máis precisamente, non moi complicado. Si, o número de obxectos é unha ducia ou dous, o número de conexións é aproximadamente o mesmo. Ademais de sinaturas, algunhas designacións. Os esquemas sinxelos pódense describir con palabras, pero os demasiado complexos, ejem... (c) "non entenderán, señor". Hai moitos esquemas, hai que facerlles cambios periodicamente, de forma episódica, é dicir. constantemente, porque seguen o desenvolvemento dos nosos produtos.
Podes inserir o html do servizo. Probaches?
Si, seguro. Por exemplo, gústanme os gráficos de gliffy.com. Pero para facer cambios, cómpre ir a un servizo de terceiros e editar alí. E é máis difícil delegar correccións nun compañeiro.
¿Que facer?
Recentemente atopeime cun repositorio en Github nas recomendacións . Diagrama como código. Eses. describimos o circuíto que necesitamos en js. Escribimos este js directamente no mesmo html onde está o outro texto de documentación.
Por certo, escribo documentación non totalmente en html. Normalmente, a documentación é un conxunto de ficheiros con texto de rebaixa, que despois algún motor, por exemplo, Wintersmith converte nun sitio de documentación completo. Ou un sistema wiki.
Resulta moi cómodo: escribimos o texto, despois ábrese a etiqueta de guión e nela descríbese o código JS do esquema.
Que pasa de novo?
Gustoume este repositorio, pero este non é o único exemplo onde se debuxa un diagrama usando código ou unha representación de texto. (Ao final do artigo haberá ligazóns a proxectos e artigos que busquei en Google no diagrama do tema como código).
E non son o único que edita a documentación. Ás veces, os compañeiros tamén contribúen: corrixir unha palabra, cambiar unha descrición, inserir novas imaxes.
Polo tanto, gustaríame ver o diagrama nun formato de texto lexible e comprensible que non requira unha longa curva de aprendizaxe. E nalgúns lugares pode incluso simplemente copiar e pegar para acelerar a adición dun novo circuíto.
E outro compañeiro sinalou que o código é, por suposto, bo, pero se usa estrutura, todo pode ser moi estrito e expresivo.
Polo tanto, tentei imaxinar o diagrama como un conxunto de varias matrices pequenas que describen nodos, conexións, grupos de nós, así como a localización dos nós. Resultou, na miña humilde opinión, bastante cómodo, aínda que, por suposto, o sabor e a cor...
Como é este un gráfico nunha matriz?
- Cada nodo descríbese mediante un identificador que o identifica de forma única.
- Tamén pode engadir unha icona ao nodo e engadir unha inscrición.
- Podes especificar unha relación entre dous nodos.
- Para a comunicación no diagrama, pode definir a cor e a inscrición.
- A dirección da comunicación defínese como desde a orixe ata o destino. E a orixe e o destino indícanse mediante identificadores de nodos.
- Pódense engadir un ou máis nodos a un grupo.
- A relación tamén se pode especificar tanto dende o grupo como co grupo.
Usando estas sinxelas regras, obtemos o seguinte diagrama. Só? Moito.
E descríbese co seguinte código js. O principal aquí son os elementos obxecto. No que se indican os nodos -nodos, bordos- conexións.
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);
Por suposto, eu non me inventei o debuxo do circuíto, senón que usei a biblioteca é unha ferramenta de visualización moi poderosa. Eu só uso unha fracción das posibilidades na miña solución.
Vale, este é un exemplo sinxelo. Pode ser máis complicado?
Sí por favor. Para indicar posicións, utilizamos posicións, para indicar grupos, indicamos unha lista de grupos en grupos, e os propios elementos teñen un atributo de grupo.
E este é o código:
<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>
Por unha banda, tal esquema é case un par de pantallas de código nun portátil, por outra banda, a estrutura á json permite encher todos os datos por analoxía, rapidamente e pode copiar-pegar.
Por que se colocan as posicións por separado dos nodos?
É máis cómodo. Primeiro especificamos os nodos. Despois podemos especificar un par de grupos e indicalos en nodos. Despois designamos as conexións. E só entón, cando os principais obxectos e conexións entre eles están alí, tomamos a localización destes obxectos no diagrama. Ou viceversa.
É posible sen postos?
É posible sen postos. Pero estará un pouco engurrado; podes ver esta opción nos exemplos. Isto débese ao feito de que hai un algoritmo para a localización dos nodos para cytoscape , que tamén ten en conta a presenza de grupos. Especificar posicións fai que o diagrama sexa máis controlable, pero na fase do primeiro borrador do diagrama é posible sen posicións.
As posicións tamén se poden especificar no estilo Battleship. Eses. un nodo está situado en a1 e o outro en d5. Axuda especialmente que o cytoscape faga que os obxectos do lenzo sexan móbiles, é dicir. podemos movelos, ver diferentes opcións de deseño e, a continuación, corrixir a disposición dos elementos que nos gustan no código.
En xeral, é comprensible. Tamén podes probar?
Por suposto, para crear circuítos rapidamente, fixenme un pequeno , que actualiza o esquema e almacena a última versión no navegador (en localStorage).
Probaches? Agora podes engadilo á túa páxina.
Entón de novo:
1. Conectando o guión
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Engadir código 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. editamos o código para o diagrama que necesitamos (creo que é máis fácil que debuxar unha curuxa :)
Máis detalles en en github.
O resultado?
Conseguín os meus obxectivos: engadir diagramas en liña á documentación, o formato é bastante sinxelo e comprensible. Non é adecuado para súper circuítos, pero para pequenos circuítos que explican a estrutura das conexións, está absolutamente ben. Sempre podes modificar e cambiar algo rapidamente co paso do tempo. Si, e os compañeiros poden corrixir algo no banco dos mesmos, polo menos os subtítulos para obxectos, sen formación especial))
Que se pode mellorar?
Hai, por suposto, moitas opcións aquí. Engade iconas adicionais (todas as existentes engádense en liña ao guión). Escolle un conxunto de iconas máis expresivo. Fai posible especificar o estilo da liña de conexión. Engade unha imaxe de fondo.
Que opinas?
Xa teño varias ideas para implementar en temas, tamén podedes engadir a vosa nos comentarios.
A miña solución é definitivamente aplicable a un abano limitado de problemas, e quizais atopes unha ferramenta máis conveniente para debuxar diagramas simplemente codificándoos, como din "mostrame o teu diagrama como código"
- (9 tipos de editor en liña de gráficos)
- E se che gustan os diagramas súper detallados e complexos, definitivamente admirarás este proxecto:
Fonte: www.habr.com