Dasar Sintaks Mermaid.js

Sebelum terjun ke tata letak arsitektur tertentu seperti bagan alur yang kompleks atau bagan timeline urutan waktu, sangat penting untuk memahami aturan dasar yang mengatur Buku Panduan Mermaid. Mermaid mengandalkan sistem notasi teks yang bersih dan sangat intuitif. Setelah Anda memahami bagaimana mesin menginisialisasi jenis kanvas, memberi nama komponen struktural, dan mengarahkan panah arah, menulis tata letak sistem yang kompleks menjadi benar-benar alami.

Panduan singkat ini membahas mekanisme sintaks struktural global yang berlaku di hampir semua jenis bagan Mermaid di dalam lingkungan kerja VPasCode.

1. Pembungkus Tipe Diagram Wajib

Setiap blok kode Mermaid harus dimulai dengan menyatakan secara eksplisit arketipe diagram pada baris pertama. Ini memberi tahu parser VPasCode secara tepat mesin struktural mana yang harus diaktifkan di kanvas pratinjau Anda:

  • graph TD — Menentukan tata letak bagan alur yang diatur dari Atas ke Bawah.
  • sequenceDiagram — Menentukan bagan timeline runtime kronologis.
  • classDiagram — Menentukan gambaran kerja perangkat lunak berbasis objek struktural.

Berbeda dengan mesin teks-ke-bagan lainnya, Mermaid tidak memerlukan tag penutup di akhir. Parser hanya membaca deklarasi struktural pada baris pertama dan mengompilasi semua elemen yang bersarang langsung di bawahnya dalam kontainer blok kode Anda.

2. Mendeklarasikan Elemen: ID vs. Label Tampilan

Ketika memodelkan sistem perangkat lunak, Anda akan membuat berbagai elemen struktural seperti komponen, basis data, atau mikroservis. Dalam Mermaid, Anda mendeklarasikan elemen dengan menentukan ID alfanumerik internal yang pendek, diikuti langsung oleh gaya kurung yang mengendalikan bentuk visualnya, dan nama tampilan yang ramah pengguna:

microservice_id[API Pemrosesan Pembayaran]
db_id[(SQL Transaksi Pengguna)]

Mengapa ini merupakan praktik terbaik: Menggunakan ID internal yang pendek dan bersih (seperti microservice_id) membuat menggambar garis hubungan jauh lebih cepat nantinya. Jika suatu saat Anda perlu mengubah label yang ditampilkan ke pelanggan dari “API Pemrosesan Pembayaran” menjadi “Layanan Checkout Global”, Anda hanya perlu mengeditnya di satu baris tempat deklarasi dilakukan, daripada memperbarui puluhan baris di seluruh skrip Anda.

3. Menguasai Panah Hubungan dan Rute Arah

Koneksi antar simpul sistem digambar menggunakan kombinasi tanda hubung (-), tanda sama dengan (=), dan kurung panah (>). Gaya garis Anda memberi Anda kendali implisit atas bagaimana mesin tata letak otomatis menyesuaikan ukuran diagram Anda:

  • A --> B menggambar panah berarah standar yang menunjuk dari elemen A langsung ke elemen B.
  • A --- Bmenggambar garis hubungan datar dan tidak berarah tanpa ujung panah, ideal untuk asosiasi sederhana.
  • A -.-> Bmenciptakan garis ketergantungan titik-titik, yang merupakan standar industri untuk menunjukkan ketergantungan asinkron atau webhook jaringan.
  • A ==> Bmenciptakan garis koneksi tebal dan tebal, sempurna untuk menyoroti jalur pemrosesan data utama atau tautan infrastruktur kritis.

4. Menambahkan Konteks Secara Langsung: Label dan Komentar Kode

Dokumentasi yang jelas sangat bergantung pada penempatan konteks yang tepat di sekitar garis visual dan skrip teks Anda:

Menandai Garis Koneksi

Anda dapat menambahkan teks penjelas langsung ke setiap garis koneksi dengan memasukkan string teks di antara dua pasang tanda hubung, atau dengan menambahkan karakter pipa (|Text|) tepat setelah pemetaan hubungan Anda:

client_id -- "HTTPS POST /v1/checkout" --> api_id
client_id --> |HTTPS POST /v1/checkout| api_id

Menulis Komentar Kode

Jika Anda ingin meninggalkan catatan administratif, kredit desain, atau penjelasan arsitektur di dalam file skrip Anda tanpa menampilkan kotak visual di kanvas, gunakan tanda persen ganda (%%). Ini memberi tahu mesin untuk melewatkan parsing baris tersebut sepenuhnya:

%% TODO: Kita perlu memperbarui kotak batas ini setelah migrasi DevOps selesai
[Monolit Lama] --> [Microservice Baru]
Scroll to Top