Panduan Sintaks Diagram Urutan Mermaid.js

Apa itu Diagram Urutan?

Sebuah Diagram Urutan adalah diagram perilaku yang penting diagram UML dirancang untuk memvisualisasikan alur kronologis pesan, pemanggilan fungsi, dan muatan data antara entitas sistem yang berbeda sepanjang timeline linier. Diakui sebagai jenis diagram UML intijenis diagram UML, memetakan interaksi runtime dengan menumpuk komponen sistem sepanjang sumbu X sebagai garis hidup vertikal dan melacak pertukaran pesan sepanjang sumbu Y. Rancangan ini sangat berharga bagi pengembang yang mendiagnosis masalah pada pertukaran tangan API terdistribusi, jalur orkestrasi mikroservis, atau alur otentikasi pengguna secara real-time.

Dengan Mermaid.js, Anda dapat membuat skrip proses temporal yang kompleks menggunakan struktur teks yang intuitif. Mesin secara otomatis menangani jarak vertikal, mengelola penataan panah pesan, dan menggambar blok aktivasi runtime dengan rapi di seluruh kanvas Anda.

Panduan Sintaks Inti: Elemen dan Konstruksi

Untuk merancang diagram urutan UML yang akurat dan mudah dibaca di Mermaid, Anda harus menguasai deklarasi peserta, variasi panah pesan, garis hidup eksplisit, dan struktur blok kondisional.

1. Deklarasi Peserta dan Aktor

Anda mendeklarasikan entitas sistem standar menggunakan kata kunci participant kata kunci. Jika entitas tersebut mewakili pengguna akhir manusia atau operator eksternal, gunakan kata kunci actor kata kunci untuk menampilkan ikon gambar batang standar di kanvas:

sequenceDiagram
    actor Client
    participant API sebagai Gateway Router

Kiat Pro: Gunakan kata kunci as kata kunci untuk memetakan nama komponen panjang ke alias internal yang ringkas, menjaga skrip pesan Anda tetap ringkas dan mudah dibaca.

2. Format Panah Pesan

Jenis garis dan kepala panah yang Anda gunakan menentukan gaya komunikasi antara peserta sistem Anda:

• ->> **Panggilan Sinkron:** Garis padat dengan kepala panah yang terisi. Melambangkan permintaan yang memblokir dan menunggu penyelesaian eksekusi.
• --> **Garis Respons:** Garis putus-putus dengan kepala panah terbuka. Digunakan untuk mengembalikan muatan data atau token konfirmasi.
• -> **Panggilan Asinkron:** Garis padat dengan kepala panah terbuka. Menunjukkan pesan atau siaran acara yang tidak memblokir.

sequenceDiagram
    App->>Server: Permintaan Muatan
    Server-->App: Respons 200 OK

3. Mengelola Batang Aktivasi Lifeline

Untuk menunjukkan kapan tepatnya komponen sistem sedang aktif menjalankan tugas atau menggunakan memori thread, gunakan perintah activate dan deactivate perintah. Sebagai alternatif, Anda dapat menambahkan tanda tambah (+) atau tanda kurang (-) sebagai tanda langsung pada target pesan Anda sebagai jalan pintas visual cepat:

sequenceDiagram
    Client->>+Server: Proses Data
    %% Server sekarang secara visual aktif
    Server-->-Client: Kembalikan Hasil

4. Menata Kondisional dan Alternatif (Alt, Opt, Loop)

Untuk menangani logika runtime bercabang, evaluasi token, atau pengulangan permintaan ulang, bungkus skrip pesan Anda di dalam fragmen blok standar:

• alt / else — Menilai jalur kondisional (mirip dengan blok kode if/else).
• opt — Menentukan langkah opsional yang hanya dieksekusi di bawah kriteria tertentu.
• loop — Mengulang urutan eksekusi hingga suatu kondisi terpenuhi.

sequenceDiagram
    loop Setiap 30 detik
        Client->>Server: Ping Heartbeat
    end

Praktik Terbaik untuk Jalur Waktu Urutan yang Bersih

