Dalam beberapa tahun terakhir, saya mulai lebih banyak berurusan dengan dokumentasi. Tulis teks penjelasan tentang cara kerja sistem ini atau itu - secara umum, ini cukup sederhana. Gambarlah diagram di mana semua objek kunci akan ditampilkan, hubungan antara objek-objek ini juga cukup mudah.Tapi momen paling problematis adalah memperbarui dokumentasi ini. Dan oke, teksnya, tapi diagramnya ... Karena semua dokumentasi online, mis. dalam format html, maka gambar gif / jpeg / png dilampirkan ke teks, di mana diagram sebenarnya digambarkan. Dan skema tersebut digambar dalam berbagai program seperti Visio atau layanan online ala draw.io. Kemudian Anda mengekspor diagram ke format grafik dan melampirkannya ke html. Semuanya sederhana.Apa masalahnya?Skema biasanya sederhana. Lebih tepatnya, tidak terlalu rumit. Ya, jumlah objek adalah sepuluh atau dua, jumlah koneksi hampir sama. Ditambah tanda tangan, beberapa sebutan. Skema sederhana dapat dijelaskan dengan kata-kata, tetapi terlalu rumit, hmm ... "mereka tidak mengerti, tuan." Ada banyak skema, perubahan di dalamnya perlu dilakukan secara berkala, berkala, yaitu. terus menerus, karena mereka mengikuti perkembangan produk kami.Anda dapat menyematkan layanan html. Sudahkah Anda mencobanya?Ya tentu saja. Misalnya, saya suka grafis gliffy.com. Tetapi untuk perubahan Anda harus pergi ke layanan pihak ketiga, di sana untuk mengedit. Dan lebih sulit untuk mendelegasikan amandemen kepada seorang kolega.Apa yang harus dilakukan?Baru-baru ini, di github, saya menemukan repositori github.com/RaoulMeyer/diagram-as-code dalam rekomendasi. Bagan sebagai kode. Itu kita jelaskan di sirkuit yang kita butuhkan. Kami menulis js ini langsung di html yang sama di mana teks dokumentasi lainnya.Ngomong-ngomong, tapi saya tidak menulis dokumentasi dalam html sama sekali. Biasanya, dokumentasi adalah sekumpulan file dengan teks penurunan harga, yang kemudian dikonversi menjadi situs dokumentasi lengkap oleh beberapa mesin, misalnya musim dingin. Atau sistem wiki.Ternyata sangat nyaman: di sini kita menulis teks, maka tag skrip dibuka dan kode js dari rangkaian dijelaskan di dalamnya.Apa yang salah lagi?Saya menyukai repositori ini, tetapi ini bukan satu-satunya contoh ketika diagram dibuat menggunakan kode atau tampilan teks. (Di akhir artikel akan ada tautan ke proyek dan artikel yang di-google-kan pada diagram topik sebagai kode.)Dan saya bukan satu-satunya yang mengoreksi dokumentasi. Terkadang kolega juga memberikan kontribusi - perbaiki kata, ubah deskripsi, masukkan gambar baru. Oleh karena itu, saya ingin melihat diagram dalam format teks yang dapat dimengerti, yang tidak harus dipelajari untuk waktu yang lama. Dan di tempat-tempat itu bahkan lebih mudah membuat salin-tempel untuk mempercepat penambahan skema baru. Dan kolega lain mencatat bahwa kode itu, tentu saja, bagus, tetapi jika Anda menggunakan strukturnya, semuanya bisa sangat ketat dan ekspresif.Oleh karena itu, saya mencoba menyajikan skema sebagai seperangkat beberapa array kecil yang menggambarkan node, koneksi, kelompok node, serta lokasi node. Ternyata, menurut pendapat saya yang sederhana, cukup nyaman, meskipun, tentu saja, rasa dan warnanya ...Bagaimana grafik dalam array?- Setiap node dijelaskan oleh pengidentifikasi yang secara unik mengidentifikasi node.
- Anda juga dapat menambahkan ikon ke simpul, menambahkan prasasti.
- Anda dapat menentukan hubungan antara dua node.
- Untuk komunikasi pada skema, Anda dapat mengatur warna, tulisan.
- Arah komunikasi didefinisikan sebagai dari sumber ke target. Dan sumber dan target ditunjukkan oleh pengidentifikasi node.
- Satu atau lebih node dapat ditambahkan ke grup.
- Tautan juga dapat ditentukan dari grup ke grup.
Dengan menggunakan aturan sederhana ini, kami mendapatkan skema seperti itu. Secara sederhana? Cukup.
Dan dijelaskan oleh kode js berikut. Hal utama di sini adalah elemen objek. Di mana node - node, tepi - koneksi ditunjukkan. 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 berpikir untuk menggambar sirkuit sendiri, tetapi saya menggunakan perpustakaan cytoscape.js , alat visualisasi yang sangat kuat. Peluang Toliku yang dalam keputusan saya hanya saya gunakan. Jelas, ini adalah contoh sederhana. Bisakah ini lebih rumit?Ya silahkan. Untuk menunjukkan posisi - kami menggunakan posisi, untuk menunjukkan grup - kami menentukan daftar grup dalam grup, dan elemen itu sendiri memiliki atribut grup.
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>
Skema semacam itu di satu sisi hampir beberapa layar kode pada laptop, di sisi lain, struktur a la json memungkinkan Anda untuk mengisi semua data dengan analogi, dengan cepat dan Anda dapat menyalin-tempel.Dan mengapa posisi diambil secara terpisah dari node?Ini lebih nyaman. Pertama kita tentukan node. Kemudian kita dapat menunjukkan beberapa grup dan mengindikasikannya dalam node. Lalu kami menunjukkan koneksi. Dan kemudian, ketika objek utama dan koneksi di antara mereka, kita mengambil lokasi objek-objek ini pada diagram. Atau sebaliknya.Apakah mungkin tanpa posisi?Itu mungkin tanpa posisi. Tapi itu akan sedikit kusut, dalam contoh Anda dapat melihat opsi ini. Hal ini disebabkan oleh fakta bahwa untuk cytoscape terdapat algoritma untuk lokasi node fcose, yang juga memperhitungkan keberadaan grup. Menentukan posisi membuat skema lebih dapat dikontrol, tetapi pada tahap draft pertama skema dimungkinkan tanpa posisi.Juga, posisi dapat ditentukan dalam gaya pertempuran laut. Itu satu node terletak di a1 dan yang lainnya di d5. Ini khususnya membantu bahwa cytoscape membentuk objek di atas kanvas yang dapat dipindahkan, mis. kita dapat memindahkannya, melihat opsi tata letak yang berbeda, dan kemudian memperbaiki kode pengaturan elemen favorit Anda.Secara umum, saya melihat. Anda juga bisa mencoba? Tentu saja, untuk membuat skema dengan cepat, saya membuat sendiri editor kecil , yang memperbarui skema itu sendiri dan menyimpan opsi terakhir di browser (di localStorage).Sudahkah Anda mencobanya? Anda sekarang dapat menambahkan ke halaman Anda.Kemudian lagi:1. Kami menghubungkan skrip<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Tambahkan ke kode 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. edit kode ke skema yang kita butuhkan (saya pikir itu lebih mudah daripada menggambar burung hantu :)Lebih detail di halaman proyek di github.Apa hasilnya?Saya mencapai tujuan saya - untuk menambahkan skema sebaris ke dokumentasi, formatnya cukup sederhana dan mudah. Itu tidak cocok untuk skema super, tetapi untuk sirkuit kecil yang menjelaskan struktur koneksi, itu bahkan tidak ada apa-apanya. Anda selalu dapat dengan cepat memperbaikinya dan mengubah sesuatu dari waktu ke waktu. Ya, dan kolega dapat memperbaiki sesuatu di dok sendiri, setidaknya tanda tangan ke objek tanpa pelatihan khusus))Apa yang dapat ditingkatkan?Tentu saja ada banyak pilihan. Buat penambahan ikon tambahan (semua yang tersedia ditambahkan sesuai dengan skrip). Pilih satu set ikon yang lebih ekspresif. Memungkinkan untuk menentukan gaya garis tautan. Tambahkan gambar latar belakang.Bagaimana menurut anda? Saya sudah punya beberapa ide untuk implementasi dalam masalah, Anda juga menambahkan Anda di komentar.Solusi saya jelas dapat diterapkan dalam berbagai tugas yang sempit, dan mungkin Anda akan menemukan alat yang lebih mudah untuk menggambar diagram dengan hanya menyandikannya - seperti yang mereka katakan 'tunjukkan diagram Anda sebagai kode'- Pilihan bagus
- Layanan mewah (9 jenis grafik editor online)
- Tentu saja mermaid.js
- Dan jika Anda menyukai skema super detail dan kompleks, maka proyek ini pasti akan menyenangkan Anda: go.drawthe.net