de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

Memperbesar Hingga Paling Dalam: Memahami Diagram Kode C4 – Apa Itu, Kapan Menambah Nilai, dan Contoh Praktis PlantUML

Apa itu Diagram Kode C4?

Diagram Kode adalahTingkat 4— tingkat paling dalam dan paling rinci dalam model C4 Simon Brown.

The Ultimate Guide to C4 Model Visualization with Visual Paradigm's AI Tools - ArchiMetric

Menunjukkan:

  • Kelas, antarmuka, enum, rekam, atau konstruksi tingkat kode lainnya yang menerapkan komponen tertentukomponen (dari Tingkat 3).

  • Hubungan antara kelas-kelas tersebut (pewarisan, komposisi, ketergantungan, realisasi antarmuka, dll).

  • Elemen desain utamaelemen desain seperti pola yang diterapkan di dalam komponen (misalnya, penyimpanan, layanan, DTO, entitas domain, pabrik).

Dalam praktiknya, tingkat ini hampir selalu merupakandiagram kelas UML (atau varian yang disederhanakan) yang berfokus pada satu (atau sangat sedikit) komponen.

Penjelasan penting:

  • Tingkat 4 adalahbukan tentang seluruh kode sumber.

  • Ini adalahbukandiperlukan untuk menampilkan setiap kelas.

  • Ini memetakan hanya struktur yang esensialyang dibutuhkan untuk memahami bagaimana komponen yang kompleks atau kritis sebenarnya dibangun.

  • Rekomendasi resmi C4: idealnya dihasilkan secara otomatisdari kode sumber (melalui alat seperti Doxygen, Javadoc + plugin UML, yWorks, Structurizr, CodeSee, dll.) daripada digambar secara manual.

Kapan Membuat Diagram Kode

Buat diagram Level 4 secara hemat — hanya dalam situasi-situasi berikut:

  • Komponen ini adalah sangat kompleks, kritis bagi misi, atau sulit dipahamihanya dari kode sumber saja (misalnya, logika domain yang rumit, penggunaan berat pola desain, aliran kriptografi, mesin keadaan, kode lama yang penuh dengan utang teknis).

  • Anda sedang bekerja di bidang industri yang sangat diatur (keuangan, kesehatan, kedirgantaraan, pertahanan) di mana auditor atau tim kepatuhan menuntut pemetaan eksplisit dari arsitektur → desain → implementasi.

  • Selama refaktor besar, menghambat komponen lama, atau memperkenalkan pola arsitektur baru (hexagonal, bersih, potongan vertikal, agregat DDD) — tampilan sebelum/sesudah membantu menyampaikan perubahan tersebut.

  • Onboarding pengembang senior atau arsitek yang perlu memahami dengan cepat struktur internal yang tidak jelas dari suatu kode berisiko tinggi.

  • Anda telah menginvestasikan pada generasi otomatis alat bantu — sehingga pemeliharaan Level 4 hampir tidak membutuhkan biaya.

  • Tim telah sepakat bahwa “dokumentasi hidup” pada tingkat kelas sangat berharga untuk subsistem khusus ini.

Jangan membuat diagram Level 4 ketika:

  • Struktur komponen jelas dari penamaan yang baik, ukuran kecil, atau kode bersih (kebanyakan mikroservis modern termasuk di sini).

  • Anda sudah memiliki uji unit/integrasi yang baik, antarmuka yang jelas, dan komentar penjelas.

  • Sebagian besar tim dapat menavigasi kode dengan mudah.

  • Biaya pemeliharaan melebihi manfaatnya (diagram kelas yang digambar tangan menjadi usang sangat cepat).

Simon Brown dan kebanyakan praktisi menekankan: Kebanyakan tim tidak pernah membutuhkan Level 4. Level 1 + 2 menutupi 80–90% kebutuhan komunikasi; Level 3 menangani sebagian besar sisanya. Level 4 adalah pengecualian, bukan aturan.

Mengapa Menggunakan Diagram Kode? (Ketika Mereka Menambah Nilai)

  • Jembatani arsitektur ↔ implementasi — Menunjukkan bagaimana komponen tingkat tinggi sebenarnya direalisasikan dalam kode.

  • Perjelas desain internal yang kompleks — Mengungkap penggunaan pola (Strategy, Factory, Decorator, Repository), pelanggaran lapisan, keterikatan erat, atau pemodelan domain yang cermat.

  • Dukung audit & kepatuhan — Menunjukkan bahwa keputusan arsitektur diimplementasikan hingga ke kode.

  • Mendukung diskusi refactoring & migrasi — Struktur kelas sebelum/sesudah membuat proposal menjadi nyata.

  • Kurangi ‘pengetahuan suku’ — Membantu rekrutan senior baru memahami bagian-bagian yang kompleks lebih cepat daripada membaca semua file sumber.

  • Versi yang dihasilkan otomatis menjadi ‘dokumen hidup’ — Jika alat sudah tersedia, mereka tetap akurat dengan usaha hampir nol.

