コードとしてのネットワーク図 / コードとしてのネットワーク図

ここ数年、私はドキュメンテーションにもっと関わるようになりました。 特定のシステムがどのように動作するかについての説明文を書くのは、一般に非常に簡単です。 すべての主要なオブジェクトとこれらのオブジェクト間の接続を表示する図を描くことも非常に簡単です。

しかし、最も問題となるのは、このドキュメントを最新の状態に保つことです。 そして、テキストは大丈夫ですが、図は...なぜなら... すべてのドキュメントはオンラインです。つまり、 HTML 形式の場合、テキストには実際に図を示す gif/jpeg/png 画像が付いています。 また、図は Visio やdraw.io などのオンライン サービスなどのさまざまなプログラムで描画されます。 次に、図をグラフィック形式にエクスポートし、HTML に添付します。 それは簡単です。

何が問題なの？

通常、スキームは単純です。 より正確に言えば、それほど複雑ではありません。 はい、オブジェクトの数は XNUMX ～ XNUMX 個ですが、接続の数はほぼ同じです。 さらに署名といくつかの指定。 単純な計画は言葉で説明できますが、複雑すぎる計画は、まあ... (c) 「彼らは理解できないでしょう、先生。」 多くのスキームがあり、それらに定期的、一時的に変更を加える必要があります。 常に、なぜなら彼らは私たちの製品の開発をフォローしています。

サービスのHTMLを埋め込むことができます。 試してみましたか？

はい、確かに。 たとえば、私は giffy.com のグラフィックが好きです。 ただし、変更を加えるには、サードパーティのサービスにアクセスして、そこで編集する必要があります。 そして、修正を同僚に委任するのはさらに困難です。

何をしますか？

最近、推奨事項で Github のリポジトリを見つけました。 github.com/RaoulMeyer/diagram-as-code。 コードとしての図。 それらの。 必要な回路をjsで記述します。 この JS は、他のドキュメント テキストと同じ HTML 内に直接記述します。

ちなみに、私はドキュメントをすべて HTML で書いているわけではありません。 通常、ドキュメントはマークダウン テキストを含む一連のファイルであり、Wintersmith などのエンジンによって本格的なドキュメント サイトに変換されます。 あるいはウィキシステム。

これは非常に便利であることがわかりました。テキストを記述した後、script タグが開き、その中にスキームの JS コードが記述されます。

また何が悪いのですか？

私はこのリポジトリが気に入りましたが、コードまたはテキスト表現を使用して図が描画される例はこれだけではありません。 (記事の最後には、トピック図をコードとして Google 検索したプロジェクトと記事へのリンクがあります。)

ドキュメントを編集しているのは私だけではありません。 同僚も時々、単語を修正したり、説明を変更したり、新しい写真を挿入したりして貢献します。 

したがって、長い学習曲線を必要とせずに、読みやすく理解できるテキスト形式で図を表示したいと考えています。 また、場所によっては、コピー＆ペーストするだけで新しい回路の追加を高速化することもできます。 

また、別の同僚は、コードはもちろん良いものですが、構造を使用すると、すべてが非常に厳密で表現力豊かになる可能性があると指摘しました。

したがって、私は図を、ノード、接続、ノードのグループ、およびノー​​ドの位置を記述するいくつかの小さな配列のセットとして想像しようとしました。 私の謙虚な意見では、それは非常に便利であることがわかりましたが、もちろん味と色は...

これはどのようにして配列内のグラフになるのでしょうか?

• 各ノードは、ノードを一意に識別する識別子によって記述されます。
• ノードにアイコンを追加したり、碑文を追加したりすることもできます。
• XNUMX つのノード間の関係を指定できます。
• 図上でのコミュニケーションは、色や表記を設定できます。
• 通信の方向は、ソースからターゲットへとして定義されます。 そして、ソースとターゲットはノード識別子によって示されます。
• XNUMX つ以上のノードをグループに追加できます。
• グループからの関係とグループへの関係の両方を指定することもできます。

