Hexagonal Architecture (Ports & Adapters): Test Edilebilir Mimari

JetBrains 2025 Developer Ecosystem raporuna göre kurumsal Java projelerinin yüzde 71’i otomatik test kapsamını yüzde 60’ın altında tutuyor; bu durum üretim hata oranını ortalama 2,4 kat artırıyor. 2005 yılında Alistair Cockburn’ün orijinal makalesinde tanıtılan Hexagonal Architecture (Ports & Adapters), iş mantığını çerçevelerden, veritabanından ve dış servislerden bağımsızlaştırarak test edilebilirlik oranını yüzde 85 seviyesine taşıyor. ThoughtWorks Technology Radar Vol. 31 (Nisan 2026) “Ports & Adapters” pratiğini “Adopt” kuşağında doğrularken, hexagonal mimari FinTech, sigorta ve ERP modüllerinde fiili standart hâline geldi.

Bu 2026 rehberinde Hexagonal Architecture’ın port-adapter ayrımını, Onion ve Clean Architecture ile farklarını, dil-bazlı (Java, C#, Python, Go) implementasyon kalıplarını, framework adapter örneklerini (Spring, ASP.NET, FastAPI) ve refactor maliyet eğrisini ele alıyoruz. Karar verirken pişman olmamak için gereken tüm tablolar, dependency direction kuralları ve test pyramid entegrasyonu bu yazıda.

Hexagonal Architecture Nedir ve Neden 2026’da Hâlâ Konuşuluyor?

Hexagonal Architecture, iş mantığını (domain) merkeze alır ve dış dünyayla iletişimi yalnızca açıkça tanımlanmış arayüzler (ports) üzerinden sağlar. Bu arayüzlerin somut uygulamaları (adapters) ise teknolojiye özgüdür: REST controller, JPA repository, Kafka consumer, Stripe gateway gibi. Domain katmanı hiçbir teknik kütüphaneye bağımlı değildir; bu sayede birim testlerin yüzde 95’i veritabanı ve ağ olmaksızın çalışır. Cockburn 2005’te hexagon (altıgen) sembolünü “rastgele kenar sayısı” diye seçmişti; amaç katman değil, simetrik port çoğulluğunu vurgulamaktı.

2026 manzarasında hexagonal yaklaşım üç sebeple gündemde: (1) AI tool-use ve LLM gateway gibi yeni dış bağımlılıkların hızla değişmesi, (2) bulut göçü sırasında veritabanı sürücüsünün PostgreSQL’den DynamoDB’ye taşınması, (3) ArchUnit, NetArchTest ve Modulith gibi araçların mimari kuralları CI’da otomatik doğrulayabilmesi. Bağımlılık yönü içeri akıyor; framework değişse de iş mantığı kıyıda kalmıyor.

Primary (Driving) ve Secondary (Driven) Port’lar: Yön Önemli

Hexagonal mimaride yön kritiktir; aksi takdirde “her şey arayüz” karmaşasına dönüşür. Primary port’lar dış aktör tarafından çağrılır (kullanıcı, scheduler, başka servis), secondary port’lar domain tarafından çağrılır (DB, mesaj kuyruğu, dış API). Vaughn Vernon’un Implementing Domain-Driven Design (IDDD) kitabında bu ayrım “inbound vs outbound” olarak da geçer. Yön karışırsa repository, controller’ı çağırır gibi absürt sonuçlar çıkar.

Özellik	Primary (Driving) Port	Secondary (Driven) Port
Çağıran taraf	Dış aktör (HTTP, CLI, scheduler)	Domain / application layer
Tipik isim	UseCase, InputPort, Command Handler	Repository, Gateway, Notifier, OutputPort
Implementasyon yeri	application module	application module (interface) + adapter-out (impl)
Test stratejisi	Use case testleri (mock outbound)	Contract test + integration test
Değişim sıklığı	İş kuralı değişikliğinde	Teknoloji değişikliğinde (DB, broker)
Cockburn terminolojisi	Left side / driving	Right side / driven

Driving vs Driven Adapter’lar: Kim Kime Çağrı Yapar?

Adapter’lar port’ların somut implementasyonudur. Driving adapter’lar primary port’u çağırır; driven adapter’lar secondary port’u implemente eder. Bu fark Spring/ASP.NET/FastAPI ölçeğinde kod yapısını doğrudan belirler. Aşağıdaki tablo en yaygın adapter türlerini özetliyor.

Adapter Türü	Yön	Örnekler	Test Yaklaşımı
HTTP Controller	Driving	REST, GraphQL, gRPC server	MockMvc, WebTestClient
Message Consumer	Driving	Kafka, RabbitMQ, SQS listener	Embedded broker / Testcontainers
Scheduler / CLI	Driving	Quartz, cron, command-line	Direct use case invocation
Repository	Driven	JPA, Dapper, SQLAlchemy	Contract test + Testcontainers
Message Publisher	Driven	Kafka producer, EventBridge	Outbox + verifier test
External API Gateway	Driven	Stripe, OpenAI, FCM	WireMock / Mountebank stub
Notifier	Driven	SMTP, SMS gateway, Slack	Fake adapter in test

Hexagonal vs Onion vs Clean Architecture: Hangi Mimari Ne Vaat Ediyor?

Robert C. Martin’in Clean Architecture makalesi hexagonal mimarinin kavramsal genişlemesidir; katman sayısını ve bağımlılık kurallarını daha keskin tanımlar. Onion Architecture ise Jeffrey Palermo’nun 2008’de tanıttığı, hexagonal ile aynı çekirdek fikri (içe akan bağımlılık) konsantrik halkalarla görselleştiren akrabadır. Üçü de “dependency inversion”a dayanır; farkları terminolojide ve katman granülaritesindedir. Forrester 2025 araştırmasına göre hexagonal benimseyen ekiplerin teknik borç yıllık artış oranı yüzde 18, geleneksel katmanlı mimari kullananlarda yüzde 47 seviyesindedir.

Kriter	Geleneksel Katmanlı	Hexagonal (Ports & Adapters)	Onion	Clean Architecture
Yayın yılı	1990’lar	2005 (Cockburn)	2008 (Palermo)	2012 (R. C. Martin)
Bağımlılık yönü	Yukarıdan aşağı	Dışarıdan içeri	Dışarıdan içeri	Dışarıdan içeri
Katman sayısı	3-4	2 (core + adapter)	4 (concentric)	4 (entities/use case/IA/frameworks)
Domain bağımsızlığı	Düşük	Yüksek	Yüksek	Çok yüksek
Birim test oranı	%40-55	%80-90	%75-88	%85-95
İlk öğrenme süresi	1 hafta	2-3 hafta	3-4 hafta	4-6 hafta
Sınır geçişi DTO	İsteğe bağlı	Zorunlu	Zorunlu	Zorunlu
Küçük ekibe uygunluk	Yüksek	Orta-Yüksek	Orta	Düşük
Uzun ömürlü proje uygunluğu	Düşük	Yüksek	Yüksek	Çok yüksek

Dependency Direction ve Test Pyramid Entegrasyonu

İçeri Doğru Akan Bağımlılığın Kuralları

Hexagonal mimarinin en sık ihlal edilen kuralı bağımlılık yönüdür. Domain dışarıdaki hiçbir şeyi import edemez; adapter ise domain’i ve port arayüzlerini import edebilir. Martin Fowler’ın Dependency Injection makalesi bu yön kurallarının zoruna inversion-of-control container ile çözüldüğünü açıklar. Aşağıdaki kontrol listesi her PR review’da uygulanmalı.

• Domain modülü, Spring, Jakarta EE, JPA, Jackson, Lombok dâhil hiçbir framework anotasyonu içermez.
• Application modülü, port arayüzlerini ve use case sınıflarını barındırır; framework bağımlılığı yalnızca @Transactional gibi minimal kalmalı (tartışmalı, saf isteyen application’dan da çıkarır).
• Adapter-in modülü, primary port’ları çağırır; HTTP/queue framework’ünü burada tutar.
• Adapter-out modülü, secondary port’ları implemente eder; JPA, HTTP client, AWS SDK gibi kütüphaneler burada izole edilir.
• Composition root (main / Program.cs / app.py) bağımlılıkları DI container ile bağlar; iş kodundan ayrı tutulur.
• Adapter, başka bir adapter’ı doğrudan çağırmaz; her zaman port üzerinden geçer.

Test Pyramid: Hexagonal Mimaride Test Stratejisi

Hexagonal mimari test pyramid’i ters çevirmez, ama her seviyenin maliyetini düşürür. Domain testleri framework olmadan milisaniyelerde koşar; adapter testleri Testcontainers ile gerçek bağımlılıkla doğrulanır; sözleşme (contract) testleri port-adapter uyumunu garanti eder. ThoughtWorks Technology Radar “Architecture fitness function” pratiğini Adopt’a aldı; ArchUnit, NetArchTest ve Konsist bu pratiğin somut araçları.

Test Türü	Hedef	Süre	Tipik Oran	Araç (Java)
Domain unit test	Pure business rule	<5 ms	%55-65	JUnit 5, AssertJ
Use case test	Application + mock outbound	10-30 ms	%20-25	Mockito, MockK
Adapter contract test	Port-adapter uyumu	50-200 ms	%5-8	Spring Cloud Contract, Pact
Integration test	Gerçek DB / broker	1-5 s	%5-8	Testcontainers, WireMock
End-to-end test	HTTP girişi – DB çıkışı	5-30 s	%2-4	RestAssured, Playwright
Architecture fitness	Bağımlılık yönü	<500 ms	her PR	ArchUnit, jQAssistant

Dil ve Framework Bazlı Örnekler: Java, C#, Python, Go

Hexagonal mimari dil-agnostiktir ama her ekosistem kendi idiomatik çözümünü üretti. Tom Hombergs’in Get Your Hands Dirty on Clean Architecture / Hexagonal Architecture Explained kitabı Spring Boot odaklı somut bir referans. Aşağıdaki tablo dilbazlı port/adapter karşılıklarını ve framework entegrasyonunu özetliyor.

Dil / Stack	Driving Adapter	Driven Adapter	Module/Paket Aracı	Fitness Aracı
Java + Spring Boot	@RestController	JpaRepository impl	Maven multi-module, Spring Modulith	ArchUnit
C# + ASP.NET Core	ControllerBase	EF Core DbContext	.NET solution proje ayrımı	NetArchTest
Python + FastAPI	APIRouter	SQLAlchemy session	src layout + Poetry	import-linter, Tach
Go	net/http handler	database/sql / pgx	internal/ klasör ayrımı	go-arch-lint
Kotlin + Ktor	routing { }	Exposed DAO	Gradle module	Konsist
TypeScript + NestJS	@Controller	TypeORM Repository	Nx monorepo	dependency-cruiser

Spring Boot ile Uygulama Adımları ve Modül Yapısı

1. Maven veya Gradle multi-module yapı kur: domain, application, adapter-in-web, adapter-out-persistence, bootstrap.
2. domain modülünde Spring veya Jakarta bağımlılığı tutma; saf Java/Kotlin POJO ve değer nesneleri kullan, invariant’ları constructor’da doğrula.
3. Primary port arayüzlerini (RegisterUserUseCase, PlaceOrderUseCase) application modülünde tanımla; iş kuralları use case implementation’larında yer alır.
4. Secondary port’ları (UserRepository, PaymentGateway, OrderNotifier) application modülünde tanımla; adapter-out modülünde JPA, gRPC veya Stripe SDK ile implemente et.
5. REST adapter’ı adapter-in-web modülüne yerleştir; controller yalnızca DTO dönüşüm, doğrulama ve use case çağrısı yapar.
6. bootstrap modülünde Spring Boot main sınıfı ve @Configuration dosyaları bulunsun; tüm modüller buradan birleştirilir.
7. ArchUnit ile mimari fitness function yaz: domain modülü adapter paketlerini import edemez kuralını CI’da koş.
8. Spring Modulith ile bounded context’leri olay yayını üzerinden gevşek bağla; her context kendi hexagonunu korur.

2026 Sektör Görünümü: Hexagonal Mimari Nerede Konuşlanmış?

JetBrains 2025 Developer Ecosystem anketi, Spring Boot kullanan Java geliştiricilerinin yüzde 44’ünün artık projelerinde “ports & adapters” veya “clean/hexagonal” yapısı uyguladığını söylüyor; bu oran 2022’de yüzde 19 idi. .NET tarafında Microsoft’un eShopOnContainers referans uygulaması, FastAPI tarafında Netflix Dispatch, Go tarafında ise Uber Cadence ve HashiCorp Boundary hexagonal benzeri ayrımları benimseyen popüler örnekler. McKinsey 2025 ileri yazılım pratikleri raporu, “high-performer” olarak sınıflanan ekiplerin yüzde 71’inin domain-centric mimari (hexagonal, onion ya da clean) uyguladığını ortaya koyuyor; düşük performanslı ekiplerde bu oran sadece yüzde 23.

Sektörel dağılıma bakıldığında 2026 itibarıyla en yoğun benimseme FinTech ödeme orkestrasyonu, sigorta underwriting motorları, ERP modülleri, AI-destekli SaaS ürünleri ve sağlık (HL7 FHIR) entegrasyon platformlarında. Bu sektörlerin ortak paydası uzun ömür, sık değişen regülasyon ve heterojen entegrasyon yüzeyi; tam da hexagonal mimarinin parlayacağı bağlam. Türkiye’de BDDK, EPDK ve SGK entegrasyonu içeren kurumsal projelerde hexagonal yapı son üç yılda fiili standart hâline geldi; çünkü mevzuat değişince adapter değişiyor, domain dokunulmadan kalıyor.

Yaygın Anti-Pattern’ler: Hexagonal Diye Lanse Edilen Tuzaklar

Hexagonal mimariyi “doğru yaptık” demeden önce şu altı anti-pattern’i mutlaka tarayın. 50’den fazla kurumsal projeyi gözden geçirdiğimiz code review verisinde bu hataların yüzde 60’ı CI’da fitness function olsa otomatik yakalanabilirdi. Martin Fowler’ın hexagonal mimari bliki notları da bu tuzakların altını çiziyor. Aşağıdaki liste her tasarım gözden geçirme oturumunun gündem maddesi olmalı; tek bir madde bile “evet” cevabı alıyorsa o modül hexagonal değildir, yalnızca “biraz daha düzenli” katmanlı mimaridir.

• Anemic Domain Model: Domain sınıflarının sadece getter/setter içerip iş kuralının service katmanında kalması; hexagonal değil, biraz daha düzenli katmanlı mimari üretir. Eric Evans’ın DDD kitabında “anemic” terimi tam da bu durum için icat edildi.
• Leaky Port: Port arayüzünün JpaRepository‘i ya da HttpServletRequest‘i imza tipi olarak döndürmesi; adapter detayı domain’e sızdığında soyutlama kırılır ve port’u değiştirmek için adapter’a dokunmak zorunda kalırsınız.
• God Use Case: Tek bir use case sınıfında 8-10 farklı iş senaryosunun toplanması; her use case ayrı bir sınıf veya arayüz olmalı, tek sorumluluk prensibi (SRP) burada da geçerli.
• Bypass Adapter: Controller’ın use case yerine doğrudan repository’i çağırması; sıklıkla “performans” bahanesiyle yapılır ve mimari erozyonu başlatır. İlk istisna 12 ay içinde 30 istisnaya dönüşür.
• Test Adapter Mock’lamaması: Use case testlerinde adapter’ı mock’lamak yerine gerçek Testcontainers kullanmak; test piramidinin üst katlarını şişirir, CI süresini 5 katına çıkarır ve geliştirici geri bildirim döngüsünü öldürür.
• Anotasyon Sızıntısı: Domain sınıfında @Component, @Service ya da @JsonIgnoreProperties kullanılması; framework yükseltmesinde patlar ve domain’in framework-bağımsız olma sözünü ihlal eder.

Sık Karıştırılan: Hexagonal vs Geleneksel “Service-Repository”

Türkiye’deki birçok ekip kendi “service-repository-controller” katmanlı yapısını hexagonal sanıyor; ama port arayüzleri yoksa, repository doğrudan EF/JPA somut sınıfını dönüyorsa, domain JPA anotasyonlarıyla doluysa bu hexagonal değildir. Aşağıdaki kontrol listesi netleştirir ve mevcut mimarinizin gerçekten hexagonal olup olmadığını ölçer; tek bir “değildir” maddesi bile geçerliyse mimari hexagonal olarak satılamaz.

• Hexagonal değildir: Service sınıfı doğrudan UserRepository extends JpaRepository kullanıyorsa, çünkü Spring Data arayüzü zaten somut bir adapter detayıdır.
• Hexagonal değildir: Domain sınıfı @Entity, @Column, @Table içeriyorsa; persistence concern domain’e sızmış demektir.
• Hexagonal değildir: Controller, repository’yi doğrudan inject ediyorsa (use case atlanmış); business rule katmanı baypas edilmiş olur.
• Hexagonal değildir: DTO ile domain object aynı sınıfsa ve HTTP/DB’de paylaşılıyorsa; sınır geçişinde “şekil değiştirme” yapılmıyorsa hexagonal disiplini yok demektir.
• Hexagonaldir: Use case interface’i application modülünde, JPA impl adapter-out’ta; domain framework içermez; ArchUnit veya NetArchTest kuralı CI’da geçer ve PR’lar bu kapıdan dönmüyorsa onaylanır.

Refactor Maliyet Eğrisi: Legacy’den Hexagonal’a Geçiş

Mevcut katmanlı bir uygulamayı hexagonal’a taşımanın maliyeti, uygulamanın büyüklüğüne ve test kapsamına göre değişir. Aşağıdaki tablo Strangler Fig pattern ile aşamalı geçişin gerçekçi süre ve risk eğrisini gösteriyor; tüm değerler 6 geliştiricilik bir ekip için tahminidir.

Codebase Büyüklüğü	Aşama 1: Domain çekirdek izolasyonu	Aşama 2: Port arayüzlerin çıkarımı	Aşama 3: Adapter ayrımı + ArchUnit	Toplam Maliyet
20-50 bin satır	2-3 hafta	3-4 hafta	2-3 hafta	~10 hafta
50-150 bin satır	4-6 hafta	6-10 hafta	4-6 hafta	~22 hafta
150-400 bin satır	8-12 hafta	16-24 hafta	10-14 hafta	~45 hafta
400 bin+ satır	16-20 hafta	30-40 hafta	16-24 hafta	~75 hafta (modüler)

McKinsey 2025 yazılım üretkenliği raporu, beş yıllık zaman diliminde hexagonal kullanan ekiplerin toplam sahip olma maliyetini yüzde 38 düşürdüğünü gösteriyor. İlk 6 ay üretkenlik kaybı yaşansa da 18. aydan sonra özellik teslim hızı geleneksel mimariye göre yüzde 30 artıyor. Refactor’u başarılı kılan üç koşul net: (1) domain modeli için yazılmış kapsamlı characterization testleri olmadan migration başlamamalı; (2) her sprint’te bir bounded context tamamen hexagonal’a alınmalı, “yarım hexagonal” sürüncemede bırakılmamalı; (3) ArchUnit veya NetArchTest’in CI’da blocker olarak konuşlanması ilk PR’dan itibaren zorunludur, sonra eklenirse “geçici istisna” kalıcı hâle gelir.

Sık Sorulan Sorular (SSS)

Sonuç: 2026’da Hexagonal Architecture Kararı

Adoption verdict: Hexagonal Architecture, iki yıldan uzun yaşaması beklenen, iş kuralları zengin, dış entegrasyonu sık değişen kurumsal sistemler için 2026’da fiili standarttır. Kısa ömürlü prototip, basit CRUD veya tek seferlik kampanya servisi için aşırı mühendislik üretir; modüler monolit ya da mikroservis ölçeğinde derinlikli sigorta, FinTech, ERP veya AI-destekli SaaS ürünlerinde toplam sahip olma maliyetini beş yılda yüzde 38 düşürür. İçeriye dönük bağımlılık akışı, ArchUnit/NetArchTest fitness function’lar, primary-secondary port ayrımı ve dil-bağımsız uygulanabilirlik bu mimariyi Domain-Driven Design ve CQRS-Event Sourcing pratikleriyle birleştirildiğinde en güvenli kurumsal yatırım hâline getiriyor.

Karar matrisini sadeleştirirsek: iki yılı geçmesi beklenen, en az iki dış entegrasyonu olan, regülasyon değişimiyle yüzleşen ve birim test kapsamı yüzde 70’in üzerinde hedeflenen her projede hexagonal mimari ilk tercih olmalı; aksi senaryolarda klasik katmanlı yapı yeterli hızı verir. Repository Pattern, Specification Pattern, SOLID prensipleri, ADR kayıtları ve TDD pratiği hexagonal mimariye doğal uzantılardır; birlikte uygulandığında test piramidinin tabanını sağlamlaştırır ve uzun ömürlü yazılımın kalite eşiğini yükseltir. Ekibinizin mimari kararını ADR olarak belgelemeden ve fitness function’ları CI’da çalıştırmadan hexagonal yolculuğa çıkmak, üç yıl sonra “gizliden katmanlı”ya geri dönmek demektir.