Diagram sebagai Kode: Diagram Urutan UML dengan PlantUML dan VPasCode

Sebuah UML diagram urutan menunjukkan bagaimana peserta berinteraksi seiring waktu. Diagram ini berguna untuk mendokumentasikan sebuah kasus penggunaan, alur API, proses bisnis, atau skenario sistem. Waktu umumnya bergerak dari atas ke bawah; penempatan horizontal menunjukkan siapa yang berpartisipasi, bukan ukuran tepat dari waktu yang berlalu.

PlantUML memungkinkan Anda mendeskripsikan diagram sebagai teks. VPasCode Edito dari Visual Paradigmr menggabungkan editor kode dengan pratinjau langsung dan bantuan AI untuk menghasilkan, memodifikasi, dan memperbaiki kode diagram. Alur kerja yang baik adalah menggunakan AI untuk mendapatkan draf awal, kemudian memeriksa dan menyempurnakan PlantUML sendiri.

1. Struktur dasar

Sebuah diagram urutan PlantUML dimulai dengan @startuml dan diakhiri dengan @enduml Peserta biasanya didaftarkan sebelum pesan sehingga Anda dapat mengontrol nama dan urutan mereka.

@startuml
actor Customer
participant Browser
participant "Order API" as API
database "Order DB" as DB

Customer -> Browser: Place order
Browser -> API: POST /orders
API -> DB: Save order
DB --> API: Order ID
API --> Browser: 201 Created
Browser --> Customer: Show confirmation
@enduml

Label yang ditampilkan untuk peserta dapat diapit tanda kutip, dengan sebagai untuk menyediakan alias yang lebih pendek yang digunakan dalam pesan. Kata kunci peserta yang umum meliputi aktor, peserta, batas, kontrol, entitas, basis data, dan koleksi. Gunakan kata kunci yang paling baik mengkomunikasikan peran peserta; kata kunci ini tidak memaksakan arsitektur tertentu.

2. Membaca pesan dan waktu

Setiap pesan ditulis sebagai pengirim, panah, penerima, dan label. Urisan baris pesan menentukan urutan vertikalnya dalam diagram.

• -> adalah panah pesan solid, yang umum digunakan untuk permintaan atau panggilan.

• --> adalah panah putus-putus, yang sering digunakan untuk respons atau pengembalian.

• ->> dan -->> menggunakan kepala panah terbuka dalam gaya PlantUML yang umum.

• : teks menambahkan label pesan.

Pilih konvensi yang konsisten untuk panggilan dan respons. Diagram UML mengkomunikasikan interaksi; diagram ini tidak secara otomatis menjamin bahwa implementasi mengikuti protokol yang digambarkan.

3. Aktivasi dan masa hidup peserta

Aktivasi dapat menunjukkan kapan seorang peserta sedang bekerja. Gunakan activate dan nonaktifkan, atau singkatan ++ dan -- pada panah pesan.

@startuml
actor User
participant "Login API" sebagai API
database Users

User -> API: Kirimkan kredensial
aktifkan API
API -> Users: Temukan akun
aktifkan Users
Users --> API: Catatan akun
dinonaktifkan Users
API --> User: Hasil login
dinonaktifkan API
@enduml

Aktivasi paling berguna ketika memperjelas panggilan bersarang atau tanggung jawab. Hindari menambahkannya secara mekanis ke setiap pesan jika hal itu membuat diagram lebih sulit dibaca.

4. Kondisi, alternatif, dan pengulangan

Gunakan fragmen gabungan untuk menunjukkan alur kontrol. Kata kunci fragmen memulai blok, else memisahkan alternatif di mana berlaku, dan end menutupnya. Kondisi penjaga ditulis dalam tanda kurung siku.

Jalur alternatif: alt dan else

@startuml
actor User
participant "Login API" as API
database Users

User -> API: Submit username and password
API -> Users: Check credentials
Users --> API: Match result

alt [credentials valid]
  API --> User: Return session token
else [credentials invalid]
  API --> User: Return authentication error
end
@enduml

alt sesuai ketika jalur-jalur saling eksklusif. Gunakan label yang membuat kondisi menjadi jelas.

Perilaku opsional: opt

@startuml
actor Customer
participant Checkout
participant "Email Service" as Email

Customer -> Checkout: Complete purchase
Checkout --> Customer: Order confirmation

opt [customer opted in to email]
  Checkout -> Email: Send receipt
  Email --> Checkout: Accepted
