Nos últimos dois anos, comecei a lidar mais com a documentação. Escreva um texto explicativo sobre como esse ou aquele sistema funciona - em geral, é bastante simples. Desenhe um diagrama no qual todos os objetos principais serão exibidos; a relação entre esses objetos também é bastante fácil.Mas o momento mais problemático é manter essa documentação atualizada. E tudo bem, o texto, mas os diagramas ... Porque toda a documentação está online, ou seja, no formato html, as imagens gif / jpeg / png são anexadas ao texto, no qual os diagramas são realmente retratados. E os esquemas são desenhados em vários programas, como o Visio ou serviços online a la draw.io. Em seguida, você exporta o diagrama para um formato gráfico e o anexa ao html. Tudo é simples.Qual é o problema?Esquemas são geralmente simples. Mais precisamente, não muito complicado. Sim, o número de objetos é dez 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 muito complexos, hmm ... (s) "eles não entendem, senhor". Existem muitos esquemas, as alterações precisam ser feitas periodicamente, periodicamente, ou seja, constantemente, porque eles seguem o desenvolvimento de nossos produtos.Você pode incorporar o serviço html. Tentaste?Sim, claro. Por exemplo, eu gosto dos gráficos do gliffy.com. Mas, para as alterações, você precisa acessar um serviço de terceiros, para editar. E é mais difícil delegar alterações a um colega.O que fazer?Recentemente, em um github, me deparei com o repositório github.com/RaoulMeyer/diagram-as-code nas recomendações. Gráfico como um código. Essa. descrevemos em js o circuito que precisamos. Nós escrevemos esses js diretamente no mesmo html onde está o outro texto da documentação.A propósito, mas não estou escrevendo documentação em html. Normalmente, a documentação é um conjunto de arquivos com texto de remarcação, que é convertido em um site de documentação completo por algum mecanismo, por exemplo, wintersmith. Ou um sistema wiki.Acontece muito conveniente: aqui escrevemos o texto, a tag do script é aberta e o código js do circuito é descrito nela.O que há de errado de novo?Gostei deste repositório, mas este não é o único exemplo quando um diagrama é desenhado usando código ou uma exibição de texto. (No final do artigo, haverá links para projetos e artigos que pesquisaram no diagrama de tópicos como código.)E não sou o único que corrige a documentação. Às vezes, os colegas também contribuem - corrija a palavra, mude a descrição, insira novas figuras. Portanto, eu gostaria de ver o diagrama em um formato de texto legível e legível, que não precisaria ser estudado por muito tempo. E, em alguns lugares, é fácil copiar e colar para acelerar a adição de um novo esquema. E outro colega observou que o código é, obviamente, bom, mas se você usar a estrutura, tudo poderá ser muito rigoroso e expressivo.Portanto, tentei apresentar o esquema como um conjunto de várias pequenas matrizes que descrevem nós, conexões, grupos de nós, bem como a localização dos nós. Na minha humilde opinião, resultou bastante conveniente, embora, é claro, o sabor e a cor ...Como está o gráfico na matriz?- Cada nó é descrito por um identificador que identifica exclusivamente o nó.
- Você também pode adicionar um ícone ao nó, adicionar uma inscrição.
- Você pode especificar um relacionamento entre dois nós.
- Para comunicação sobre o esquema, você pode definir a cor, a inscrição.
- A direção da comunicação é definida como da origem ao destino. E a origem e o destino são indicados pelos identificadores do nó.
- Um ou mais nós podem ser adicionados ao grupo.
- Um link também pode ser especificado de um grupo para um grupo.
Usando essas regras simples, obtemos esse esquema. Simplesmente? Bastante.
E é descrito pelo seguinte código js. A principal coisa aqui é o objeto de elementos. Nos quais nós - nós, arestas - conexões são indicados. 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);
Obviamente, eu não pensei em desenhar o circuito, mas usei a biblioteca cytoscape.js , uma ferramenta de visualização muito poderosa. Toliku oportunidades que na minha decisão eu uso apenas. Claramente, este é um exemplo simples. Pode ser mais complicado?Sim por favor. Para indicar posições - usamos posições, para indicar grupos - especificamos uma lista de grupos em grupos, e os próprios elementos têm 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>
Esse esquema, por um lado, inclui quase duas telas de código no laptop; por outro lado, a estrutura a la json permite que você preencha todos os dados por analogia, rapidamente, e você pode copiar e colar.E por que as posições são tiradas separadamente dos nós?Isso é mais confortável. Primeiro, especificamos nós. Em seguida, podemos indicar alguns grupos e indicá-los em nós. Então denotamos a conexão. E então, quando os objetos principais e as conexões entre eles estiverem, ocupamos a localização desses objetos no diagrama. Ou vice-versa.É possível sem posições?É possível sem posições. Mas será um pouco amassado, nos exemplos você pode ver esta opção. Isso se deve ao fato de que, para o cytoscape, existe um algoritmo para a localização dos nós fcose, que também leva em consideração a presença de grupos. A especificação de posições torna o esquema mais controlável, mas no estágio do primeiro rascunho do esquema é possível sem posições.Além disso, as posições podem ser especificadas no estilo da batalha naval. Essa. um nó está localizado em a1 e o outro em d5. Isso ajuda especialmente o fato de o cytoscape formar objetos em telas móveis, ou seja, podemos movê-los, analisar diferentes opções de layout e, em seguida, fixar no código sua organização favorita dos elementos.Em geral, eu vejo. Você também pode tentar? Obviamente, para criar esquemas rapidamente, eu me tornei um pequeno editor , que atualiza o próprio esquema e armazena a última opção no navegador (em localStorage).Tentaste? Agora você pode adicionar à sua página.Então, novamente:1. Nós conectamos um script<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Adicione ao código 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. edite o código para o esquema de que precisamos (acho mais fácil do que desenhar uma coruja :)Mais detalhes na página do projeto no github.Qual é o resultado?Atingi meus objetivos - para adicionar esquemas em linha à documentação, o formato é bastante simples e direto. Não é adequado para superesquemas, mas para pequenos circuitos que explicam a estrutura das conexões, nem é nada. Você sempre pode corrigi-lo rapidamente e alterar algo ao longo do tempo. Sim, e os colegas podem corrigir alguma coisa no banco dos réus, pelo menos assinaturas para objetos sem treinamento especial))O que pode ser melhorado?Existem, é claro, muitas opções. Faça a adição de ícones adicionais (todos os disponíveis são adicionados em linha ao script). Escolha um conjunto mais expressivo de ícones. Torne possível especificar um estilo de linha de link. Adicione imagem de fundo.O que você acha? Eu já tenho algumas idéias para implementação em problemas, você também adiciona a sua nos comentários.Minha solução é definitivamente aplicável em uma gama limitada de tarefas, e talvez você encontre uma ferramenta mais conveniente para desenhar diagramas simplesmente codificando-os - como eles dizem 'mostre-me seu diagrama como código'- Boa seleção
- Serviço fino (9 tipos de editor de gráficos on-line)
- Claro mermaid.js
- E se você gosta de esquemas super detalhados e complexos, esse projeto definitivamente irá encantar você: go.drawthe.net