• Jaga Garis Kehidupan Tetap Rapi: Hindari mencantumkan puluhan mikro-entitas sepanjang sumbu X. Jika suatu proses berinteraksi dengan kelas bantuan kecil, abstraksikan mereka di balik batas sistem tingkat tinggi seperti [Pekerja Otorisasi] atau [Kolam Cache].
• Beri Label Kode Status Secara Jelas: Saat menulis kembali respons (-->), jangan hanya menulis “Kembalikan Data”. Beri label pada jalur dengan status HTTP yang jelas atau jenis peristiwa (misalnya, "201 Dibuat (Token JWT)") untuk memberi konteks yang tepat kepada insinyur.
• Terapkan Catatan untuk Perhitungan yang Kompleks: Gunakan Catatan di atas, Catatan di kiri, atau Catatan di kanan petunjuk untuk mendokumentasikan operasi non-visual, seperti langkah enkripsi internal atau hashing data basis data.

Contoh Diagram Urutan Mermaid.js Dunia Nyata

Contoh 1: Alur Pertukaran Token OAuth2 yang Aman (Blok Aktivasi & Alternatif)

Rancangan fungsional ini memodelkan urutan login pengguna yang aman. Ini menunjukkan cara menggabungkan aktor manusia, garis kehidupan sistem yang jelas, dan jalur validasi yang kompleks menggunakan blok alt/else.

sequenceDiagram
    actor User sebagai Pengguna Akhir
    participant App sebagai Klien Aplikasi Mobile
    participant Auth sebagai Penyedia Identitas Auth0

    User->>+App: Klik "Masuk dengan OAuth"
    App->>+Auth: Alihkan dengan client_id & scope
    Auth-->>User: Tampilkan Antarmuka Masuk
    User->>Auth: Kirim Kredensial
    
    Auth->>Auth: Validasi Hash Kata Sandi
    
    alt Kredensial Sah
        Auth-->>App: Alihkan 302 dengan Kode Otorisasi
        App->>Auth: Tukar Kode untuk Token Akses
        Auth-->>-App: Kembalikan Token JWT (IdToken)
        App-->>User: Tampilkan Halaman Beranda Akun Pengguna
    else Kredensial Tidak Sah
        Auth-->>App: Kembalikan Kesalahan 401 Tidak Diizinkan
        App-->>-User: Tampilkan Peringatan "Nama Pengguna/Sandi Salah"
    end

Analisis Sintaks: Timeline ini melacak proses jabat tangan antar pihak. Bagian alt / else kontainer memetakan jalur validasi biner dengan jelas, memastikan status kesalahan didokumentasikan secara lengkap bersamaan dengan jalur sukses.

Contoh 2: Pemeriksaan Stok Pesanan Terdistribusi (Proses Paralel & Catatan)

Rancangan sistem canggih ini memetakan alur pemeriksaan e-commerce perusahaan. Ini menggunakan blok paralel (par) untuk menampilkan rutin pengiriman API secara bersamaan dan menangani catatan penguncian basis data di seluruh topologi.

sequenceDiagram
    participant Web sebagai Frontend Web
    participant Ord sebagai Penyelaras Pesanan
    participant Inv sebagai Layanan Stok
    participant Pay sebagai Gerbang Pembayaran

    Web->>+Ord: Kirim Permintaan Pemeriksaan
    Note over Ord: Verifikasi Ketersediaan Stok Barang
    
    par Kirim Panggilan API Secara Paralel
        Ord->>+Inv: Kunci Barang Stok
        Inv-->-Ord: Stok Dipesan (Stok Terkunci)
    and
        Ord->>+Pay: Otorisasi Pembayaran Kartu Kredit
        Pay-->-Ord: Penangkapan Berhasil (Pembayaran Tercatat)
    end
    
    opt Proses Alokasi Gagal
        Note right of Ord: Jalankan saga rollback jika ada panggilan yang gagal
    end
    
    Ord-->-Web: 200 Sukses Pemeriksaan Dikonfirmasi

Analisis Sintaks: Bagian par / and kontainer memberi petunjuk kepada mesin untuk mengelompokkan eksekusi paralel bersama, mendokumentasikan operasi backend yang berjalan bersamaan. Bagian Note over dan Note right of tag menyisipkan penjelasan teknis runtime langsung ke dalam kisi kanvas, membantu tim memahami transaksi latar belakang seperti penguncian data dan saga rollback tanpa membuat panah pesan utama menjadi berantakan.