ProHoster > Blog > Pentadbiran > Gambarajah rangkaian sebagai kod / Gambarajah rangkaian sebagai kod

Gambarajah rangkaian sebagai kod / Gambarajah rangkaian sebagai kod

Dalam beberapa tahun kebelakangan ini saya telah menjadi lebih terlibat dalam dokumentasi. Menulis teks penjelasan tentang cara sistem ini atau itu berfungsi secara amnya agak mudah. Melukis rajah yang akan memaparkan semua objek utama dan hubungan antara objek ini juga agak mudah.

Tetapi aspek yang paling bermasalah ialah memastikan dokumentasi ini dikemas kini. Dan teksnya akan baik, tetapi gambar rajah... Kerana... semua dokumentasi adalah dalam talian, i.e. dalam format html, maka teks disertakan dengan gambar gif/jpeg/png, yang sebenarnya menunjukkan gambar rajah. Dan gambar rajah dilukis dalam pelbagai program seperti Visio atau perkhidmatan dalam talian ala draw.io. Kemudian anda mengeksport rajah ke dalam format grafik dan melampirkannya pada html. Mudah sahaja.

Apakah masalahnya?

Skim biasanya mudah. Lebih tepat lagi, tidak terlalu rumit. Ya, bilangan objek adalah sedozen atau dua, bilangan sambungan adalah lebih kurang sama. Ditambah tandatangan, beberapa jawatan. Skema mudah boleh diterangkan dalam perkataan, tetapi terlalu kompleks, ehem... (c) "mereka tidak akan faham, tuan." Terdapat banyak skim, perubahan perlu dibuat kepada mereka secara berkala, episodik, i.e. secara berterusan, kerana mereka mengikuti perkembangan produk kami.

Anda boleh membenamkan html perkhidmatan. Sudahkah anda mencubanya?

Ya pasti. Sebagai contoh, saya suka grafik daripada gliffy.com. Tetapi untuk membuat perubahan, anda perlu pergi ke perkhidmatan pihak ketiga dan mengedit di sana. Dan lebih sukar untuk mewakilkan pembetulan kepada rakan sekerja.

Apa yang perlu dilakukan?

Baru-baru ini saya menjumpai repositori di Github dalam cadangan github.com/RaoulMeyer/diagram-as-code. Gambar rajah sebagai kod. Itu. kami menerangkan litar yang kami perlukan dalam js. Kami menulis js ini terus dalam html yang sama di mana teks dokumentasi lain berada.

Dengan cara ini, saya menulis dokumentasi bukan sepenuhnya dalam html. Biasanya, dokumentasi ialah satu set fail dengan teks penurunan nilai, yang kemudiannya ditukar menjadi tapak dokumentasi lengkap oleh sesetengah enjin, contohnya wintersmith. Atau sistem wiki.

Ternyata sangat mudah: kami telah menulis teks, kemudian tag skrip dibuka dan kod JS skema diterangkan di dalamnya.

apa salah lagi?

Saya suka repositori ini, tetapi ini bukan satu-satunya contoh di mana gambar rajah dilukis menggunakan kod atau perwakilan teks. (Pada penghujung artikel akan terdapat pautan ke projek dan artikel yang saya Google pada gambarajah topik sebagai kod.)

Dan saya bukan seorang sahaja yang mengedit dokumentasi. Kadang-kadang rakan sekerja turut menyumbang - betulkan perkataan, tukar penerangan, masukkan gambar baharu. 

Oleh itu, saya ingin melihat rajah dalam format teks yang boleh dibaca dan difahami yang tidak memerlukan keluk pembelajaran yang panjang. Dan di sesetengah tempat, anda juga boleh salin-tampal untuk mempercepatkan menambah litar baharu. 

Dan rakan sekerja lain menyatakan bahawa kod, sudah tentu, bagus, tetapi jika anda menggunakan struktur, semuanya boleh menjadi sangat ketat dan ekspresif.

Oleh itu, saya cuba membayangkan rajah sebagai satu set beberapa tatasusunan kecil yang menerangkan nod, sambungan, kumpulan nod, serta lokasi nod. Ternyata, pada pendapat saya yang sederhana, agak mudah, walaupun, tentu saja, rasa dan warna...

Bagaimanakah ini carta dalam tatasusunan?

  • Setiap nod diterangkan oleh pengecam yang mengenal pasti nod secara unik.
  • Anda juga boleh menambah ikon pada nod dan menambah inskripsi.
  • Anda boleh menentukan hubungan antara dua nod.
  • Untuk komunikasi pada rajah, anda boleh menetapkan warna dan inskripsi.
  • Arah komunikasi ditakrifkan sebagai dari sumber ke sasaran. Dan sumber dan sasaran ditunjukkan oleh pengecam nod.
  • Satu atau lebih nod boleh ditambah pada kumpulan.
  • Perhubungan juga boleh ditentukan kedua-dua daripada kumpulan dan kepada kumpulan.

Menggunakan peraturan mudah ini, kita mendapat rajah berikut. Cuma? cukup.