end
@enduml

Pengulangan: loop

@startuml
participant "Batch Job" as Job
participant "Payment API" as API

loop [untuk setiap pembayaran yang tertunda]
  Job -> API: Kirim pembayaran
  API --> Job: Hasil pembayaran
end
@enduml

Letakkan tindakan yang berulang di dalam fragmen dan nyatakan kondisi atau ruang lingkup loop dengan jelas.

5. Interaksi paralel dan dikelompokkan

Gunakan par ketika interaksi terjadi secara bersamaan atau urutannya tidak penting. Gunakan group untuk memberi label pada sekumpulan pesan tanpa menyiratkan struktur alur kontrol tertentu.

@startuml
participant "Layanan Pesanan" sebagai Pesanan
participant "Layanan Inventaris" sebagai Inventaris
participant "Layanan Notifikasi" sebagai Notifikasi

Pesanan -> Pesanan: Pesanan diterima

par Cadangkan stok
  Pesanan -> Inventaris: Cadangkan barang
  Inventaris --> Pesanan: Hasil reservasi
else Notifikasi pelanggan
  Pesanan -> Notifikasi: Kirim pembaruan pesanan
  Notifikasi --> Pesanan: Diterima
end
@enduml

Gunakan parhanya ketika konkurensi memiliki makna. Jika satu tindakan harus selesai sebelum tindakan lain dimulai, tampilkan pesan secara berurutan sebagai gantinya.

6. Catatan, referensi, dan pengelompokan visual

Catatan dapat memperjelas asumsi, batasan, atau keputusan. Sebuah reffragmen dapat mengarahkan pembaca ke diagram lain atau interaksi yang didokumentasikan secara terpisah.

@startuml
actor Pelanggan
participant "UI Checkout" sebagai UI
participant "Layanan Pembayaran" sebagai Bayar
participant "Pemeriksaan Penipuan" sebagai Fraud

Pelanggan -> UI: Bayar pesanan
UI -> Bayar: Otorisasi pembayaran
Bayar -> Fraud: Evaluasi transaksi

note kanan Fraud
  Aturan risiko dipelihara
  di luar interaksi ini.
end note

Fraud --> Bayar: Hasil risiko
Bayar --> UI: Hasil otorisasi
UI --> Pelanggan: Tampilkan hasil
@enduml

Catatan harus menambahkan konteks daripada mengulang label pesan. Jika diagram menjadi padat, pecah menjadi skenario yang fokus dan gunakan referensi atau tautan dokumentasi untuk menghubungkannya.

7. Membuat dan menyempurnakan diagram di VPasCode

VPasCode mendukung pengeditan PlantUML dengan rendering langsung, serta pembuatan diagram yang dibantu AI, modifikasi kode, dan koreksi sintaks. Antarmuka dan ketersediaan fitur yang tepat dapat berubah, tetapi alur kerja umumnya adalah:

1. Buka VPasCode dan pilih atau masukkan PlantUML.

2. Deskripsikan interaksi, atau tempelkan draf PlantUML ke dalam editor.

3. Periksa pratinjau yang telah dirender saat Anda menyempurnakan sumbernya.

4. Minta AI untuk melakukan perubahan tertentu, seperti “tambahkan jalur kredensial tidak valid menggunakan “alt.”

5. Tinjau kode dan diagram yang dihasilkan untuk memastikan kebenaran sintaks dan sistem.

6. Ekspor atau bagikan diagram yang sudah selesai menggunakan opsi yang tersedia di editor.

Perintah yang berguna memberikan kepada AI jenis diagram, aktor, batas sistem, jalur sukses utama, jalur alternatif penting, dan tingkat detail. Sebagai contoh:

Buat diagram urutan PlantUML untuk pelanggan yang masuk ke aplikasi web. Sertakan Browser, Login API, Penyedia Identitas, dan User DB. Tampilkan jalur masuk yang berhasil dan alternatif kata sandi tidak valid. Gunakan label yang ringkas dan jangan menciptakan layanan di luar ini.

Anggap kode yang dihasilkan sebagai draf. Periksa bahwa peserta, panah, kondisi, dan jalur kesalahan mencerminkan sistem yang sebenarnya—bukan hanya alur yang tampak masuk akal.

8. Contoh yang lebih lengkap: checkout dengan kegagalan pembayaran

