Nos últimos anos, me envolvi mais com documentação. Escrever um texto explicativo sobre como funciona um determinado sistema geralmente é bastante simples. Desenhar um diagrama que exiba todos os objetos principais e as conexões entre esses objetos também é bastante fácil.
Mas o aspecto mais problemático é manter esta documentação atualizada. E o texto estaria bem, mas os diagramas... Porque... toda a documentação está online, ou seja, em formato html, o texto vem acompanhado de imagens gif/jpeg/png, que na verdade mostram os diagramas. E os diagramas são desenhados em vários programas, como Visio ou serviços online à la draw.io. Em seguida, você exporta o diagrama em formato gráfico e anexa-o ao HTML. É simples.
Qual é o problema?
Os esquemas geralmente são simples. Mais precisamente, não muito complicado. Sim, o número de objetos é uma dúzia ou dois, o número de conexões é aproximadamente o mesmo. Além de assinaturas, algumas designações. Esquemas simples podem ser descritos em palavras, mas esquemas muito complexos, aham... (c) “eles não vão entender, senhor.” Existem muitos esquemas, mudanças precisam ser feitas neles periodicamente, episodicamente, ou seja, constantemente, porque eles acompanham o desenvolvimento de nossos produtos.
Você pode incorporar o html do serviço. Tentaste?
Sim, claro. Por exemplo, gosto dos gráficos do gliffy.com. Mas para fazer alterações, você precisa ir a um serviço de terceiros e editar lá. E é mais difícil delegar correções a um colega.
O que fazer?
Recentemente me deparei com um repositório no Github nas recomendações . Diagrama como código. Aqueles. descrevemos o circuito que precisamos em js. Escrevemos esse js diretamente no mesmo html onde está o outro texto da documentação.
A propósito, não escrevo documentação inteiramente em HTML. Normalmente, a documentação é um conjunto de arquivos com texto markdown, que é então convertido em um site de documentação completo por algum mecanismo, por exemplo, Wintersmith. Ou um sistema wiki.
Acontece muito conveniente: escrevemos o texto, então a tag do script é aberta e o código JS do esquema é descrito nela.
O que está errado de novo?
Gostei deste repositório, mas este não é o único exemplo em que um diagrama é desenhado usando código ou representação de texto. (No final do artigo haverá links para projetos e artigos que pesquisei no Google no diagrama de tópicos como código.)
E não sou o único editando a documentação. Às vezes, os colegas também contribuem – corrigem uma palavra, alteram uma descrição, inserem novas imagens.
Portanto, gostaria de ver o diagrama em um formato de texto legível e compreensível que não exigisse uma longa curva de aprendizado. E em alguns lugares você pode simplesmente copiar e colar para acelerar a adição de um novo circuito.
E outro colega observou que código é, claro, bom, mas se você usar estrutura, tudo pode ser muito rígido e expressivo.
Portanto, tentei imaginar o diagrama como um conjunto de vários pequenos arrays que descrevem nós, conexões, grupos de nós, bem como a localização dos nós. Acabou, na minha humilde opinião, bastante conveniente, embora, claro, o sabor e a cor...
Como isso é um gráfico em uma matriz?
- Cada nó é descrito por um identificador que identifica exclusivamente o nó.
- Você também pode adicionar um ícone ao nó e adicionar uma inscrição.
- Você pode especificar um relacionamento entre dois nós.
- Para comunicação no diagrama, você pode definir a cor e a inscrição.
- A direção da comunicação é definida como da origem ao destino. E a origem e o destino são indicados por identificadores de nó.
- Um ou mais nós podem ser adicionados a um grupo.
- O relacionamento também pode ser especificado tanto do grupo quanto para o grupo.
Usando essas regras simples, obtemos o diagrama a seguir. Apenas? Bastante.
E é descrito pelo seguinte código js. O principal aqui é o objeto dos elementos. Em quais nós são indicados - nós, arestas - conexões.
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);
Claro, não fui eu que fiz o desenho do circuito, mas usei a biblioteca é uma ferramenta de visualização muito poderosa. Eu uso apenas uma fração das possibilidades na minha solução.
Ok, este é um exemplo simples. Pode ser mais complicado?
Sim por favor. Para indicar posições, usamos posições, para indicar grupos, indicamos uma lista de grupos em grupos, e os próprios elementos possuem um 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 um lado, tal esquema consiste em quase algumas telas de código em um laptop, por outro lado, a estrutura à la json permite preencher todos os dados por analogia, de forma rápida e você pode copiar e colar.
Por que as posições são colocadas separadamente dos nós?
É mais confortável. Primeiro especificamos os nós. Então podemos especificar alguns grupos e indicá-los em nós. Então designamos as conexões. E só então, quando os objetos principais e as conexões entre eles estiverem presentes, assumimos a localização desses objetos no diagrama. Ou vice-versa.
É possível sem posições?
É possível sem posições. Mas vai ficar um pouco amassado, você pode ver essa opção nos exemplos. Isso se deve ao fato de existir um algoritmo de localização de nós para citoscape , que também leva em consideração a presença de grupos. A especificação de posições torna o diagrama mais controlável, mas na fase do primeiro rascunho do diagrama é possível sem posições.
As posições também podem ser especificadas no estilo Battleship. Aqueles. um nó está localizado em a1 e o outro em d5. Ajuda especialmente o fato de o cytoscape tornar os objetos na tela móveis, ou seja, podemos movê-los, ver diferentes opções de layout e então corrigir a disposição dos elementos que gostamos no código.
Em geral, é compreensível. Você também pode tentar?
Claro, para criar circuitos rapidamente, fiz para mim um pequeno , que atualiza o esquema e armazena a versão mais recente no navegador (em localStorage).
Tentaste? Agora você pode adicioná-lo à sua página.
Então de novo:
1. Conectando o roteiro
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Adicione código ao 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 no diagrama que precisamos (acho que é mais fácil do que desenhar uma coruja :)
Mais detalhes em no github.
O resultado?
Atingi meus objetivos - adicionar diagramas embutidos à documentação, o formato é bastante simples e direto. Não é adequado para supercircuitos, mas para circuitos pequenos que explicam a estrutura das conexões, é absolutamente adequado. Você sempre pode ajustar e alterar algo rapidamente ao longo do tempo. Sim, e os próprios colegas podem corrigir algo no banco dos réus, pelo menos legendas de objetos, sem treinamento especial))
O que pode ser melhorado?
Existem, é claro, muitas opções aqui. Adicione ícones adicionais (todos os existentes são adicionados inline ao script). Escolha um conjunto de ícones mais expressivo. Permite especificar o estilo da linha de conexão. Adicione uma imagem de fundo.
O que você acha?
Já tenho várias ideias para implementação em questões, você também pode adicionar a sua nos comentários.
Minha solução é definitivamente aplicável em uma gama restrita de problemas, e talvez você encontre uma ferramenta mais conveniente para desenhar diagramas simplesmente codificando-os - como dizem 'mostre-me seu diagrama como código'
- (9 tipos de editor online de gráficos)
- E se você gosta de diagramas super detalhados e complexos, com certeza irá admirar este projeto:
Fonte: habr.com