Au cours des dernières années, je me suis davantage consacré à la documentation. Écrire un texte explicatif sur le fonctionnement d'un système donné est en général assez simple. Dessiner un schéma représentant tous les objets clés et leurs relations est également relativement facile.
Mais le plus gros problème est de maintenir cette documentation à jour. Et ce n'est pas seulement le texte, mais aussi les schémas... Étant donné que toute la documentation est en ligne, c'est-à-dire au format html, des images gif/jpeg/png sont jointes au texte, où sont illustrés les schémas. Ces schémas sont dessinés dans divers programmes comme Visio ou des services en ligne tels que draw.io. Ensuite, il suffit d'exporter le schéma au format graphique et de l'ajouter à l'html. C'est simple.
Quel est le problème ?
Les schémas sont généralement simples. En fait, ils ne sont pas très complexes. Oui, le nombre d'objets est d'une dizaine à deux, et le nombre de relations est à peu près le même. Plus des étiquettes, quelques symboles. Des schémas simples peuvent être décrits par des mots, mais les trop compliqués, eh bien... (c) « ne vont pas comprendre-s ». Il y a beaucoup de schémas, et il est nécessaire d'y apporter des modifications de temps en temps, c'est-à-dire constamment, car ils suivent le développement de nos produits.
On peut intégrer html du service. Avez-vous essayé ?
Oui, bien sûr. Par exemple, j'aime les graphiques de gliffy.com. Mais pour effectuer des modifications, il faut aller dans un service tiers et faire les corrections là-bas. Il est également plus difficile de déléguer ces corrections à un collègue.
Que faire ?
Récemment, sur GitHub, je suis tombé sur un dépôt recommandé. . Diagramme comme code. C'est-à-dire que nous décrivons en js le schéma dont nous avons besoin. Ce js est écrit directement dans le même html que le reste du texte de la documentation.
Cela étant dit, je n'écris pas la documentation tout à fait en html. En général, la documentation est un ensemble de fichiers avec du texte markdown, qui est ensuite converti en un site de documentation complet par un moteur, comme wintersmith. Ou un système wiki.
C'est très pratique : nous avons écrit le texte, puis une balise script s'ouvre et le code js du schéma y est décrit.
Qu'est-ce qui ne va pas encore ?
Ce dépôt m'a plu, mais ce n'est pas le seul exemple où un diagramme est dessiné à l'aide de code ou de représentation textuelle. (À la fin de l'article, il y aura des liens vers des projets et des articles que j'ai trouvés sur le thème du diagramme comme code.)
Et je ne suis pas le seul à corriger la documentation. Parfois, mes collègues y apportent aussi leur contribution - corriger un mot, modifier une description, insérer de nouvelles images.
C'est pourquoi j'aimerais voir le diagramme sous un format texte lisible et compréhensible, qui ne nécessiterait pas une longue formation. Parfois, il suffirait même de faire un simple copier-coller pour accélérer l'ajout d'un nouveau schéma.
Un autre collègue a également fait remarquer que le code, c'est bien, mais si l'on utilise une structure, tout peut être très rigoureux et expressif.
J'ai donc essayé de présenter le schéma comme un ensemble de plusieurs petits tableaux décrivant les nœuds, les liens, les groupes de nœuds, ainsi que la disposition des nœuds. À mon humble avis, cela s'est avéré plutôt pratique, bien sûr, chacun ses goûts.
Comment cela fonctionne-t-il en tant que tableau?
- Chaque nœud est décrit par un identifiant qui définit de manière unique le nœud.
- On peut également ajouter une icône au nœud, ou ajouter un texte.
- Entre deux nœuds, une relation peut être définie.
- Pour la relation sur le schéma, on peut définir une couleur, un texte.
- La direction de la relation est définie comme allant de la source vers la cible. La source et la cible sont spécifiées par les identifiants du nœud.
- Un ou plusieurs nœuds peuvent être ajoutés à un groupe.
- La relation peut également être spécifiée depuis un groupe et vers un groupe.
En utilisant ces règles simples, on obtient un schéma comme celui-ci. Simple? Tout à fait.
Il est décrit par le code js suivant. L'élément principal ici est l'objet elements. Dans lequel sont indiqués nodes — les nœuds, edges — les relations.
const elements = {
nodes: [ // décrivant les nœuds
{ id: 'client', type: 'smartphone', label: 'Application mobile'},
{ id: 'server', type: 'server', label: 'Serveur principal'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [ // indiquant les relations
{ source: 'client', target: 'server', label: 'demande' },
{ source: 'server', target: 'db1', label: 'demande' },
{ source: 'server', target: 'db2', label: 'demande' },
],
};
Diagram('scheme1', elements);
Bien sûr, je n'ai pas inventé le dessin du schéma, mais j'ai utilisé une bibliothèque. — un outil de visualisation très puissant. Je n'utilise qu'une fraction de ses capacités dans ma solution.
C'est clair, c'est un exemple simple. Peut-on le rendre plus complexe?
Oui, bien sûr. Pour spécifier les positions, nous utilisons positions, pour indiquer les groupes, nous définissons une liste de groupes dans groups, et pour les éléments eux-mêmes, l'attribut group.
Et voici le code :
<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>
Un tel schéma d'un côté — c'est presque deux écrans de code sur un ordinateur portable, de l'autre la structure de type json permet de remplir toutes les données par analogie, rapidement et par copier-coller.
Et pourquoi les positions sont-elles séparées des nœuds?
C'est plus pratique. D'abord, nous indiquons les nœuds. Ensuite, nous pouvons indiquer un ou deux groupes et les placer dans les nœuds. Puis, nous définissons les connexions. Et enfin, lorsque les objets principaux et leurs relations sont établis, nous nous occupons de la disposition de ces objets sur le schéma. Ou inversement.
Peut-on le faire sans les positions ?
On peut sans les positions. Mais cela sera un peu désordonné, dans les exemples on peut voir une telle option. C'est dû au fait que pour cytoscape, il existe un algorithme de disposition des nœuds. , qui prend également en compte la présence de groupes. L'indication des positions rend le schéma plus contrôlable, mais à l'étape du premier croquis du schéma, on peut s'en passer.
Les positions peuvent également être indiquées dans le style de Bataille navale. C'est-à-dire qu'un nœud se trouve en a1, et un autre en d5. Cela aide particulièrement que cytoscape crée des objets sur le canvas de manière mobile, c'est-à-dire que nous pouvons les déplacer, voir différentes options de disposition, puis fixer dans le code la disposition des éléments qui nous plaît.
En gros, c'est clair. Peut-on essayer ?
Bien sûr, pour créer rapidement des schémas, j'ai fait un petit , qui met à jour le schéma et conserve la dernière version dans le navigateur (dans localStorage).
Vous avez essayé ? On peut maintenant l'ajouter à votre page.
Alors encore une fois :
1. Nous intégrons le script
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Ajoutons au code 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. corrigeons le code selon le schéma que nous désirons (je pense que c'est plus simple que de dessiner une chouette 🙂
Encore plus de détails sur sur GitHub.
Quel est le résultat ?
J'ai atteint mes objectifs — intégrer des schémas en ligne dans la documentation, le format est assez simple et compréhensible. Cela ne conviendra pas pour des super schémas, mais pour de petits schémas qui expliquent la structure des connexions, c'est très bien. On peut toujours le modifier rapidement et changer quelque chose au fil du temps. Oui, et les collègues peuvent eux-mêmes modifier dans le doc, au moins les légendes des objets sans trop de formation. ))
Que peut-on améliorer ?
Il y a bien sûr de nombreuses options. Ajouter des icônes supplémentaires (toutes les existantes sont intégrées en ligne dans le script). Choisir un ensemble d'icônes plus expressif. Ajouter la possibilité de définir le style des lignes de connexion. Ajouter une image de fond.
Qu'en pensez-vous ?
J'ai déjà quelques idées à mettre en œuvre dans les issues, n'hésitez pas à ajouter les vôtres dans les commentaires.
Ma solution est certainement applicable à un éventail restreint de tâches, et vous pourriez trouver un outil de dessin de diagrammes plus pratique simplement en les codant — comme on dit : ‘montrez-moi votre diagramme sous forme de code’
- (9 types de graphiques éditeur en ligne)
- Et si vous aimez les schémas super détaillés et complexes — ce projet va définitivement vous émerveiller :
Source : habr.com