Cara Membuat Diagram Kode yang Hebat (Langkah demi Langkah + Praktik Terbaik)

  1. Pilih SATU komponen — Biasanya dari diagram Level 3 di mana kompleksitas internal membenarkan pembesaran.

  2. Putuskan: digambar tangan atau dihasilkan otomatis?

    • Digambar tangan → hanya untuk lokakarya, proposal, atau area yang terlalu kacau untuk alat otomatis.

    • Dihasilkan otomatis → disukai (PlantUML masih bisa digunakan untuk menata/gaya output).

  3. Fokus pada hal-hal penting — Tunjukkan:

    • Kelas/antarmuka utama

    • Hubungan penting (→ ketergantungan, — komposisi, <| realisasi, ^ warisan)

    • Agregat, entitas, objek nilai (gaya DDD)

    • Pola kritis atau anti-pola yang ingin Anda soroti

  4. Jaga agar tetap kecil — Maksimal 8–15 kelas. Jika lebih besar → bagi menjadi diagram fokus (misalnya, ‘potongan Autentikasi’, ‘entitas pemrosesan pesanan’).

  5. Praktik Terbaik

    • Lebih baik pilih generasi otomatis kapan pun memungkinkan (lebih sedikit usang).

    • Gunakan sintaks PlantUML classDiagram sintaks — bersih dan dapat dikelola versinya.

    • Tambahkan catatanuntuk keputusan yang tidak jelas (misalnya, “Menggunakan Model Domain Anemik – direncanakan refaktor”).

    • Hindari menampilkan semuanya— abaikan getter/setter biasa, kelas utilitas.

    • Simpan di repo → perlakukan sebagai kode (komit file .puml di dekat komponen).

    • Gunakan secara bijak — satu per komponen kompleks, bukan per mikroservis.

    • Gabungkan dengan tampilan dinamis (sequence/kolaborasi) jika alur saat runtime lebih penting daripada struktur statis.

Contoh PlantUML – Komponen Autentikasi (perluasan gaya Big Bank plc)

Berikut adalah contoh Level 4 yang realistis yang memperbesar bagian Komponen Keamanan / Autentikasi dari diagram Aplikasi API sebelumnya.

@startuml
title C4 Level 4 – Diagram Kode: Autentikasi di Dalam Aplikasi API

skinparam monochrome true
skinparam shadowing false
skinparam class {
  BackgroundColor White
  BorderColor Black
  ArrowColor Black
}

abstract class AuthenticationProvider {
  + authenticate(credentials): Authentication
}

class JwtAuthenticationProvider {
  - tokenProvider: JwtTokenProvider
  - userDetailsService: UserDetailsService
  + authenticate(credentials): Authentication
}

class JwtTokenProvider {
  - secretKey: String
  - validityInMilliseconds: long
  + generateToken(userDetails): String
  + validateToken(token): boolean
  + getUsernameFromToken(token): String
}

interface UserDetailsService {
  + loadUserByUsername(username): UserDetails
}

class DatabaseUserDetailsService {
  - userRepository: UserRepository
  + loadUserByUsername(username): UserDetails
}

class UserRepository {
  + findByUsername(username): Optional<User>
}

class User {
  - username: String
  - passwordHash: String
  - roles: Set<Role>
}

class JwtAuthenticationToken << (T,orchid) Authentication >> {
  - principal: UserDetails
  - credentials: Object
  - authorities: Collection<GrantedAuthority>
}

' Hubungan
JwtAuthenticationProvider -up-> JwtTokenProvider : menggunakan
JwtAuthenticationProvider -up-> UserDetailsService : menggunakan
DatabaseUserDetailsService .up.|> UserDetailsService
DatabaseUserDetailsService --> UserRepository : menggunakan
UserRepository --> User : mengembalikan

JwtAuthenticationToken .up.|> Authentication

note right of JwtAuthenticationProvider
  Alur autentikasi utama untuk sesi tanpa status berbasis JWT
end note

note bottom of JwtTokenProvider
  Menandatangani & memverifikasi JWT menggunakan HS512
end note

@enduml

Diagram kecil ini:

  • Hanya berfokus pada bagian dalam autentikasi

  • Menampilkan kelas kunci, antarmuka, dan ketergantungan

  • Menyoroti pola (penyedia, penyimpanan)

  • Menggunakan catatan untuk konteks

Tempelkan ke renderer PlantUML apa pun — sesuaikan untuk domain Anda (misalnya, ganti JWT dengan OAuth2, tambahkan kelas MFA, dll.).

Pengingat ringkasan: Level 4 sangat kuat tetapi langka. Gunakan secara sengaja, lebih pilih otomatisasi, dan jangan biarkan menjadi pekerjaan membosankan. Sebagian besar nilai C4 berasal dari Level 1–3. Selamat (pemodelan selektif)!

Sumber Daya

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