Clean Architecture Nedir? Katmanlar ve Dependency Rule 2026

Clean Architecture Nedir ve Neden Hala 2026’da Standart?

Clean Architecture, Robert C. Martin’in 2012’de “The Clean Architecture” makalesinde formüle ettiği, iş kurallarını (entities, use cases) framework, veritabanı, UI ve dış servislerden bağımsızlaştıran katmanlı yazılım tasarım yaklaşımıdır. Temel iddia tek cümleyle: bağımlılıklar her zaman içe doğru, soyutlamaya doğru akmalı; iş mantığı asla bir framework’e veya kütüphaneye köle olmamalı. Bu sayede framework değişikliği, veritabanı taşıma veya UI yeniden yazımı iş kurallarına dokunmadan yapılabilir.

2025 Stack Overflow Developer Survey’e göre profesyonel geliştiricilerin yaklaşık %48’i kurumsal projelerde “katmanlı / clean / hexagonal” türevi bir mimari kullandığını belirtti; bu oran 2020’deki ~%29 seviyesinden belirgin bir artış. GitHub’da “clean architecture” anahtar kelimesiyle eşleşen repo sayısı 14.000’i aştı (Mayıs 2026, GitHub Code Search). Üstelik .NET, Java, Go ve Python topluluklarının resmi template repolarında (örn. Microsoft eShop reference application, Spring Modulith örnekleri) Clean Architecture katmanlaması default şablon haline geldi.

2026’da bu mimarinin canlılığını koruma sebebi tek: değişim oranı. AI/LLM entegrasyonu, vector database eklenmesi, mesajlaşma altyapısının Kafka’dan Redpanda’ya taşınması veya Postgres’ten DynamoDB’ye geçiş — hepsinde iş mantığı aynı kalır, sadece “detaylar” değişir. Clean Architecture, detayı (frameworks & drivers katmanı) iş kuralından koruyan en olgun, en iyi belgelenmiş model olarak öne çıkıyor.

Dört Katman: Entities, Use Cases, Interface Adapters, Frameworks

Clean Architecture’ın klasik diyagramı 4 eş merkezli halkadan oluşur. İçten dışa: Entities → Use Cases → Interface Adapters → Frameworks & Drivers. Her halka kendi içindeki halkayı bilmez; dış halkalar iç halkalara port arayüzleri üzerinden bağlanır. Bu yapı, “Dependency Rule” dediğimiz tek altın kuralın somutlaşmış halidir.

Katman	Sorumluluk	Örnek Sınıflar	Bağımlılık Yönü	Test Tipi
Entities	Kurumsal iş kuralları, değişmez domain modelleri	Invoice, Customer, OrderLine	Hiçbir şeye bağlı değil	Saf unit test (mock yok)
Use Cases	Uygulama-spesifik iş akışları	CreateOrder, PayInvoice, RefundPayment	Sadece Entities’e	Unit test + fake port
Interface Adapters	Veri çevirici (Controller, Presenter, Gateway)	OrderController, PaymentGateway, OrderRepoImpl	Use Cases + Entities	Integration test
Frameworks & Drivers	Web, ORM, DB, mesajlaşma, dış API	Spring MVC, EF Core, Postgres, Kafka	Adapters üstünden bağlanır	E2E + contract test

En kritik kavramsal kırılma şudur: iş mantığı, framework’ün içine değil, framework iş mantığının dışına yazılır. Spring Boot bir @Service ile başlamaz; OrderUseCase arayüzünden başlar, Spring sadece bu arayüzü dışarıdan tutar. Bu ters çevirme (Dependency Inversion Principle), SOLID prensiplerinin “D” maddesinin doğrudan mimari ölçekte uygulanmış halidir.

Dependency Rule: İç Halkalar Dış Halkayı Bilmez

Clean Architecture’ın değiştirilemez tek kuralı şudur: Source code dependencies must point only inward. Pratikte bunun anlamı: UseCase sınıfı içinde import org.springframework.*, import jakarta.persistence.*, import io.lettuce.* görmek mimari ihlaldir. Use Case sadece OrderRepository arayüzünü bilir; bu arayüzün JPA, MongoDB veya in-memory implementasyonu olduğunu bilmez ve bilmemelidir.

