Panduan Sintaks Model C4 PlantUML

Apa itu Diagram Model C4?

The Diagram Model C4adalah kerangka arsitektur hierarkis dengan empat tingkatan yang dirancang untuk mendokumentasikan arsitektur perangkat lunak dengan tingkat detail yang bervariasi. Dibuat oleh Simon Brown, C4 menghindari kotak dan garis yang samar dengan menyusun peta sistem menjadi empat lensa abstraksi yang jelas: Konteks (lingkup tingkat sistem), Kontainer (Aplikasi dan penyimpanan data), Komponen (modul internal), dan Kode (implementasi tingkat kelas).

Untuk menerapkan model ini secara efektif dalam teks, insinyur menggunakan ekstensi perpustakaan resmi C4-PlantUMLekstensi perpustakaan standar. Perpustakaan ini menggantikan bentuk UML mentah dengan makro khusus yang secara otomatis menyisipkan warna, bentuk, dan bidang metadata yang berbeda untuk pengguna, sistem, dan basis data. Dengan VPasCode, Anda dapat mendefinisikan lingkungan bersarang ini secara bersih dalam kode. Mesin tata letak secara dinamis mengarahkan vektor koneksi dan menyesuaikan ukuran bidang teks tanpa merusak geometri tata letak Anda.

Panduan Sintaks Inti: Elemen dan Konstruksi

Membangun model C4 yang valid menggunakan PlantUML bergantung pada mengimpor file perpustakaan yang benar, memilih makro struktural, menetapkan batas, dan menggunakan tautan hubungan khusus.

1. Mengimpor File Perpustakaan Standar C4

The C4-PlantUMLekstensi ini dibagi menjadi file-file individual yang langsung sesuai dengan tingkatan-tingkatan berbeda dalam model abstraksi. Untuk mencegah penurunan kinerja atau kesalahan kompilator, Anda hanya harus mengimpor lapisan file tertentu yang ditargetkan oleh diagram Anda:

@startuml
' Sertakan file lapisan C4 yang diperlukan
!include <C4/C4_Context>
' Gunakan C4_Container atau C4_Component untuk peta arsitektur yang lebih mendalam

2. Deklarasi Aktor dan Sistem Inti (Tingkat Konteks)

Pada tingkat konteks sistem tingkat tinggi, Anda memodelkan komponen internal, ketergantungan eksternal, dan pengguna manusia. Perpustakaan standar menyediakan makro khusus yang menerima ID, label visual, dan tag deskriptif opsional:

• Person(id, "Label", "Deskripsi") — Melambangkan profil pengguna manusia atau aktor sistem.
• System(id, "Label", "Deskripsi") — Melambangkan ekosistem aplikasi perangkat lunak internal utama atau layanan.
• System_Ext(id, "Label", "Deskripsi") — Melambangkan sistem eksternal atau ketergantungan API pihak ketiga (ditampilkan dengan palet warna abu-abu yang jelas).

@startuml C4_Elements
!include <C4/C4_Context>
Person(customer, "Pelanggan Perbankan", "Pelanggan dengan rekening bank pribadi")
System(banking_sys, "Sistem Perbankan Inti", "Menangani transaksi keuangan")
System_Ext(mail_sys, "Layanan Email", "Gerbang notifikasi SMTP internal")

3. Meledakkan Batas (Tingkat Container dan Komponen)

Ketika menyelami lebih dalam ke lapisan Container, Anda memodelkan aplikasi web, mikroservis, dan basis data. Anda dapat mengisolasi elemen-elemen internal ini di dalam kotak batas logis yang jelas menggunakanSystem_Boundary() wrapper makro:

!include <C4/C4_Container>

System_Boundary(c1, "Ekosistem Sistem E-Commerce") {
    Container(web_app, "Aplikasi Halaman Tunggal", "React & TypeScript", "Menyediakan fitur pengguna melalui tampilan web")
    ContainerDb(database, "Basis Data Relasional", "PostgreSQL", "Menyimpan profil pengguna dan riwayat buku besar")
}

4. Memetakan Hubungan Teknis

Alih-alih mengandalkan garis putus-putus dasar, C4 menggunakan format makro komunikasi yang eksplisit sebagaiRel(ID_Dari, ID_Tujuan, "Label", "Teknologi"). Ini menjaga peta arsitektur Anda sangat mudah dibaca dengan mewajibkan setiap koneksi menyatakan tujuannya dan protokol transportasi dasar (seperti HTTPS, gRPC, atau AMQP):

!include <C4/C4_Container>

Person(customer, "Pelanggan Perbankan", "Pelanggan dengan rekening bank pribadi")
System(banking_sys, "Sistem Perbankan Inti", "Menangani transaksi keuangan")
System_Ext(mail_sys, "Layanan Email", "Gerbang notifikasi SMTP internal")

System_Boundary(c1, "Ekosistem Sistem E-Commerce") {
    Container(web_app, "Aplikasi Halaman Tunggal", "React & TypeScript", "Menyediakan fitur pengguna melalui tampilan web")
    ContainerDb(database, "Basis Data Relasional", "PostgreSQL", "Menyimpan profil pengguna dan riwayat buku besar")
}
Rel(customer, web_app, "Menggunakan fitur toko online melalui", "HTTPS")
Rel(web_app, database, "Membaca dan menulis data transaksional melalui", "SQL/TCP")

