ProHoster > blog > administrasi > Diagram jaringan sebagai kode / Diagram jaringan sebagai kode

Diagram jaringan sebagai kode / Diagram jaringan sebagai kode

Dalam beberapa tahun terakhir saya menjadi lebih terlibat dalam dokumentasi. Menulis teks penjelasan tentang cara kerja sistem tertentu umumnya cukup sederhana. Menggambar diagram yang akan menampilkan semua objek utama dan hubungan antar objek tersebut juga cukup mudah.

Namun aspek yang paling bermasalah adalah menjaga dokumentasi ini tetap mutakhir. Dan teksnya akan baik-baik saja, tetapi diagramnya... Karena... semua dokumentasi online, mis. dalam format html, kemudian teks disertai gambar gif/jpeg/png, yang sebenarnya menunjukkan diagram. Dan diagram digambar dalam berbagai program seperti Visio atau layanan online ala draw.io. Kemudian Anda mengekspor diagram ke dalam format grafik dan melampirkannya ke html. Itu mudah.

Apa masalahnya?

Skemanya biasanya sederhana. Lebih tepatnya, tidak terlalu rumit. Ya, jumlah bendanya selusin atau dua, jumlah sambungannya kurang lebih sama. Ditambah tanda tangan, beberapa sebutan. Skema sederhana bisa dijelaskan dengan kata-kata, tapi skema yang terlalu rumit, ahem... (c) β€œmereka tidak akan mengerti, Pak.” Ada banyak skema, perlu dilakukan perubahan secara berkala, episodik, yaitu. terus-menerus, karena mereka mengikuti perkembangan produk kita.

Anda dapat menyematkan html layanan. Sudahkah Anda mencobanya?

Ya tentu. Misalnya, saya suka grafik dari gliffy.com. Namun untuk melakukan perubahan, Anda perlu pergi ke layanan pihak ketiga dan mengedit di sana. Dan lebih sulit mendelegasikan koreksi kepada rekan kerja.

Apa yang harus dilakukan?

Baru-baru ini saya menemukan repositori di Github di rekomendasi github.com/RaoulMeyer/diagram-as-code. Diagram sebagai kode. Itu. kami menggambarkan sirkuit yang kami butuhkan di js. Kami menulis js ini langsung di html yang sama dengan teks dokumentasi lainnya.

Omong-omong, saya menulis dokumentasi tidak seluruhnya dalam html. Biasanya, dokumentasi adalah sekumpulan file dengan teks penurunan harga, yang kemudian diubah menjadi situs dokumentasi lengkap oleh beberapa mesin, misalnya wintersmith. Atau sistem wiki.

Ternyata sangat nyaman: kita telah menulis teksnya, kemudian tag skrip terbuka dan kode JS dari skema dijelaskan di dalamnya.

Ada apa lagi?

Saya menyukai repositori ini, tapi ini bukan satu-satunya contoh di mana diagram digambar menggunakan kode atau representasi teks. (Di akhir artikel akan ada link ke proyek dan artikel yang saya cari di Google tentang diagram topik sebagai kode.)

Dan saya bukan satu-satunya yang mengedit dokumentasinya. Terkadang rekan kerja juga berkontribusi - mengoreksi kata, mengubah deskripsi, menyisipkan gambar baru. 

Oleh karena itu, saya ingin melihat diagram dalam format teks yang mudah dibaca dan dipahami serta tidak memerlukan kurva pembelajaran yang panjang. Dan di beberapa tempat Anda bahkan dapat menyalin-menempel untuk mempercepat penambahan sirkuit baru. 

Dan rekan lainnya mencatat bahwa kode itu, tentu saja, bagus, tetapi jika Anda menggunakan struktur, semuanya bisa menjadi sangat ketat dan ekspresif.

Oleh karena itu, saya mencoba membayangkan diagram sebagai kumpulan beberapa array kecil yang menggambarkan node, koneksi, kelompok node, serta lokasi node. Ternyata, menurut pendapat saya, cukup nyaman, meskipun tentu saja rasa dan warnanya...

Bagaimana ini bagan dalam array?

  • Setiap node dijelaskan oleh pengidentifikasi yang secara unik mengidentifikasi node tersebut.
  • Anda juga dapat menambahkan ikon ke node dan menambahkan tulisan.
  • Anda dapat menentukan hubungan antara dua node.
  • Untuk komunikasi pada diagram, Anda dapat mengatur warna dan tulisan.
  • Arah komunikasi didefinisikan dari sumber ke sasaran. Dan sumber dan target ditunjukkan oleh pengidentifikasi node.
  • Satu atau lebih node dapat ditambahkan ke grup.
  • Hubungannya juga dapat ditentukan baik dari grup maupun ke grup.

Dengan menggunakan aturan sederhana ini, kita mendapatkan diagram berikut. Hanya? Lumayan.