• Doğru: Use Case katmanı interface NotificationPort { void send(Notification n); } tanımlar. Adapter katmanında SmtpNotificationAdapter implements NotificationPort bulunur.
• Yanlış: Use Case içinde doğrudan JavaMailSender kullanmak — Spring’e zincirlenmiş demektir.
• Avantaj: SMTP’yi SendGrid REST API’ye taşırken Use Case kodu hiç değişmez.
• Dezavantaj: Küçük projelerde 3-4 sınıf yerine 8-10 sınıf yazmak gerekir; başlangıç maliyeti %30-50 daha yüksektir.
• Ne zaman seç: Tahmini 3+ yıl ömür biçilen, framework/DB değişikliği ihtimali olan, 50.000+ LOC’a ulaşma potansiyeli olan projelerde.

Microsoft’un resmi Modern Web Apps for Azure rehberi, kurumsal .NET projeleri için tam olarak bu yaklaşımı önerir ve referans şablon olarak “ardalanmış” Clean Architecture katmanlamasını gösterir.

Use Case Katmanı: Uygulamanın Kalbi

Use Case (etkileşim katmanı), kullanıcı veya sistemin uygulamayla yapacağı her bir somut iş akışını temsil eder: SubmitOrder, CancelSubscription, GenerateMonthlyInvoice. Her use case tek bir public metoda sahip olmalı (Command pattern); girdisi DTO, çıktısı DTO. Use case asla HTTP, JSON, SQL bilmez.

Use Case Boyutu	Tipik LOC	Ortalama Geliştirme Süresi	Test Coverage Hedefi	Bakım Maliyeti (saat/ay)
Mikro (single CRUD)	30-80	2-4 saat	%95+	0.5
Orta (3-5 entity)	120-260	1-2 gün	%85-90	2-4
Karmaşık (saga / orchestration)	300-600	3-5 gün	%75-85	6-10
Cross-context (BC dışı çağrı)	250-500	4-7 gün	%70-80	8-12

Use Case’lerin Input → Validate → Authorize → Orchestrate → Persist → Notify → Output sekansını izlemesi, hem okunabilirliği hem de test yazımını kolaylaştırır. CQRS Event Sourcing uygulayan ekipler, Command ve Query Use Case’lerini ayrı sınıflara böler — bu, Clean Architecture’ın doğal genişlemesidir.

Domain Modelleme: Entities, Value Objects ve Invariants

Entities katmanı kurumsal iş kurallarını barındırır ve uygulamadan bağımsızdır. Aynı Customer sınıfı hem fatura sisteminde hem de CRM’de yaşayabilir; çünkü hiçbir framework’e bağlı değildir. Burada en kritik kavramlar: aggregate root, value object, invariant.

1. Aggregate Root: Tutarlılık sınırının sahibi. Order bir aggregate root’tur ve içindeki OrderLine‘lara dışarıdan doğrudan erişim yasaktır.
2. Value Object: Kimlik taşımaz, değeriyle eşittir. Money(amount, currency), Email("[email protected]") — değişmez (immutable) olmalı.
3. Invariant: Her zaman doğru olması gereken iş kuralı. “Bir Order’ın toplam tutarı 0’dan büyük olmalı” gibi. Setter değil, factory metodu içinde garanti edilir.
4. Domain Event: “OrderPlaced”, “PaymentFailed” gibi geçmişte olmuş olayları temsil eder; Saga Pattern ile dağıtık tutarlılığın temel taşıdır.

Eric Evans’ın 1996’da temellerini attığı bu modelleme yaklaşımı, Domain-Driven Design ile Clean Architecture’ın hayli üst üste binen kesişim noktasını oluşturur. Pratikte Clean Architecture’ı uygulayan ekipler genellikle taktiksel DDD desenlerini (entity, value object, repository, aggregate) iç halkalarda kullanır.

Interface Adapters: Veri Çevirici Köprü

Interface Adapter katmanı, dış dünyanın diline (HTTP, SQL, JSON, Kafka mesajı) ile iç dünyanın diline (Use Case Input/Output DTO, Domain nesnesi) arasında çevirmen rolü oynar. Üç ana rol: Controller (dışarıdan içeri), Presenter (içeriden dışarı), Gateway/Repository (iki yönlü).