Praktik Terbaik untuk Arsitektur C4 yang Mudah Dibaca

• Jangan Pernah Menggabungkan Tingkat Abstraksi:Pertahankan diagram Anda fokus pada satu lapisan. Jangan mencampur komponen perangkat lunak internal yang sangat rinci ke dalam peta Konteks Sistem tingkat tinggi. Jika suatu sistem menjadi terlalu kompleks, pisahkan menjadi diagram tingkat Container yang terpisah dan khusus.
• Tentukan Teknologi Secara Eksplisit:Selalu gunakan parameter keempat dalam makro AndaRel()untuk menyatakan teknologi atau protokol yang digunakan secara tepat (misalnya,"JSON/HTTPS" atau "JDBC"). Ini memberikan konteks implementasi penting bagi tim Anda dalam sekali pandang.
• Manfaatkan Ovveride Tata Letak Berarah: Jika komponen Anda mulai tumpang tindih secara tidak nyaman, gunakan makro hubungan berarah (seperti Rel_D() untuk bawah, Rel_R() untuk kanan, atau Rel_L() untuk kiri) untuk membersihkan alur arsitektur Anda secara manual.

Contoh Nyata PlantUML C4

Contoh 1: Tata Letak Konteks Sistem Tingkat Tinggi (Tingkat 1)

Rancangan fungsional ini memodelkan diagram Konteks Sistem Tingkat 1 standar, menjelaskan bagaimana pelanggan berinteraksi dengan aplikasi perbankan internet dan ketergantungan eksternalnya.

@startuml
!include <C4/C4_Context>

title Diagram Konteks Sistem untuk Sistem Perbankan Internet

Person(customer, "Pelanggan Perbankan Pribadi", "Pelanggan bank dengan rekening pribadi.")
System(banking_system, "Sistem Perbankan Internet", "Memungkinkan pelanggan melihat informasi keuangan dan melakukan transfer.")
System_Ext(mail_system, "Subsistem E-mail", "Klaster server email perusahaan internal perusahaan SendGrid.")

Rel(customer, banking_system, "Menggunakan dashboard online melalui")
Rel_R(banking_system, mail_system, "Mengirim pemberitahuan dan kode verifikasi menggunakan", "SMTP")
@enduml

Analisis Sintaks: Diagram ini berfokus murni pada cakupan tingkat tinggi. Makro System_Ext secara otomatis menerapkan profil warna abu-abu pada layanan email, secara visual memisahkan sistem inti dari ketergantungan eksternal. Makro Rel_R memaksa mesin tata letak untuk menempatkan node email tepat di sebelah kanan blok sistem perbankan.

Contoh 2: Topologi Wadah Mikroservis Penyelidikan Mendalam (Tingkat 2)

Rancangan perusahaan canggih ini memecah suatu sistem menjadi aplikasi wadah penyusunnya dan penyimpanan data terpisah, menunjukkan bagaimana lalu lintas web melewati gateway API hingga ke mikroservis backend.

@startuml
!include <C4/C4_Container>

title Diagram Wadah untuk Gateway Portal Pembayaran

Person(merchant, "Mitra Pedagang Web", "Mengintegrasikan titik akhir checkout platform ke situs web mereka.")

System_Boundary(portal_scope, "Ekosistem Gateway Pembayaran") {
    Container(api_gateway, "Proxy Routing API", "Nginx", "Menangkap panggilan masuk, menangani batas kecepatan dan menyeimbangkan node.")
    Container(auth_service, "Mikroservis Identitas", "Go & OAuth2", "Memvalidasi token API dan ruang lingkup pengembang.")
    Container(txn_service, "Buku Jurnal Transaksi", "Java Spring Boot", "Memproses pembayaran dan mengelola akun buku jurnal.")
    ContainerDb(ledger_db, "Penyimpanan Data Buku Jurnal", "CockroachDB", "Menerapkan skema tabel yang kompatibel dengan ACID secara terdistribusi.")
}

' Alirkan lalu lintas secara bersih melintasi target wadah internal
Rel(merchant, api_gateway, "Mengirim payload pembayaran melalui", "HTTPS/JSON")
Rel_D(api_gateway, auth_service, "Memvalidasi token masuk melalui", "gRPC")
Rel_D(api_gateway, txn_service, "Meneruskan tindakan checkout ke", "gRPC")
Rel_R(txn_service, ledger_db, "Menyimpan entri buku jurnal melalui", "SQL/TLS")
@enduml

Analisis Sintaks: Dengan menggunakan System_Boundary wrapper makro, komponen internal dikelompokkan dengan rapi di dalam kotak batas yang jelas. Makro khususContainerDb makro menampilkan penyimpanan data dengan ikon silinder basis data yang jelas, membuat pembagian antara runtime komputasi dan lapisan penyimpanan permanen menjadi jelas pada pandangan pertama.