Diagram jaringan sebagai kode / Diagram jaringan sebagai kode

Dan itu dijelaskan oleh kode js berikut. Hal utama di sini adalah elemen obyek. Di mana node ditunjukkan - node, tepi - koneksi.
 

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

Tentu saja, saya tidak membuat gambar sirkuitnya sendiri, tetapi menggunakan perpustakaan sitoscape.js adalah alat visualisasi yang sangat kuat. Saya hanya menggunakan sebagian kecil dari kemungkinan dalam solusi saya. 

Oke, ini adalah contoh sederhana. Bisakah ini menjadi lebih rumit?

Ya silahkan. Untuk menunjukkan posisi, kami menggunakan posisi, untuk menunjukkan grup, kami menunjukkan daftar grup dalam grup, dan elemen itu sendiri memiliki atribut grup.

Diagram jaringan sebagai kode / Diagram jaringan sebagai kode

Dan ini kodenya:

<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 sisi, skema seperti itu hampir beberapa layar kode di laptop, di sisi lain, struktur ala json memungkinkan Anda mengisi semua data dengan analogi, dengan cepat dan Anda dapat menyalin-menempel.

Mengapa posisi ditempatkan terpisah dari node?

Ini lebih nyaman. Pertama kita tentukan node. Kemudian kita dapat menentukan beberapa grup dan menunjukkannya dalam node. Lalu kami menentukan koneksinya. Dan baru kemudian, ketika objek utama dan hubungan di antara mereka ada, kita mengambil lokasi objek-objek tersebut pada diagram. Atau sebaliknya.

Apakah mungkin tanpa posisi?

Hal ini dimungkinkan tanpa posisi. Tapi itu akan sedikit kusut, Anda bisa melihat opsi ini di contoh. Hal ini disebabkan adanya algoritma lokasi node untuk cytoscape fcose, yang juga memperhitungkan keberadaan kelompok. Menentukan posisi membuat diagram lebih mudah dikontrol, tetapi pada tahap draf pertama diagram, hal ini dimungkinkan tanpa posisi.

Posisi juga dapat ditentukan dalam gaya Battleship. Itu. satu node terletak di a1, dan node lainnya di d5. Hal ini terutama membantu bahwa cytoscape membuat objek di kanvas dapat dipindahkan, mis. kita dapat memindahkannya, melihat opsi tata letak yang berbeda, dan kemudian memperbaiki susunan elemen yang kita suka dalam kode.

Secara umum, hal ini dapat dimengerti. Anda juga bisa mencoba?
 
Tentu saja, untuk membuat sirkuit dengan cepat, saya membuat sendiri yang kecil editornya, yang dengan sendirinya memperbarui skema dan menyimpan versi terbaru di browser (di Penyimpanan lokal).

Sudahkah Anda mencobanya? Anda sekarang dapat menambahkannya ke halaman Anda.

Kemudian lagi:

1. Menghubungkan skrip

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

2. Tambahkan kode ke 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. kita edit kodenya ke diagram yang kita butuhkan (menurut saya lebih mudah daripada menggambar burung hantu :)

Lebih detailnya di halaman proyek di github.

Hasilnya?

Saya mencapai tujuan saya - untuk menambahkan diagram sebaris ke dokumentasi, formatnya cukup sederhana dan mudah dimengerti. Ini tidak cocok untuk sirkuit super, tetapi untuk sirkuit kecil yang menjelaskan struktur koneksi, tidak masalah. Anda selalu dapat dengan cepat mengubah dan mengubah sesuatu seiring waktu. Ya, dan kolega dapat memperbaiki sendiri sesuatu di dok, setidaknya keterangan untuk objek, tanpa pelatihan khusus))

Apa yang bisa ditingkatkan?

Tentu saja ada banyak pilihan di sini. Tambahkan ikon tambahan (semua ikon yang sudah ada ditambahkan sebaris ke skrip). Pilih kumpulan ikon yang lebih ekspresif. Memungkinkan untuk menentukan gaya jalur koneksi. Tambahkan gambar latar belakang.

Bagaimana menurutmu?
 
Saya sudah punya beberapa ide untuk diterapkan dalam masalah, Anda juga bisa menambahkan ide Anda di komentar.

Solusi saya pasti dapat diterapkan dalam rentang masalah yang sempit, dan mungkin Anda akan menemukan alat yang lebih nyaman untuk menggambar diagram hanya dengan mengkodekannya - seperti yang dikatakan 'tunjukkan diagram Anda sebagai kode'

  1. pilihan yang bagus
  2. Layanan hebat (9 jenis editor grafik online)
  3. Tentu saja, putri duyung.js
  4. Dan jika Anda menyukai diagram yang sangat detail dan rumit, Anda pasti akan mengagumi proyek ini: pergi.drawthe.net

Sumber: www.habr.com

Tambah komentar