Panduan Sintaks Diagram Alir Mermaid.js

Apa itu Diagram Alir?

Sebuah Diagram Aliradalah peta perilaku dasar yang memvisualisasikan alur kerja operasional langkah demi langkah, prosedur algoritmik, atau logika bisnis berurutan. Dengan mewakili tindakan sistem sebagai bentuk geometris yang berbeda dan mencatat alur kontrol dengan panah arah, diagram alir memudahkan insinyur perangkat lunak dan arsitek sistem untuk melacak jalur eksekusi bersyarat, mengisolasi blok titik kegagalan tunggal, serta menganalisis lingkaran logika sistem sebelum menulis kode backend yang sebenarnya.

Dengan Mermaid.js, Anda tidak perlu menghabiskan berjam-jam menyeret kotak, mengatur garis grid secara detail, atau menghitung ulang variabel padding. Mesin tata letak menghitung koordinat simpul secara dinamis dari skrip deklaratif mentah Anda, sehingga Anda dapat sepenuhnya fokus pada logika dasar sistem Anda.

Panduan Sintaks Inti: Elemen dan Konstruksi

Untuk merancang diagram alir yang elegan dan mudah dibaca di Mermaid, Anda harus menguasai petunjuk arah kanvas, pembatasan simpul geometris, variabel kabel tautan, dan subgraf struktural.

1. Menetapkan Arah Kanvas

Orientasi diagram alir Anda ditentukan langsung pada baris pertama oleh pasangan kata kunci yang diterapkan pada graph atau diagram alirwrapper. Anda dapat mengendalikan arah penskalaan visual tata letak Anda menggunakan empat kunci orientasi utama:

• diagram alir TD (Atas ke Bawah / Orientasi Vertikal)
• diagram alir BU (Bawah ke Atas orientasi)
• diagram alir LR (Kiri ke Kanan / Orientasi Horizontal)
• diagram alir RL (Kanan ke Kiri orientasi)

2. Menyesuaikan Geometri Simpul (Bentuk)

Secara default, deklarasi ID biasa ditampilkan sebagai kotak persegi panjang tajam. Untuk membuat diagram Anda lebih mudah dibaca, gunakan kurung penutup khusus Mermaid untuk menyisipkan konteks visual langsung ke langkah-langkah kerja yang berbeda. Setiap blok definisi harus diawali dengan token tata letak arah agar dapat diproses dengan benar:

• Sudut Bulat: id(Teks) — Melambangkan langkah proses umum.
• Bentuk Stadion/Kapsul: id([Text]) — Penanda standar untuk batas awal dan akhir batas.
• Subrutin/Proses yang Didefinisikan Sebelumnya: id[[Text]] — Melambangkan rutin sistem yang terenkapsulasi atau skrip kelas eksternal.
• Silinder/Database: id[(Text)] — Melambangkan persistensi basis data, cache, atau gudang data.
• Rombus/Hati Keputusan: id{Text} — Melambangkan sakelar bersyarat, cabang if/else, atau titik evaluasi.
• Jajaran Genjang: id[/Text/] atau id[Text] — Menghasilkan batas miring untuk mewakili input/output data secara eksplisit (I/O).

flowchart TD
    start_node([Mulai Eksekusi])
    query_db[(Instan PostgreSQL)]
    validate_check{Diberi Izin?}

3. Aturan Kabel Penghubung dan Label Inline

Anda dapat menyesuaikan garis penghubung Anda untuk mewakili berbagai hubungan struktural dan gaya komunikasi. Untuk menjaga diagram Anda tetap bersih, sisipkan label deskriptif langsung pada jalur tautan Anda:

flowchart TD
    %% Panah penghubung standar dengan label teks
    A --> |"Payload JSON"| B

    %% Garis titik-titik/asinkron dengan label teks
    B -.-> |"Kejadian Asinkron"| C

    %% Garis tebal dengan label teks
    C ==> |"Tulisan Kritis"| D

4. Isolasi Modular melalui Subgraf

Untuk menetapkan perimeter jaringan yang bersih, mengelompokkan mikroservis, atau memisahkan tanggung jawab tim, kelompokkan elemen-elemen Anda di dalam struktursubgraf pembungkus. Anda mendefinisikan subgraf dengan memberikan ID internal, judul tampilan opsional, dan menutupnya denganakhir tag:

flowchart TD
    subgraph auth_sub["Batas Keamanan"]
        gateway[Gateway API] --> auth_worker(Penilai Token)
    akhir