Contoh ini menggabungkan alias peserta, aktivasi, dan jalur alternatif.

@startuml
title Checkout dan Otorisasi Pembayaran

actor Customer
boundary "Checkout UI" sebagai UI
control "Order Service" sebagai Orders
participant "Payment Gateway" sebagai Pay
database "Order DB" sebagai DB

Customer -> UI: Kirim checkout
UI -> Orders: Buat pesanan tertunda
activate Orders

Orders -> DB: Simpan pesanan tertunda
DB --> Orders: ID Pesanan

Orders -> Pay: Otorisasi pembayaran
activate Pay

alt [pembayaran disetujui]
  Pay --> Orders: Kode otorisasi
  deactivate Pay

  Orders -> DB: Tandai pesanan dikonfirmasi
  DB --> Orders: Diperbarui
  Orders --> UI: Pesanan dikonfirmasi
  UI --> Customer: Tampilkan konfirmasi
else [pembayaran ditolak]
  Pay --> Orders: Alasan penolakan
  deactivate Pay

  Orders -> DB: Tandai pesanan gagal
  DB --> Orders: Diperbarui
  Orders --> UI: Pembayaran ditolak
  UI --> Customer: Tampilkan opsi coba lagi
end

deactivate Orders
@enduml

Periksa apakah urutan dalam diagram sesuai dengan perilaku nyata. Misalnya, jika sistem menyimpan pesanan hanya setelah otorisasi berhasil, pindahkan pesan database agar sesuai dengan desain tersebut.

9. Pedoman pemodelan praktis

• Jaga agar diagram tetap fokus.Tampilkan satu skenario atau satu set jalur yang sangat terkait. Pisahkan detail mendalam yang mengalihkan perhatian dari interaksi utama.

• Beri nama peserta berdasarkan tanggung jawabnya. Preferkan label seperti “Order Service” atau “Payment Gateway” daripada label samar seperti “System.

• “Tampilkan batas yang bermakna.Bedakan pengguna, klien, layanan internal, basis data, dan sistem eksternal ketika hal itu membantu pembaca memahami tanggung jawab.

• Gunakan label pesan yang jelas. Sertakan operasi, peristiwa, atau hasil penting; hindari label yang hanya menyatakan “proses.”

• Pemodelan jalur kegagalan yang relevan.Sertakan waktu habis yang relevan, penolakan, percobaan ulang, atau kegagalan validasi ketika hal tersebut memengaruhi skenario.

• Gunakan fragmen dengan tepat. alt berarti jalur alternatif, opt berarti perilaku opsional, loop berarti pengulangan, dan par berarti perilaku paralel.

• Hindari kebisingan implementasi.Jangan diagramkan setiap getter, metode internal, atau detail tingkat rendah kecuali audiens membutuhkannya.

• Jaga agar sumber dapat dipelihara.Gunakan alias untuk nama panjang, penamaan yang konsisten, serta komentar atau catatan singkat untuk asumsi penting.

10. Kesalahan umum dan daftar periksa tinjauan

Jika diagram gagal dirender, periksa bahwa @startuml dan @enduml hadir, blok fragmen memiliki pasangan end pernyataan, alias digunakan secara konsisten, dan semua titik akhir pesan merujuk pada peserta yang telah didefinisikan. Periksa juga apakah ada sintaks dari bahasa diagram lain yang secara tidak sengaja disisipkan ke dalam sumber PlantUML.

Sebelum membagikan, tinjau dua hal:

• Sintaks: Apakah diagram berhasil dirender? Apakah semua fragmen ditutup? Apakah peserta dan alias konsisten?

• Makna: Apakah peserta dan arah pesan sudah benar? Apakah jalur kesalahan penting sudah disertakan? Apakah sistem eksternal dan penyimpanan data direpresentasikan dengan akurat?

Alur kerja diagram-sebagai-kode yang paling kuat diagram-sebagai-kode menggabungkan sumber yang mudah dibaca, umpan balik visual yang cepat, dan tinjauan domain. PlantUML memberikan kontrol eksplisit atas notasi interaksi, sementara VPasCode dapat mempercepat penyusunan dan iterasi; otoritas terakhir mengenai akurasi diagram tetaplah perilaku sistem yang dimaksudkan untuk digambarkan.

This post is also available in Deutsch, English, Español, فارسی, Français, 日本語, Polski, Portuguese, Ру́сский, Việt Nam, 简体中文 and 繁體中文.