In den letzten Jahren begann ich mich mehr mit Dokumentation zu beschäftigen. Schreiben Sie einen erklärenden Text darüber, wie dieses oder jenes System funktioniert - im Allgemeinen ist es ganz einfach. Zeichnen Sie ein Diagramm, in dem alle Schlüsselobjekte angezeigt werden. Die Beziehung zwischen diesen Objekten ist ebenfalls recht einfach.Der problematischste Moment ist jedoch, diese Dokumentation auf dem neuesten Stand zu halten. Und okay, der Text, aber die Diagramme ... Weil Die gesamte Dokumentation ist online, d. h. Im HTML-Format werden dann GIF / JPEG / PNG-Bilder an den Text angehängt, auf dem die Diagramme tatsächlich dargestellt sind. Und die Programme werden in verschiedenen Programmen wie Visio oder Online-Diensten a la draw.io erstellt. Anschließend exportieren Sie das Diagramm in ein Grafikformat und hängen es an HTML an. Alles ist einfach.Was ist das Problem?Schemata sind normalerweise einfach. Genauer gesagt, nicht sehr kompliziert. Ja, die Anzahl der Objekte beträgt zehn oder zwei, die Anzahl der Verbindungen ist ungefähr gleich. Plus Unterschriften, einige Bezeichnungen. Einfache Schemata können in Worten beschrieben werden, aber zu komplex, hmm ... (s) "Sie verstehen nicht, Sir." Es gibt viele Schemata, deren Änderungen periodisch, periodisch vorgenommen werden müssen, d. H. ständig, weil Sie folgen der Entwicklung unserer Produkte.Sie können den HTML-Dienst einbetten. Hast du es versucht?Ja natürlich. Zum Beispiel mag ich gliffy.com-Grafiken. Für Änderungen müssen Sie sich jedoch an einen Drittanbieter wenden, um diese zu bearbeiten. Und es ist schwieriger, Änderungsanträge an einen Kollegen zu delegieren.Was zu tun ist?Kürzlich bin ich auf einem Github in Empfehlungen auf das Repository github.com/RaoulMeyer/diagram-as-code gestoßen. Diagramm als Code. Jene. Wir beschreiben auf js die Schaltung, die wir brauchen. Wir schreiben dieses js direkt in das gleiche HTML, in dem sich der andere Dokumentationstext befindet.Übrigens, aber ich schreibe überhaupt keine Dokumentation in HTML. In der Regel handelt es sich bei der Dokumentation um eine Reihe von Dateien mit Markdown-Text, die dann von einer Engine, z. B. dem Winterschmied, in eine vollwertige Dokumentationssite konvertiert werden. Oder ein Wiki-System.Es stellt sich als sehr praktisch heraus: Hier haben wir den Text geschrieben, dann wird das Skript-Tag geöffnet und der js-Code der Schaltung darin beschrieben.Was ist wieder los?Ich mochte dieses Repository, aber dies ist nicht das einzige Beispiel, wenn ein Diagramm mit Code oder einer Textansicht gezeichnet wird. (Am Ende des Artikels befinden sich Links zu Projekten und Artikeln, die im Themendiagramm als Code gegoogelt wurden.)Und ich bin nicht der einzige, der die Dokumentation korrigiert. Manchmal leisten auch Kollegen einen Beitrag - korrigieren Sie das Wort, ändern Sie die Beschreibung, fügen Sie neue Bilder ein. Daher möchte ich das Diagramm in einem lesbaren, verständlichen Textformat sehen, das lange nicht untersucht werden müsste. An manchen Stellen ist es sogar einfach, Copy-Paste zu erstellen, um das Hinzufügen eines neuen Schemas zu beschleunigen. Und ein anderer Kollege bemerkte, dass der Code natürlich gut ist, aber wenn Sie die Struktur verwenden, kann alles sehr streng und ausdrucksstark sein.Daher habe ich versucht, das Schema als eine Reihe mehrerer kleiner Arrays darzustellen, die Knoten, Verbindungen, Gruppen von Knoten sowie die Position von Knoten beschreiben. Es stellte sich meiner bescheidenen Meinung nach recht praktisch heraus, obwohl natürlich der Geschmack und die Farbe ...Wie ist die Tabelle im Array?- Jeder Knoten wird durch eine Kennung beschrieben, die den Knoten eindeutig identifiziert.
- Sie können dem Knoten auch ein Symbol hinzufügen und eine Inschrift hinzufügen.
- Sie können eine Beziehung zwischen zwei Knoten angeben.
- Für die Kommunikation über das Schema können Sie die Farbe und die Inschrift festlegen.
- Die Kommunikationsrichtung wird als von der Quelle zum Ziel definiert. Die Quelle und das Ziel werden durch die Kennungen des Knotens angezeigt.
- Ein oder mehrere Knoten können der Gruppe hinzugefügt werden.
- Ein Link kann auch von einer Gruppe zu einer Gruppe angegeben werden.
Mit diesen einfachen Regeln erhalten wir ein solches Schema. Einfach? Ganz.
Und es wird durch den folgenden js-Code beschrieben. Die Hauptsache hier ist das Elementobjekt. In welchen Knoten - Knoten, Kanten - Verbindungen werden angezeigt. 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);
Natürlich habe ich nicht daran gedacht, die Schaltung selbst zu zeichnen, aber ich habe die Bibliothek cytoscape.js verwendet , ein sehr leistungsfähiges Visualisierungstool. Toliku Möglichkeiten, die ich in meiner Entscheidung nur nutze. Dies ist eindeutig ein einfaches Beispiel. Kann es komplizierter sein?Ja, bitte. Um Positionen anzuzeigen - wir verwenden Positionen, um Gruppen anzuzeigen - geben wir eine Liste von Gruppen in Gruppen an, und die Elemente selbst haben ein Gruppenattribut.
Und das ist der 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>
Ein solches Schema besteht einerseits aus fast ein paar Codebildschirmen auf dem Laptop, andererseits ermöglicht Ihnen die a la json-Struktur, alle Daten analog und schnell einzugeben und sie zu kopieren und einzufügen.Und warum werden die Positionen getrennt von den Knoten entfernt?Das ist bequemer. Zuerst geben wir Knoten an. Dann können wir einige Gruppen angeben und sie in Knoten angeben. Dann bezeichnen wir die Verbindung. Und wenn dann die Hauptobjekte und die Verbindungen zwischen ihnen sind, nehmen wir die Position dieser Objekte im Diagramm auf. Oder umgekehrt.Ist es ohne Positionen möglich?Es ist ohne Positionen möglich. Aber es wird ein wenig zerknittert sein, in den Beispielen können Sie diese Option sehen. Dies liegt an der Tatsache, dass es für Cytoscape einen Algorithmus für die Position von fcose- Knoten gibt, die auch die Anwesenheit von Gruppen berücksichtigt. Die Angabe von Positionen macht das Schema kontrollierbarer, aber in der Phase des ersten Entwurfs des Schemas ist es ohne Positionen möglich.Außerdem können Positionen im Stil einer Seeschlacht festgelegt werden. Jene. Ein Knoten befindet sich in a1 und der andere in d5. Es hilft insbesondere, dass Cytoscape Objekte auf Leinwand beweglich bildet, d.h. Wir können sie verschieben, verschiedene Layoutoptionen betrachten und dann im Code Ihre bevorzugte Anordnung von Elementen festlegen.Im Allgemeinen verstehe ich. Sie können auch versuchen? Um schnell Schemata zu erstellen, habe ich mir natürlich einen kleinen Editor erstellt , der das Schema selbst aktualisiert und die letzte Option im Browser (in localStorage) speichert.Hast du es versucht? Sie können jetzt zu Ihrer Seite hinzufügen.Dann nochmal:1. Wir verbinden ein Skript<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Fügen Sie dem HTML-Code hinzu<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. Bearbeiten Sie den Code nach dem von uns benötigten Schema (ich denke, es ist einfacher als eine Eule zu zeichnen :)Weitere Details finden Sie auf der Projektseite im Github.Was ist das Ergebnis?Ich habe meine Ziele erreicht - um der Dokumentation Inline-Schemata hinzuzufügen, ist das Format recht einfach und unkompliziert. Es ist nicht für Superschemata geeignet, aber für kleine Schaltkreise, die die Struktur von Verbindungen erklären, ist es sogar nichts. Sie können das Problem jederzeit schnell beheben und im Laufe der Zeit ändern. Ja, und Kollegen können etwas im Dock selbst korrigieren, zumindest Signaturen für Objekte ohne spezielle Schulung.))Was kann verbessert werden?Es gibt natürlich viele Möglichkeiten. Fügen Sie zusätzliche Symbole hinzu (alle verfügbaren werden inline zum Skript hinzugefügt). Wählen Sie eine ausdrucksstärkere Reihe von Symbolen. Ermöglichen Sie die Angabe eines Linklinienstils. Hintergrundbild hinzufügen.Was denken Sie? Ich habe bereits einige Ideen für die Implementierung in Problemen, Sie fügen Ihre auch in den Kommentaren hinzu.Meine Lösung ist definitiv auf einen engen Bereich von Aufgaben anwendbar, und vielleicht finden Sie ein bequemeres Werkzeug zum Zeichnen von Diagrammen, indem Sie sie einfach codieren - wie sie sagen: "Zeigen Sie mir Ihr Diagramm als Code".- Gute Auswahl
- Posh Service (9 Arten von Diagrammen Online-Editor)
- Natürlich mermaid.js
- Und wenn Sie sehr detaillierte und komplexe Schemata mögen, wird Sie dieses Projekt auf jeden Fall begeistern: go.drawthe.net