Gambarajah rangkaian sebagai kod / Gambarajah rangkaian sebagai kod

Dan ia diterangkan oleh kod js berikut. Perkara utama di sini ialah objek elemen. Di mana nod ditunjukkan - nod, tepi - sambungan.
 

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

Sudah tentu, saya tidak menghasilkan lukisan litar itu sendiri, tetapi menggunakan perpustakaan cytoscape.js ialah alat visualisasi yang sangat berkuasa. Saya hanya menggunakan sebahagian kecil daripada kemungkinan dalam penyelesaian saya. 

Okay, ini contoh mudah. Bolehkah ia menjadi lebih rumit?

Ya sila. Untuk menunjukkan kedudukan, kami menggunakan kedudukan, untuk menunjukkan kumpulan, kami menunjukkan senarai kumpulan dalam kumpulan, dan elemen itu sendiri mempunyai atribut kumpulan.

Gambarajah rangkaian sebagai kod / Gambarajah rangkaian sebagai kod

Dan ini adalah kodnya:

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

Di satu pihak, skema sedemikian adalah hampir beberapa skrin kod pada komputer riba, sebaliknya, struktur a la json membolehkan anda mengisi semua data dengan analogi, dengan cepat dan anda boleh menyalin-tampal.

Mengapa kedudukan diletakkan secara berasingan daripada nod?

Ia lebih selesa. Mula-mula kita tentukan nod. Kemudian kita boleh menentukan beberapa kumpulan dan menunjukkannya dalam nod. Kemudian kami menetapkan sambungan. Dan hanya selepas itu, apabila objek utama dan sambungan di antara mereka ada, kami mengambil lokasi objek ini pada rajah. Atau sebaliknya.

Adakah boleh tanpa jawatan?

Ia boleh dilakukan tanpa jawatan. Tetapi ia akan menjadi sedikit renyuk; anda boleh melihat pilihan ini dalam contoh. Ini disebabkan oleh fakta bahawa terdapat algoritma untuk lokasi nod untuk cytoscape fcose, yang juga mengambil kira kehadiran kumpulan. Menentukan kedudukan menjadikan rajah lebih terkawal, tetapi pada peringkat draf pertama rajah ia boleh dilakukan tanpa kedudukan.

Kedudukan juga boleh ditentukan dalam gaya Battleship. Itu. satu nod terletak di a1, dan satu lagi di d5. Ia terutamanya membantu bahawa cytoscape menjadikan objek pada kanvas boleh dialihkan, i.e. kita boleh mengalihkannya, melihat pilihan susun atur yang berbeza, dan kemudian membetulkan susunan elemen yang kita suka dalam kod.

Secara umum, ia boleh difahami. Anda juga boleh mencuba?
 
Sudah tentu, untuk membuat litar dengan cepat, saya menjadikan diri saya kecil editor itu, yang dengan sendirinya mengemas kini skema dan menyimpan versi terkini dalam penyemak imbas (dalam localStorage).

Sudahkah anda mencubanya? Anda kini boleh menambahkannya ke halaman anda.

Kemudian sekali lagi:

1. Menyambung skrip

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

2. Tambahkan kod pada 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. kami mengedit kod ke rajah yang kami perlukan (saya fikir ia lebih mudah daripada melukis burung hantu :)

Butiran lanjut di halaman projek pada github.

Hasilnya?

Saya mencapai matlamat saya - untuk menambah gambar rajah sebaris pada dokumentasi, formatnya agak mudah dan boleh difahami. Ia tidak sesuai untuk litar super, tetapi untuk litar kecil yang menerangkan struktur sambungan, ia tidak mengapa. Anda sentiasa boleh mengubah suai dan mengubah sesuatu dari semasa ke semasa. Ya, dan rakan sekerja boleh membetulkan sesuatu dalam dok sendiri, sekurang-kurangnya kapsyen untuk objek, tanpa latihan khas))

Apa yang boleh diperbaiki?

Sudah tentu, terdapat banyak pilihan di sini. Tambahkan ikon tambahan (semua yang sedia ada ditambah sebaris pada skrip). Pilih set ikon yang lebih ekspresif. Jadikan ia mungkin untuk menentukan gaya talian sambungan. Tambah imej latar belakang.

Apa pendapat kamu?
 
Saya sudah mempunyai beberapa idea untuk pelaksanaan dalam isu, anda juga boleh menambah idea anda dalam ulasan.

Penyelesaian saya pastinya boleh digunakan dalam pelbagai masalah yang sempit, dan mungkin anda akan menemui alat yang lebih mudah untuk melukis gambar rajah dengan hanya mengekodnya - seperti yang mereka katakan 'tunjukkan gambar rajah anda sebagai kod'

  1. Pilihan yang bagus
  2. Perkhidmatan yang hebat (9 jenis editor dalam talian carta)
  3. Sudah tentu, mermaid.js
  4. Dan jika anda suka gambar rajah yang sangat terperinci dan kompleks, maka anda pasti akan mengagumi projek ini: go.drawthe.net

Sumber: www.habr.com

Tambah komen