Gerçekçi Bir Örnekle C4 Modeli

C4 modelini anlatmak kolaydır, yanlış uygulamak da. Birçok ekip sonunda kullanıcıları, mikroservisleri, Java sınıflarını ve bulut kutularını tek bir dev diyagramda karıştırır; C4 tam da bunu önlemek için tasarlandı. Bu rehber eksiksiz bir C4 model diyagram örneği üzerinden ilerliyor: tek bir kurgusal sistem, 1., 2. ve 3. seviyelerde çiziliyor. Böylece her diyagrama neyin girdiğini, kimin okuduğunu ve tipik hataların nerede başladığını görebilirsiniz.

Bir dakikada C4 modeli

Simon Brown tarafından geliştirilen C4 modeli, yazılım mimarisini yakınlaştırılabilen bir dizi diyagramla anlatır. Her seviye farklı bir kitle için farklı bir soruyu yanıtlar.

C4'te "container", kendi başına çalışan veya veri saklayan her şeydir: web uygulaması, API, worker, veritabanı, mesaj kuyruğu veya topic. Özellikle bir Docker container'ı kastedilmez. C4 şekil veya renk değil, soyutlamalar tanımlar; notasyon size kalmıştır. Resmî kaynak: c4model.com.

Örnek sistem: Folio, bir online kitapçı

Somut kalmak için kurgusal bir sistem kullanacağız. Folio, basılı kitap ve e-kitap satan hayalî bir online kitapçıdır; gerçek bir şirket değildir.

• Müşteriler kataloğa göz atar, kitap satın alır ve e-kitap indirir.
• Back-office ekibi kataloğu, stoku ve fiyatları yönetir.
• Folio üç harici sisteme bağımlıdır: bir ödeme sağlayıcı, bir e-posta gönderim servisi ve depo partnerinin fulfilment sistemi.

Seviye 1: System Context diyagramı

Context diyagramı Folio'yu tek bir kutu olarak ve etrafındaki her şeyi gösterir. Hiçbir iç detay yoktur.

• Customer (Person): kitaplara göz atar ve satın alır.
• Back-office Staff (Person): kataloğu, stoku ve fiyatları yönetir.
• Folio (Software System, kapsam içinde): müşterilerin basılı kitap ve e-kitap almasını sağlar.
• Payment Provider (Software System, harici): kart ödemelerini onaylar ve tahsil eder.
• Email Service (Software System, harici): sipariş ve kargo e-postalarını iletir.
• Fulfilment System (Software System, harici, depo partnerine ait): basılı siparişleri toplar, paketler ve gönderir.

Her ilişki, amacı belirten bir etiket alır:

• Customer → Folio: "Kitaplara göz atar ve satın alır"
• Back-office Staff → Folio: "Katalog ve stoku yönetir"
• Folio → Payment Provider: "Kart ödemelerini bununla alır"
• Folio → Email Service: "Sipariş e-postalarını bununla gönderir"
• Folio → Fulfilment System: "Basılı siparişleri buraya gönderir"

Kimin için: ürün yöneticileri, yeni katılanlar, güvenlik incelemecileri, diğer ekipler. Okuyucunun anlamak için hızlı bir bakıştan fazlasına ihtiyacı varsa, diyagram fazla kalabalıktır. Protokoller ve teknolojiler genellikle bu seviyede yer almaz.

Seviye 2: Container diyagramı

Folio'nun içine yakınlaşın. Kişiler ve harici sistemler yerinde kalır; Folio, container'larını çevreleyen bir boundary'ye dönüşür.

İlişkiler artık amaç ve protokol taşır:

• Web Storefront → API Application: "Kataloğu okur, sipariş verir [JSON/HTTPS]"
• API Application → Main Database: "Okur ve yazar [SQL/TCP]"
• API Application → Payment Provider: "Ödeme oluşturur ve tahsil eder [HTTPS]"
• API Application → Order Events Queue: "OrderPaid olaylarını yayınlar [AMQP]"
• Order Worker → Order Events Queue: "OrderPaid olaylarını tüketir [AMQP]"
• API Application → E-book Store: "E-kitap dosyaları için indirme linklerini imzalar [HTTPS]"
• Order Worker → Fulfilment System: "Basılı siparişleri iletir [JSON/HTTPS]"
• Order Worker → Email Service: "Onay e-postaları gönderir [HTTPS]"

