En los últimos años, comencé a tratar más con la documentación. Escriba un texto explicativo sobre cómo funciona este o aquel sistema; en general, es bastante simple. Dibuje un diagrama en el que se mostrarán todos los objetos clave, la relación entre estos objetos también es bastante fácil.Pero el momento más problemático es mantener esta documentación actualizada. Y bueno, el texto, pero los diagramas ... Porque toda la documentación está en línea, es decir en formato html, las imágenes gif / jpeg / png se adjuntan al texto, en el que se representan realmente los diagramas. Y los esquemas se dibujan en varios programas como Visio o servicios en línea a la draw.io. Luego exporta el diagrama a un formato gráfico y lo adjunta a html. Todo es simple¿Cuál es el problema?Los esquemas suelen ser simples. Más precisamente, no muy complicado. Sí, el número de objetos es diez o dos, el número de conexiones es casi el mismo. Más firmas, algunas designaciones. Los esquemas simples se pueden describir con palabras, pero demasiado complejos, hmm ... (s) "no entienden, señor". Hay muchos esquemas, los cambios en ellos deben hacerse periódicamente, periódicamente, es decir constantemente, porque Siguen el desarrollo de nuestros productos.Puede incrustar el servicio html. ¿Lo has probado?Sí, por supuesto. Por ejemplo, me gustan los gráficos de gliffy.com. Pero para los cambios, debe ir a un servicio de terceros, allí para editar. Y es más difícil delegar enmiendas a un colega.¿Qué hacer?Recientemente, en un github, me encontré con el repositorio github.com/RaoulMeyer/diagram-as-code en recomendaciones. Gráfico como un código. Aquellos. describimos en js el circuito que necesitamos. Escribimos este js directamente en el mismo html donde está el otro texto de documentación.Por cierto, pero no estoy escribiendo documentación en html en absoluto. Por lo general, la documentación es un conjunto de archivos con texto de descuento, que luego se convierte en un sitio de documentación completo por algún motor, por ejemplo Wintersmith. O un sistema wiki.Resulta muy conveniente: aquí escribimos el texto, luego se abre la etiqueta del script y se describe el código js del circuito.¿Qué pasa de nuevo?Me gustó este repositorio, pero este no es el único ejemplo cuando se dibuja un diagrama usando código o una vista de texto. (Al final del artículo habrá enlaces a proyectos y artículos que buscaron en Google en el diagrama del tema como código).Y no soy el único que corrige la documentación. A veces, los colegas también contribuyen: corrija la palabra, cambie la descripción, inserte nuevas imágenes. Por lo tanto, me gustaría ver el diagrama en un formato de texto legible y comprensible, que no tendría que estudiarse durante mucho tiempo. Y en algunos lugares, incluso es fácil copiar y pegar para acelerar la incorporación de un nuevo esquema. Y otro colega señaló que el código es, por supuesto, bueno, pero si usa la estructura, todo puede ser muy estricto y expresivo.Por lo tanto, intenté presentar el esquema como un conjunto de varias matrices pequeñas que describen nodos, conexiones, grupos de nodos, así como la ubicación de los nodos. Resultó, en mi humilde opinión, bastante conveniente, aunque, por supuesto, el sabor y el color ...¿Cómo está la tabla en la matriz?- Cada nodo se describe mediante un identificador que identifica de forma exclusiva el nodo.
- También puede agregar un icono al nodo, agregar una inscripción.
- Puede especificar una relación entre dos nodos.
- Para la comunicación sobre el esquema, puede establecer el color, la inscripción.
- La dirección de comunicación se define como de origen a destino. Y el origen y el destino están indicados por los identificadores del nodo.
- Se pueden agregar uno o más nodos al grupo.
- También se puede especificar un enlace de un grupo a otro.
Usando estas reglas simples, obtenemos tal esquema. ¿Simplemente? Bastante.
Y se describe mediante el siguiente código js. Lo principal aquí es el objeto de elementos. En el que se indican los nodos - nodos, bordes - conexiones. 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 supuesto, no pensé en dibujar el circuito yo mismo, pero usé la biblioteca cytoscape.js , una herramienta de visualización muy poderosa. Oportunidades de Toliku que en mi decisión solo uso. Claramente, este es un ejemplo simple. ¿Puede ser más complicado?Sí por favor. Para indicar posiciones, utilizamos posiciones, para indicar grupos, especificamos una lista de grupos en grupos, y los elementos mismos tienen un atributo de grupo.
Y este es el 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>
Tal esquema, por un lado, es casi un par de pantallas de código en la computadora portátil, por otro lado, una estructura a la json le permite completar todos los datos por analogía, rápidamente y puede copiar y pegar.¿Y por qué las posiciones se toman por separado de los nodos?Esto es mas comodo. Primero especificamos nodos. Luego podemos indicar un par de grupos e indicarlos en nodos. Luego denotamos la conexión. Y luego, cuando los objetos principales y las conexiones entre ellos son, tomamos la ubicación de estos objetos en el diagrama. O viceversa.¿Es posible sin cargos?Es posible sin cargos. Pero estará un poco arrugado, en los ejemplos puedes ver esta opción. Esto se debe al hecho de que para cytoscape hay un algoritmo para la ubicación de los nodos de glucosa, que también tiene en cuenta la presencia de grupos. Especificar posiciones hace que el esquema sea más controlable, pero en la etapa del primer borrador del esquema es posible sin posiciones.Además, las posiciones se pueden especificar en el estilo de la batalla naval. Aquellos. un nodo se encuentra en a1 y el otro en d5. Ayuda especialmente que el cytoscape forme objetos sobre lienzo móviles, es decir podemos moverlos, ver diferentes opciones de diseño y luego fijar en el código su disposición favorita de elementos.En general, ya veo. También puedes probar? Por supuesto, para crear esquemas rápidamente, me hice un pequeño editor , que actualiza el esquema en sí y almacena la última opción en el navegador (en localStorage).¿Lo has probado? Ahora puede agregar a su página.Por otra parte:1. Conectamos un script<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Agregar al 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 el código al esquema que necesitamos (creo que es más fácil que dibujar un búho :)Más detalles en la página del proyecto en el github.Cual es el resultado?Logré mis objetivos: agregar esquemas en línea a la documentación, el formato es bastante simple y directo. No es adecuado para superschemes, pero para pequeños circuitos que explican la estructura de las conexiones, ni siquiera es nada. Siempre puede solucionarlo rápidamente y cambiar algo con el tiempo. Sí, y los colegas pueden corregir algo en el muelle ellos mismos, al menos firmas de objetos sin entrenamiento especial))¿Qué se puede mejorar?Por supuesto, hay muchas opciones. Agregue íconos adicionales (todos los disponibles se agregan en línea al script). Elija un conjunto de iconos más expresivo. Permitir especificar un estilo de línea de enlace. Añadir imagen de fondo.¿Qué piensas? Ya tengo algunas ideas para implementar en los problemas, también agregas las tuyas en los comentarios.Mi solución es definitivamente aplicable en un rango reducido de tareas, y quizás encuentre una herramienta más conveniente para dibujar diagramas simplemente codificándolos, ya que dicen 'muéstrame tu diagrama como código'- Buena selección
- Servicio elegante (9 tipos de editor de gráficos en línea)
- Por supuesto mermaid.js
- Y si te gustan los esquemas súper detallados y complejos, entonces este proyecto definitivamente te encantará: go.drawthe.net