Adapter Tipi	Yön	Sorumluluk	Anti-pattern	Doğru Örnek
Controller	Dış → İç	HTTP request’i Use Case Input DTO’ya çevirir	Controller içinde SQL yazmak	OrderController.create() sadece DTO çevirir, createOrderUseCase.execute() çağırır
Presenter	İç → Dış	Use Case Output’unu API response veya HTML’e çevirir	Use Case’in HTTP status code döndürmesi	OrderJsonPresenter 201/422 mapping’ini yapar
Repository	Çift yönlü	Domain ↔ DB satırı çevirisi	Domain entity’sinin JPA anotasyonu taşıması	Ayrı OrderEntity (JPA) + Order (domain) sınıfı
Gateway	Dış API	Üçüncü taraf servisle haberleşme	Use Case’in HTTP client’a doğrudan bağlanması	StripePaymentGateway implements PaymentPort
Message Adapter	İç ↔ Broker	Domain Event’i Kafka mesajına çevirir	Domain Event’in JSON anotasyonu olması	Ayrı OrderPlacedKafkaMessage DTO

Bu ayrım Repository Pattern ve Hexagonal Architecture‘ın ports & adapters mantığıyla bire bir aynıdır; aslında Clean Architecture, Alistair Cockburn’un 2005 Hexagonal modelinin genelleştirilmiş halidir. Martin Fowler’ın Inversion of Control makalesi, bu adapter ayrımının teorik zemininin en iyi anlatımlarından biri olmaya devam ediyor.

Frameworks & Drivers: En Dış Halka

En dış halka projenin değişken ve geçici kısmıdır: Spring Boot 3.4, ASP.NET Core 9, Express 5, Postgres 16, Kafka 3.7, Redis 7.4. Bu katman 5 yıl içinde tamamen değişebilir; iyi tasarlanmış Clean Architecture projesinde bu değişim iç halkaya hiç dokunmaz. 2024-2026 arası gözlemlenen pratik örnek: birçok ekip Spring Boot 2.x → 3.x Jakarta migration’ı, Clean Architecture sayesinde sadece infrastructure/ modülünü güncelleyerek 1-2 günde tamamladı.

• Web framework değişikliği: Spring MVC → WebFlux geçişinde Controller adapter’ları yeniden yazılır, Use Case dokunulmaz.
• ORM değişikliği: Hibernate → jOOQ → MyBatis arasında geçiş infrastructure/persistence/ klasörüyle sınırlı kalır.
• Mesajlaşma değişikliği: RabbitMQ → Kafka → NATS geçişlerinde Domain Event yapısı değişmez, sadece publisher adapter yenilenir.
• Cloud taşıma: AWS Lambda → Kubernetes ya da Cloud Run → Fargate geçişleri “main composition root”u değiştirir, geri kalan kod aynıdır.

Bu izolasyon CNCF’in 2025 Annual Survey‘inde de raporlanmış bir gerçeklik: katmanlı / port-adapter mimarisi uygulayan ekiplerin %62’si, framework upgrade işlemini ortalama bir sprint içinde tamamlayabildiklerini bildirdi.

Test Stratejisi: Halka Bazında Test Piramidi

Clean Architecture’ın getirdiği en büyük somut faydalardan biri test edilebilirliktir. Her halka için ayrı test stratejisi vardır ve hepsi birlikte sağlıklı bir test piramidi oluşturur. 2025 Stripe Engineering blog post’una göre, port-adapter izolasyonu uygulayan servislerde unit test coverage %88 ortalamayla, monolitik framework-coupled servislere göre yaklaşık 1.8x daha yüksek seyrediyor.

Test Tipi	Hedef Katman	Hız (per test)	Önerilen Adet/Servis	Bakım Maliyeti	Coverage Katkısı
Domain Unit	Entities	1-5 ms	200-800	Düşük	%40-50
Use Case Unit (fake port)	Use Cases	5-20 ms	150-500	Orta	%25-35
Adapter Integration	Adapters	200-800 ms	40-120	Orta-Yüksek	%10-15
Contract (Pact, Spring Cloud Contract)	Adapter sınırı	100-300 ms	10-30	Orta	%5
End-to-End	Tüm sistem	2000-8000 ms	5-20	Yüksek	%5-10

