Diagram Mermaid Arsitektur Dokumen dalam Markdown Tanpa Klik Apapun

Diagram arsitektur Anda akurat saat Anda menggambarinya. Itu sudah tiga sprint yang lalu. Sekarang ia berada di Google Slide bersama yang tidak diperbarui, dan insinyur yang membangun layanan yang dijelaskan telah pindah tim. Apakah ini terdengar familiar?

Diagram Mermaid membalikkan masalah ini secara utuh. Alih-alih sebuah canvas drag-and-drop yang berada di luar kode Anda, Anda menulis diagram sebagai teks — sintaks Markdown sederhana yang berada di README Anda, dikontrol versi bersama kode Anda, dan ditampilkan di mana saja Markdown ditampilkan. Ketika arsitektur berubah, Anda hanya perlu mengubah satu file teks. Perbedaan (diff) menceritakan seluruh cerita.

Apa Mermaid (dan Mengapa Diagram sebagai Kode Penting)

Mermaid adalah bahasa penggambaran sumber terbuka yang menghasilkan diagram dari teks sederhana. Anda menulis sebuah diagram alur dalam blok kode terlindung; sebuah penghasil (atau penglihat yang memahami Mermaid) mengubahnya menjadi diagram SVG. Tidak perlu akun, tidak perlu langkah ekspor, tidak ada 'format diagram tidak didukung di mesin ini.'

Pendekatan 'diagram sebagai kode' mendapatkan manfaatnya dalam beberapa cara konkret:

• Kontrol versi — diagram berada di Git. Anda dapat membandingkan perubahan, membatalkan perubahan, dan mengikatnya ke PR yang sama dengan kode yang dijelaskan.
• Tidak ada ketergantungan pada vendor — teks sederhana dapat dipindahkan. Ganti penghasil, cabut repositori, ekspor ke Confluence — sumbernya selalu dapat dibaca.
• Selalu dekat dengan kode — diagram yang berada di repositori yang sama dengan layanan yang dijelaskan jauh lebih mungkin tetap akurat daripada yang berada di slide bersama.
• Mudah diotomatisasi — Anda dapat menghasilkan sintaks Mermaid dari kode (skema database, spesifikasi API, jalur CI) menggunakan skrip atau LLM.

Sebelum mempelajari jenis diagram, Anda dapat memperlihatkan secara langsung setiap sintaks Mermaid — tanpa setup lokal — menggunakan Penghasil Diagram Mermaid di iotools.cloud. Tempel, lihat hasilnya, iterasi. Gunakan ini bersama panduan ini untuk menjalankan setiap contoh secara langsung.

Alur: Pekerja Utama

Alur adalah jenis diagram Mermaid yang paling umum, dan alasan itu — karena mereka menangani segala hal dari pohon keputusan sederhana hingga alur kompleks antar layanan. Berikut sintaks yang mencakup 90% kasus penggunaan nyata:

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

Beberapa hal penting tentang sintaks alur:

• Arah: TD (atas ke bawah), LR (kiri ke kanan), BT (bawah ke atas), RL (kanan ke kiri)
• Bentuk node: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• Label sisi: -- label --> atau -->|label|
• Subgraf: mengelompokkan node secara visual

Subgraf sangat berguna untuk menunjukkan batas layanan:

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

Diagram Urutan: Menunjukkan Alur Pemanggilan API

Diagram urutan adalah alat yang tepat ketika Anda perlu menunjukkan urutan interaksi antar sistem — rantai pemanggilan API, alur otentikasi, atau urutan webhook. Mereka membuat waktu dan tanggung jawab jelas dalam cara yang tidak bisa dilakukan oleh alur.

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

Panah padat (->>) adalah permintaan; panah berputar (-->>) adalah respons. participant deklarasi mengontrol urutan kotak muncul di bagian atas diagram. Anda juga dapat menggunakan actor untuk peserta manusia, activate/deactivate untuk menunjukkan waktu pemrosesan, dan loop atau alt blok untuk alur kondisional.

Diagram Hubungan-Entitas: Skema Database dalam Dokumentasi

Diagram ER harus ada di setiap README layanan yang memiliki skema database. Sintaks ER Mermaid bersih dan mencakup kardinalitas secara otomatis:

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