これらの単純なルールを使用すると、次の図が得られます。 ただ？ とても。

そして以下のjsコードで記述します。 ここで重要なのは要素オブジェクトです。 どのノードが示されているか - ノード、エッジ - 接続。
 

  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);

もちろん回路図は自分で考えたわけではなく、ライブラリを使用しました。 サイトスケープ.js は非常に強力な視覚化ツールです。 私のソリューションでは可能性のほんの一部しか使用しません。 

これは簡単な例です。 もっと複雑にすることはできますか?

はい、お願いします。 位置を示すには、position を使用し、グループを示すには、グループ内のグループのリストを示します。要素自体はグループ属性を持ちます。

そしてこれがコードです:

<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>

一方では、このようなスキームはラップトップ上でほぼ数画面のコードに相当しますが、他方では、json の構造により、すべてのデータを類推して素早く入力でき、コピーアンドペーストすることができます。

ポジションがノードとは別に配置されるのはなぜですか?

より快適です。 まずノードを指定します。 次に、いくつかのグループを指定し、それらをノードで示すことができます。 次に接続を指定します。 そして、主要なオブジェクトとそれらの間の接続が存在する場合にのみ、図上でこれらのオブジェクトの位置を取得します。 あるいはその逆も同様です。

ポジションなしでも可能ですか？

ポジションがなくても可能です。 ただし、少しくしゃくしゃになります。このオプションは例で確認できます。 これは、cytoscape のノードの位置を決定するアルゴリズムがあるためです。 フコース、グループの存在も考慮されます。 位置を指定すると図を制御しやすくなりますが、図の初稿の段階では位置を指定しなくても可能です。

戦艦スタイルでも位置を指定できます。 それらの。 1 つのノードは a5 にあり、もう XNUMX つは dXNUMX にあります。 cytoscape がキャンバス上のオブジェクトを移動可能にするのは特に役立ちます。 それらを移動したり、さまざまなレイアウト オプションを確認したり、コード内で気に入った要素の配置を修正したりできます。

一般的には理解できます。 あなたも試してみませんか？
 
もちろん、すぐに回路を作成するために、自分自身を小さなものにしました редактор、それ自体がスキーマを更新し、最新バージョンをブラウザー (localStorage) に保存します。

試してみましたか？ これでページに追加できるようになりました。

それからまた：

1. スクリプトの接続

<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>

2. 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. 必要な図に合わせてコードを編集します (フクロウを描くよりも簡単だと思います:)

詳細については、 プロジェクトページ github で。

その結果は？

ドキュメントにインライン図を追加するという目標は達成できました。形式は非常にシンプルで理解しやすいものです。 スーパー回路には適していませんが、接続の構造を説明する小さな回路にはまったく問題ありません。 いつでもすぐに調整したり、時間をかけて変更したりできます。 はい、同僚はドック内の何か、少なくともオブジェクトのキャプションを特別な訓練なしで自分で修正できます))

何を改善できますか？

もちろん、ここには多くのオプションがあります。 追加のアイコンを追加します (既存のアイコンはすべてスクリプトにインラインで追加されます)。 より表現力豊かなアイコンのセットを選択してください。 接続線のスタイルを指定できるようにしました。 背景画像を追加します。

どう思いますか？
 
すでに課題に実装するためのアイデアがいくつかあります。コメントにアイデアを追加することもできます。

• リポジトリ
• 例
• オンラインエディター

私の解決策は間違いなく狭い範囲の問題に適用できます。おそらく、「コードとして図を見せてください」と言われるように、単にコーディングするだけで図を描画するためのより便利なツールが見つかるでしょう。

1. 良い選択
2. 素晴らしいサービス (9種類のチャートオンラインエディター)
3. もちろん、mermaid.js
4. 非常に詳細で複雑な図が好きなら、間違いなくこのプロジェクトを賞賛するでしょう。 go.drawthe.net

出所： habr.com