• Domain unit testleri mock kullanmaz; saf nesneler üzerinde invariant doğrulaması yapar — milisaniye altı çalışır.
• Use Case testleri in-memory fake port (örn. InMemoryOrderRepository) kullanır; binlerce test paralel olarak 10 saniyede tamamlanabilir.
• Adapter testleri Testcontainers ile gerçek Postgres/Kafka container ayağa kaldırır; ağır ama gerçeğe en yakın.
• Contract testleri servis sınırında uyumu garanti eder — Mikroservis Mimarisi bağlamında özellikle kritiktir.

Klasör Yapısı ve Modül Sınırları: 2026 Best Practice

Teorik halka diyagramı güzeldir, ama production projede klasör yapısı somut bir karar gerektirir. 2024-2026 arası gözlemlenen iki ana yaklaşım var: layer-first (entities/, usecases/, adapters/) ve feature-first (order/, payment/, billing/ — her özellik kendi katmanlarını barındırır). Büyük projelerde feature-first daha sürdürülebilir; Modular Monolith yaklaşımının doğal partneri budur.

Yapı Tipi	Tipik Klasör Sayısı	Avantaj	Dezavantaj	Önerilen Proje Boyutu
Layer-First	4 kök klasör	Öğrenmesi kolay, mimari görünür	Cross-cutting feature değişikliği zor	<30K LOC, <6 geliştirici
Feature-First	Feature başına 4 alt klasör	Yüksek cohesion, ekip izolasyonu	İlk öğrenme dik	30K-300K LOC, 6-30 geliştirici
Hybrid (feature içinde layer)	Feature × 4	İki dünyanın iyisi	Boilerplate fazla	100K+ LOC, çoklu takım
Bounded Context (modular monolith)	BC başına bağımsız modül	İleride mikroservise bölme kolay	Modül arası iletişim disiplini gerekir	200K+ LOC, 3+ takım

Build tool seviyesinde modül izolasyonunu zorlamak şart: Maven multi-module veya Gradle subprojects ile domain modülünün infrastructure‘a bağımlılığı imkansız hale getirilmeli. .NET tarafında ArchUnitNET, Java’da ArchUnit, .NET tarafında NetArchTest veya benzeri kütüphanelerle CI’da arch test yazmak, mimari erozyonu önlemenin en pragmatik yoludur. ArchUnit User Guide bu testlerin nasıl yazılacağını detaylı anlatır. Ömer Önal olarak danışmanlık verdiğim ekiplere ilk önerim, CI pipeline’a 5-6 arch test eklemek olur — çünkü mimari kararlar yazılı kurallarla değil, derleme zamanı checkler ile korunabilir.

Performans, Maliyet ve Pratik Sınırlar

Clean Architecture saf çalıştırma hızında %2-7 ekstra overhead getirebilir (ekstra arayüz çağrıları, DTO mapping). Modern JVM/CLR JIT optimizasyonları bu farkı çoğu senaryoda gürültü seviyesine indirir, ama hot-path latency-critical servislerde (örn. HFT, real-time bidding) ölçüm yapmadan kabul edilmemeli. 2025 Microsoft Build oturumunda paylaşılan bir benchmark, “anemic Clean Architecture .NET 9 servisi” ile “minimal API straight to EF Core” servisi arasında p99 latency farkını ~1.4 ms olarak ölçtü — çoğu B2B SaaS için kabul edilebilir bir maliyet.

• Avantaj: Framework upgrade’leri (Spring 6, .NET 9, Node 22 LTS) iç katmanı etkilemediği için risk profili belirgin azalır.
• Avantaj: Yeni ekip üyesinin onboarding’i hızlanır — Use Case dosyasına bakarak iş kuralı 5 dakikada anlaşılır.
• Dezavantaj: Tipik CRUD servisi için 3-5 sınıf yerine 8-12 sınıf yazılır — küçük servislerde “boilerplate fatigue” hissedilir.
• Dezavantaj: DTO mapping (MapStruct, AutoMapper) ek tooling getirir; eksik konfigürasyonda silent bug riski oluşur.
• Ne zaman seçme: 6 aylık MVP, sadece 1 geliştirici, deneysel ürün — burada framework-coupled minimal mimari daha sağlıklı.