Notasi kardinalitas: || tepat satu, o| nol atau satu, o{ nol atau banyak, |{ satu atau banyak. Label hubungan ("tempat", "mengandung") dimasukkan dalam kutipan di akhir.

Diagram Status: Memodelkan Alur dan Mesin Status

Setiap kali Anda memiliki entitas yang berpindah antar status — pesanan, langganan, pekerjaan CI — diagram status lebih tepat daripada alur. Sintaks diagram status Mermaid secara langsung sesuai dengan cara Anda mendefinisikan mesin status dalam kode:

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] menandai status awal dan akhir. Transisi membawa kejadian yang memicu transisi tersebut. Anda dapat menempatkan status dalam status komposit dan menggunakan note blok untuk memberi konteks tambahan pada transisi.

Diagram Kelas: Struktur OOP untuk Dokumentasi Penerimaan

Diagram kelas paling berguna saat memperkenalkan insinyur ke kodebasis berbasis objek atau dokumentasi model domain. Mermaid mencakup pewarisan, antarmuka, komposisi, dan tanda metode:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean isIndoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

Modifikasi visibilitas mengikuti konvensi UML: + umum, - privat, # terlindungi. Panah hubungan mencakup asosiasi (-->), pewarisan (<|--), komposisi (*--), dan agregasi (o--).

Di mana Mermaid Tampil Secara Native

Poin utama dari Mermaid adalah dukungan native di alat-alat yang sudah digunakan oleh pengembang:

• GitHub — blok kode terlindung Mermaid (```mermaid) tampil di README, isu, deskripsi PR, dan wiki sejak 2022.
• GitLab — dukungan native Mermaid di file Markdown dan halaman wiki.
• Notion — tempel blok kode Mermaid ke dalam blok kode yang diatur sebagai "Mermaid" dan tampil secara langsung.
• VS Code — ekstensi "Pendukung Tampilan Mermaid" untuk tampilan pra-visualisasi menghasilkan diagram di panel tampilan bawaan.
• Obsidian — Mermaid tampil secara native tanpa plugin.
• Docusaurus, MkDocs, Astro — ada plugin Mermaid untuk semua generator situs statis utama.
• Confluence — melalui aplikasi "Diagram Mermaid untuk Confluence".

Jika Anda menulis dokumentasi yang akan berakhir di GitHub atau GitLab, diagram Mermaid bekerja secara langsung tanpa konfigurasi.

Kekurangan dan Kapan Menggunakan Sesuatu yang Lain

Mermaid tidak sempurna untuk setiap situasi. Beberapa hal yang perlu diperhatikan:

• Layout kompleks — algoritma otomatis layout Mermaid tidak selalu menghasilkan hasil yang rapi untuk grafik besar. Jika Anda memiliki 50+ node dengan banyak sisi yang saling berpotongan, Anda mungkin perlu mengatur ulang atau membagi diagram secara manual.
• Tampilan di Confluence — Confluence tidak mendukung Mermaid secara native; Anda perlu aplikasi berbayar. Jika tim Anda tinggal di Confluence, alokasikan anggaran untuk ini atau gunakan draw.io sebagai alternatif.
• Jenis diagram yang tidak standar — diagram jaringan, diagram penerapan, dan diagram arsitektur C4 membutuhkan penyesuaian atau tidak didukung secara baik.
• Kontrol gaya — pilihan tema Mermaid terbatas. Untuk diagram berbranding dengan warna dan font khusus, Anda akan menghabiskan waktu berjuang dengan penghasil.

Alternatif utama yang perlu diketahui:

• PlantUML — sintaks lebih tua dan lebih panjang, tetapi dukungan UML lebih kaya dan integrasi dengan Confluence lebih baik. Membutuhkan Java secara lokal atau penghasil berbasis server.
• D2 — alat baru untuk diagram sebagai kode dengan kontrol layout yang lebih baik dan penanganan diagram besar yang lebih baik. Penggunaan ekosistem kurang dari Mermaid, tetapi berkembang cepat.
• draw.io / Excalidraw — alat GUI saat Anda membutuhkan kontrol visual yang tepat dan tidak peduli bahwa diagram berada di luar kontrol versi.

Untuk kebanyakan dokumentasi pengembang — README layanan, alur API, panduan onboarding — Mermaid cukup menangani kebutuhan tersebut, dan dukungan native di GitHub saja membuatnya layak untuk belajar.

Pratinjau Mermaid Tanpa Menginstal Apapun

Jika Anda sedang menguji sintaks atau ingin berbagi diagram dengan seseorang yang tidak memiliki pengaturan lokal renderer, Penghasil Diagram Mermaid di iotools.cloud memberi Anda tampilan langsung tanpa pendaftaran, tanpa instalasi, dan tanpa konfigurasi. Tempel kode Mermaid Anda, lihat diagram yang dihasilkan, dan salin hasilnya.

Ini berguna untuk memeriksa sintaks diagram sebelum mengirimkan, berbagi versi yang dihasilkan di pesan Slack, atau membangun prototipe diagram yang nanti akan Anda tempelkan ke README.

Mulai dengan Alur

Jika Anda belum pernah menulis diagram Mermaid, mulailah dengan alur. Pilih proses di dalam kodebase Anda yang sudah lama ingin di dokumentasikan — siklus permintaan, pekerjaan latar belakang, pipeline deploy — dan tulis dalam sintaks Mermaid dalam waktu 10 menit. Tempel ke README Anda dalam blok ```mermaid dan push. GitHub akan menghasilkan tampilan secara otomatis.

Satu diagram tersebut, yang dikontrol versi dan berada di dekat kode yang dijelaskan, lebih bernilai daripada slide yang tidak diperiksa oleh siapa pun.

Anda mungkin juga menyukai