Praktik Terbaik untuk Diagram Alir yang Bersih

• Pisahkan Tata Letak Secara Horizontal: Untuk pipeline rekayasa panjang dengan banyak langkah, pilih flowchart LR arah. Ini lebih bersih saat diperbesar pada monitor landscape lebar standar dibandingkan tata letak vertikal yang panjang.
• Pisahkan Lingkaran yang Kompleks: Jika suatu alur kerja mengandung lingkaran pengulangan berat, beri label pada koneksi balik secara jelas (misalnya, ulangi --> |"Coba Reset"| mulai) untuk mencegah pembaca salah mengira lingkaran ini sebagai jalur maju standar.
• Hindari Menggabungkan Jenis Grafik: Tetap gunakan flowchart kata kunci daripada graph bendera saat merender peta kompleks. Mesin flowchart menggunakan algoritma tata letak yang diperbarui yang mendukung kombinasi panah canggih dan rute jalur yang lebih bersih.

Contoh Diagram Alir Mermaid.js Dunia Nyata

Contoh 1: Jaringan Ingesti Berbasis Peristiwa Mikroservis (Arsitektur Kiri-ke-Kanan)

Rancangan fungsional ini memodelkan layanan ingesti telemetri web. Ini menunjukkan cara menggabungkan input data, berlian keputusan, dan bentuk basis data awan di atas kanvas horizontal yang jelas.

flowchart LR
    %% Tentukan node elemen dengan bentuk geometri eksplisit
    init([Webhook Dipicu]) --> input_io[/Tangkap Permintaan HTTP/]
    input_io --> auth_check{Validasi Token}
    
    auth_check --> |"Token Tidak Valid"| err_stop([Kembalikan 401 Tidak Sah])
    auth_check --> |"JWT Sah"| write_queue[[Terbitkan ke Antrian Kafka]]
    
    write_queue --> worker_proc(Daemon Konsumen)
    worker_proc --> db_store[(Klaster TimescaleDB)]
    db_store --> term([Alur Berakhir])

    %% Opsi gaya kustom cepat
    style auth_check fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style err_stop fill:#f8d7da,stroke:#dc3545,stroke-width:1px

Analisis Sintaks: Diagram ini mengalir dengan lancar dari kiri ke kanan. Langkah validasi menggunakan bentuk berlian keputusan kuning (auth_check{Validasi Token}), yang membagi jalur eksekusi secara bersih menjadi dua hasil yang berbeda. Penyimpanan data langsung dapat dikenali berkat silinder basis data khusus mereka ([(Kelompok TimescaleDB)]) dan input berbentuk jajaran genjang.

Contoh 2: Mesin Pendaftaran Pengguna Multi-Tingkat Perusahaan (Vertikal dengan Subgraf Bersarang)

Rancangan perusahaan canggih ini memetakan alur pendaftaran aplikasi. Ini mengatur langkah-langkah secara vertikal melintasi tiga subgraf struktural terpisah untuk mewakili lapisan arsitektur yang berbeda.

flowchart TD
    subgraph Client_Tier["Lapisan Antarmuka UI Presentasi"]
        app[Antarmuka Aplikasi Seluler]
        web[Frontend SPA Web]
    end

    subgraph Service_Tier["Router Gateway Inti"]
        proxy[[Proxy Balik Ingress Nginx]]
        auth_svc(Pekerja Layanan Otorisasi)
    end

    subgraph Persistence_Tier["Pusat Data yang Diamankan"]
        main_db[(Database Utama Akun Pengguna)]
        cache_node[(Cache Sesi Redis)]
    end

    %% Tentukan saluran komunikasi di seluruh lapisan subsistem
    app -- "Permintaan HTTPS" --> proxy
    web -- "Permintaan HTTPS" --> proxy
    
    proxy --> |"Rute /v1/auth"| auth_svc
    
    auth_svc --> |"Verifikasi Sesi"| cache_node
    auth_svc --> |"Simpan Akun"| main_db

Analisis Sintaks: Indikator orientasi atas-ke-bawah (flowchart TD) memaksa mesin tata letak untuk mengatur komponen secara bersih dari atas ke bawah. Blok pembatas mengelompokkan komponen yang terkait menjadi lapisan-lapisan terpisah (Klien, Layanan, dan Persistensi), memberikan arsitektur keseluruhan rasa yang intuitif dan sangat terstruktur.