Pragmatik bir referans: Uncle Bob’un orijinal “The Clean Architecture” yazısı (cleancoder.com) ve Jason Taylor’ın .NET Clean Architecture template’i (GitHub’da 17.000+ yıldız), 2026 itibarıyla hala en çok başvurulan iki kaynak olarak öne çıkıyor.

Yaygın Anti-Pattern’ler ve Düzeltme Reçeteleri

Clean Architecture projelerinde en sık karşılaşılan 7 hatayı ve bunların düzeltme reçetelerini bilmek, projenin 2-3 yıl sonra “kötü Clean Architecture” tuzağına düşmesini önler. Bu hatalar genellikle teorinin yüzeysel okunması ve build-time enforcement eksikliğinden doğar.

1. Domain entity’sinde JPA/EF anotasyonu: @Entity, @Table domain modeline değil, ayrı persistence entity’sine konmalı. Düzeltme: domain/Order.java ve infrastructure/persistence/OrderJpaEntity.java şeklinde iki sınıf.
2. Use Case’in HttpServletRequest alması: Use Case sadece DTO almalı. Düzeltme: Controller’da DTO’ya çeviri yap.
3. Domain’in Logger framework’üne bağımlı olması: SLF4J, Serilog gibi framework’ler infrastructure detayıdır. Düzeltme: Domain Event yayınla, infrastructure layer log alsın.
4. “Service” katmanının kendisi anemic olup, tüm mantığı bir OrderManager god class’a yığmak: Use Case başına 1 sınıf disiplini.
5. Repository’nin domain dışı arama metotları sızdırması: findAll() yerine findOpenOrdersByCustomer() gibi iş odaklı sorgular tanımla.
6. “Bus” / “Mediator” abstraksiyonunu zorla her yere koymak: Mediator iyi bir araçtır ama her CRUD için gerekmez; Yazılım Tasarım Desenleri seçimi bağlama göre yapılmalı.
7. Test pyramid’i tersine çevirmek: %70 E2E + %20 integration + %10 unit anti-pattern’i; Clean Architecture tam tersi piramidi mümkün kılar.

Bu hataların çoğu, ArchUnit/NetArchTest ile yazılan 10-15 kuralla derleme zamanında yakalanabilir. API Entegrasyon noktalarında özellikle dış sınır temizliği kritiktir; çünkü dış API’nin DTO’su sızdığında, kontrat değiştiğinde tüm uygulama kırılır.

Sık Sorulan Sorular

Sonuç

Clean Architecture, 2026’da hala kurumsal yazılım geliştirmede defansif bir yatırımdır: framework değişikliği, DB taşıma, UI yeniden yazımı gibi kaçınılmaz olayları öngörülebilir maliyetli hale getirir. Karar çerçevesi nettir — proje 20.000+ LOC, 3+ yıl ömür ve 2+ geliştirici bekliyorsa, ekstra %15-30 başlangıç boilerplate’i 2-3 yıl içinde 5-10x bakım kazancına dönüşür. Aksine, 3-6 aylık MVP veya tek geliştirici deneysel ürün için katman zorunluluğu zarar verebilir.

Başarılı uygulamanın anahtarı üç ayakta: (1) domain modelini framework’ten gerçekten izole etmek (anotasyonsuz entities, saf POJO/POCO sınıflar), (2) build-time arch test’leriyle mimari erozyonu önlemek (CI pipeline’da en az 5-7 kural), (3) test piramidini doğru tabandan kurarak unit test yatırımının kalıcı değerini korumak. Bu üç ayak eksik olduğunda Clean Architecture, “boilerplate üreten bürokrasi”ye dönüşür ve eleştirmenlerini haklı çıkarır; üçü birden sağlandığında ise framework değişimi, ekip rotasyonu ve scope büyümesi gibi olaylar kontrollü maliyetle yönetilebilir hale gelir.

Ekibinizin mevcut kod tabanında Clean Architecture geçişi planlıyor veya mevcut implementasyonun “kötü Clean Architecture” mı yoksa sağlıklı bir uygulama mı olduğunu değerlendirmek istiyorsanız, somut mimari incelemesi ve refactor yol haritası için iletişim sayfası üzerinden ulaşabilirsiniz.