Kimin için: mühendisler, mimarlar ve SRE'ler. Günlük işte genellikle en faydalı C4 diyagramı budur: design review'da ekrana yansıttığınız ya da yeni bir ekip üyesine verdiğiniz diyagram. Nelerin olmadığına dikkat edin: Pod'lar, VPC'ler, load balancer'lar. Bunların yeri deployment diyagramıdır.

Seviye 3: Component diyagramı

Tek bir container'a, API Application'a yakınlaşın. Her container için component diyagramı gerekmez; iç yapısı açıklama gerektirecek kadar karmaşık olanlar için çizin.

• Catalogue Controller (Spring MVC REST controller): arama ve kitap detay endpoint'leri.
• Checkout Controller (Spring MVC REST controller): sepet ve ödeme endpoint'leri.
• Order Service (Spring service): sepeti doğrular, sipariş oluşturur, olay yayınlar.
• Payment Gateway Client (Spring component): ödeme sağlayıcının API'sini sarmalar.
• Order Repository (Spring Data JPA): siparişleri kalıcı hale getirir.
• Catalogue Repository (Spring Data JPA): kitapları, fiyatları ve stoku okur.

İlişkiler 2. seviyedeki kuralı izler; örneğin Order Service → Payment Gateway Client "Ödeme tahsilatı ister" ve Order Repository → Main Database "[SQL/TCP]".

Kimin için: o container'ın sahibi olan geliştiriciler. Component diyagramları en hızlı eskiyen diyagramlardır.

Seviye 4, Code: elle çizmeyin. Gerektiğinde sınıf diyagramlarını IDE'nizden üretin.

C4 diyagramlarını okunur tutan notasyon ipuçları

• Her kutuda dört şey olsun: ad, eleman tipi, teknoloji ve tek satırlık sorumluluk.

API Application
[Container: Java, Spring Boot]
Provides catalogue, ordering and account functionality via a JSON/HTTPS API.

• Her ilişkiyi etiketleyin: amaç ve 2. seviyeden itibaren protokol. Sadece "Kullanır" yazan bir ok okuyucuya hiçbir şey söylemez.
• Her ok tek yönlü olsun ve kaynağın bakış açısından anlatılsın.
• Bir anahtar (legend) ekleyin: şekilleri, renkleri, çizgi stillerini ve kısaltmaları açıklayın. Kesikli çizginin ne anlama geldiğini söyleyene kadar hiçbir anlamı yoktur.
• Her diyagrama başlık verin: tipini ve kapsamını yazın, örneğin "Container diyagramı: Folio".
• Kapsamdaki sistemin boundary'sini çizin ki okuyucu neye sahip olduğunuzu ve neyi çağırdığınızı görsün.

Sık yapılan hatalar

1. Doğrudan component'lere atlamak. Context ve container görünümü olmadan okuyucu bir component'in nerede yaşadığını ve neden var olduğunu bilemez.
2. Seviyeleri karıştırmak. Aynı diyagramda bir Person, bir Pod ve bir Java sınıfı varsa hiçbiri iyi anlatılmaz.
3. Etiketsiz oklar. Amaç veya protokol içermeyen çizgiler okuyucuyu tahmine zorlar ve herkes farklı tahmin eder.
4. Code seviyesini elle çizmek. Bitirdiğiniz günün ertesinde güncelliğini yitirir.
5. Container diyagramına altyapı koymak. Namespace'ler, subnet'ler ve instance tipleri deployment diyagramına aittir.

Tamamlayıcı diyagramlar: deployment ve dynamic

C4 destekleyici görünümler de tanımlar. İkisi özellikle işe yarar:

• Deployment diyagramı: container'ları altyapıya eşler. Folio için bu, Kubernetes cluster'ında Deployment olarak çalışan API Application ve Order Worker, yönetilen veritabanı olarak PostgreSQL ve object storage'daki E-book Store olabilir. Kubernetes ve bulut detayının yeri burasıdır.
• Dynamic diyagram: belirli bir akışı numaralı adımlarla gösterir, örneğin "Müşteri e-kitap satın alır": 1) Storefront ödemeyi gönderir, 2) API ödemeyi tahsil eder, 3) API OrderPaid yayınlar, 4) Worker indirme linkli e-postayı gönderir.

Bu C4 model diyagram örneğini Archboard'da oluşturmak

Archboard'da Person, Software System, Container, Component ve Database node'ları ile boundary'leri içeren bir C4 Model paketi var. Bunlar genel şekiller değil, port'ları olan birinci sınıf node'lardır; ilişkiler port'tan port'a bağlanır.

1. Google veya GitHub ile giriş yapın ve bir diyagram oluşturun.
2. Seviye 1: iki Person node'u (Customer, Back-office Staff), Folio için bir Software System node'u ve ödeme, e-posta ve fulfilment sistemleri için üç External System node'u ekleyin. Port'ları bağlayın ve her kenarı amacıyla etiketleyin.
3. Seviye 2: Folio için bir boundary ekleyin; Web Storefront, Admin Portal, API Application, Order Worker, Order Events Queue ve E-book Store için Container node'ları, Main Database için bir Database node'u yerleştirin. Ad, teknoloji ve sorumluluğu doldurun, ardından kenarları amaç ve protokolle etiketleyin.
4. Seviye 3: API Application için bir boundary ekleyin ve içine Component node'larını yerleştirin.
5. Legend ve notlar: anahtar için Core öğelerinden bir Markdown bloğu veya Table kullanın; her seviyeyi sonsuz canvas'ta kendi alanında tutmak için bir Frame kullanın.
6. Yanına deployment görünümü: C4 görünümleri, Kubernetes ve Cloud paketleriyle aynı canvas'ta durabilir. API Application ve Order Worker için Deployment, Service ve Ingress node'larını içeren bir Namespace frame'ini, uyguladığı container görünümünün hemen yanına çizin.

Archboard bir canvas olduğu için her görünümü bilinçli olarak çizersiniz: Her seviyede neyin yer alacağına siz karar verirsiniz. C4 node'ları aynı board'da Kubernetes ve Cloud paketi node'larının yanında durur; böylece deployment görünümü container görünümünün hemen yanında yaşar.

Free planda bir diyagram 15 diyagram node'u + 150 not, metin, çıkartma ve zihin haritası konusu içerir; bu, Folio gibi bir sistem için diyagram başına bir C4 seviyesine yeter. Tüm seviyeleri tek canvas'ta istiyorsanız Pro, node ve diyagram limitlerini kaldırır. C4 iş akışları hakkında daha fazlası: C4 kullanım senaryosu.

Ücretsiz şablon

C4 container view örneği, Bu örneği kullan ile çalışma alanınıza kopyalayabileceğiniz herkese açık bir diyagramdır. Boundary yerleşimi için kullanın, ardından her kenarı yukarıda anlatıldığı gibi amaç ve protokolle etiketleyin.

SSS

Dört seviyenin hepsine ihtiyacım var mı? Hayır. Çoğu ekip en büyük faydayı context ve container diyagramlarından alır. Component diyagramlarını seçici ekleyin, code seviyesi görünümleri yalnızca gerekirse üretin.

C4 container'ı bir Docker container'ı mı? Hayır. Veritabanları ve single-page app'ler dahil, ayrı çalıştırılabilen veya deploy edilebilen her birimdir. Docker'da çalışabilir de, çalışmayabilir de.

Kubernetes detayları nereye gider? Deployment diyagramına. Container diyagramını sorumluluklar ve iletişim üzerine tutun.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez