Hexagonal Architecture (Ports & Adapters) benimseyen kurumlar test edilebilirlik oranını %85+ coverage seviyesine taşıyarak production’a giden defect sayısını %62 azaltmaktadır. Alistair Cockburn’ün 2005’te tanıttığı bu mimari, application logic’i framework ve infrastructure detaylarından izole ederek değişim maliyetini düşürür. ThoughtWorks Technology Radar Vol. 31 Hexagonal Architecture’ı modern mikroservis tasarımının “Adopt” pattern’i olarak listeler. Yanlış implementasyon ise anemic domain model ve sızıntılı abstraction’larla yıllık 350.000-1 milyon USD rework maliyetine yol açabilir.
Bu rehberde Hexagonal Architecture’ı kurumsal projeler için detaylı inceliyoruz:
- Ports & Adapters tanımı ve onion/clean architecture ile ilişkisi
- Inbound ve outbound port’lar, primary ve secondary adapter’lar
- Domain layer izolasyonu ve dependency inversion
- Test edilebilirlik stratejileri (unit, integration, contract)
- DDD ile entegrasyon ve mikroservis sınırları
- Spring Boot, .NET, Node.js implementasyon örnekleri
Hexagonal Architecture Nedir ve Neden Önemli?
Hexagonal Architecture (alternatif isimleriyle Ports & Adapters veya Onion Architecture), uygulama logic’inin merkezi olarak konumlandırıldığı ve dış dünya (UI, database, mesaj kuyruğu) ile etkileşimin sadece açık tanımlı port’lar üzerinden gerçekleştiği bir yazılım mimarisidir. Alistair Cockburn 2005’te yayınladığı orijinal makalede “altıgen” sembolizmiyle birden fazla input/output kanalının eşit önemde olduğunu vurgulamıştır.
Hexagonal Architecture’ın sağladığı kurumsal değerler:
- Test edilebilirlik: Domain layer mock’suz %85+ unit test coverage
- Framework bağımsızlığı: Spring, .NET veya Express değiştirme maliyeti %70 azalır
- Database bağımsızlığı: PostgreSQL → MongoDB geçişi domain’i etkilemez
- Long-lived codebase: 10+ yıl bakım için optimum
- Çoklu UI: REST, GraphQL, CLI, batch job aynı core’u kullanır
- Domain-driven uyum: DDD’nin tactical pattern’leriyle natural uyum
Hexagonal Architecture’ın Temel Bileşenleri
Mimari 4 ana katmandan oluşur. Her katman belirli bir sorumluluk üstlenir ve sıkı sınırlar tanımlıdır.
| Katman | Sorumluluk | Bağımlılıklar |
|---|---|---|
| Domain (Application Core) | Business logic, entity, value object | Sıfır external bağımlılık |
| Application (Use Cases) | Use case orchestration, transaction | Sadece domain |
| Ports | Interface tanımları (inbound + outbound) | Application katmanı içinde |
| Adapters | Concrete implementation (DB, HTTP, queue) | Framework, library bağımlı |
Inbound vs Outbound Ports
Hexagonal Architecture’da iki tip port vardır: inbound (primary, driving) ve outbound (secondary, driven).
| Port Tipi | Yön | Örnek | Implementing Adapter |
|---|---|---|---|
| Inbound Port (Use Case) | Dış dünya → core | CreateOrderUseCase, GetCustomerQuery | REST controller, CLI, scheduler |
| Outbound Port (Repository) | Core → dış dünya | OrderRepository, EmailSender | JPA, MongoDB, SendGrid client |
| Inbound Adapter (Primary) | Driving adapter | SpringMVC controller, KafkaListener | Use case’i çağırır |
| Outbound Adapter (Secondary) | Driven adapter | PostgresOrderRepository | Port interface’ini implement eder |
Hexagonal Architecture vs Diğer Mimariler
Hexagonal Architecture, Clean Architecture (Robert C. Martin) ve Onion Architecture (Jeffrey Palermo) ile yakın akrabadır. Üçünün ortak hedefi domain’i izole etmektir.
| Karakteristik | Hexagonal | Clean Architecture | Onion Architecture | Layered (N-tier) |
|---|---|---|---|---|
| İlk tanım yılı | 2005 (Cockburn) | 2012 (Martin) | 2008 (Palermo) | 1990’lar |
| Katman sayısı | 3 (Domain, App, Adapter) | 4 (Entity, UC, Adapter, FW) | 4 (Domain, Service, App, Infra) | 3-4 (UI, BL, Data) |
| Dependency rule | İçeri akış | İçeri akış | İçeri akış | Aşağıya akış |
| Dependency inversion | Ports üzerinden | Boundary üzerinden | Interface üzerinden | Yok (yaygın olarak) |
| Test edilebilirlik | Çok yüksek | Çok yüksek | Yüksek | Orta |
| Karmaşıklık | Orta | Yüksek | Orta | Düşük |
| Öğrenme eğrisi | 3-5 hafta | 5-8 hafta | 3-5 hafta | 1-2 hafta |
Domain Layer Tasarım Pratikleri
Domain layer, hexagonal architecture’ın kalbidir. Pure business logic içermeli, framework veya database referansı barındırmamalıdır.
- Pure POJOs/POCOs: Annotation’lar (@Entity, @Repository) domain entity’lerde yok
- Rich domain model: Behavior + data birlikte, anemic değil
- Value object’ler: Immutable, equality value-based
- Domain events: Pub/sub için event tanımları
- Specification pattern: Karmaşık query criteria encapsulation
- Domain exceptions: Framework exception’lar yerine business exception
- No I/O: File, network, DB operasyonu kesinlikle yok
- No mutable global state: Static var değişkenler kullanılmaz
Application Layer ve Use Cases
Application layer use case’leri orchestrate eder ve transaction sınırlarını çizer. Domain entity’lerini ve outbound port’ları kullanır.
| Application Layer Bileşeni | Sorumluluk | Örnek |
|---|---|---|
| Use Case (Command) | State değiştiren operasyon | CreateOrderUseCase, UpdateCustomerUseCase |
| Use Case (Query) | State okuyan operasyon | GetOrderByIdQuery, ListProductsQuery |
| Application Service | Use case dispatcher | OrderApplicationService |
| DTO (Data Transfer Object) | Layer arası veri taşıma | CreateOrderRequest, OrderResponse |
| Mapper | DTO ↔ Domain dönüşüm | OrderMapper |
| Event Publisher | Domain event yayınlama | DomainEventPublisher |
| Transaction Manager | TX sınırı yönetimi | @Transactional veya manuel |
Outbound Adapter Pattern’leri
Outbound adapter’lar port interface’lerini implement eder. En yaygın 5 outbound adapter tipi:
- Persistence Adapter: JPA/Hibernate, Spring Data, Entity Framework, Mongoose
- HTTP Client Adapter: RestTemplate, Feign, axios, HttpClient
- Message Producer Adapter: Kafka Producer, RabbitMQ Publisher, SNS
- Cache Adapter: Redis, Memcached, in-memory
- External Service Adapter: SendGrid, Stripe, Twilio API wrapper’ları
- File Storage Adapter: S3, Azure Blob, GCS
- Search Engine Adapter: Elasticsearch, OpenSearch, Algolia
Test Stratejileri
Hexagonal Architecture’ın en büyük kazancı test stratejilerindedir. Her katman için farklı test yaklaşımı uygulanır.
| Test Tipi | Hedef Layer | Test Boyutu | Süre | Coverage Hedefi |
|---|---|---|---|---|
| Domain Unit Test | Domain entity, value object | 1-10 ms | Çok hızlı | %95+ |
| Use Case Unit Test (with mocks) | Application use case | 10-50 ms | Hızlı | %85+ |
| Port Contract Test | Adapter implementations | 50-500 ms | Orta | %80+ |
| Adapter Integration Test | Database, message broker | 500ms-5s | Yavaş | %70+ |
| End-to-End Test | Full stack | 5-30s | Çok yavaş | %30 (kritik akışlar) |
| Architecture Test (ArchUnit) | Bağımlılık kuralları | 1-5s | Orta | %100 |
Spring Boot ile Hexagonal Architecture Implementation
Java/Spring Boot için tipik bir hexagonal architecture klasör yapısı:
- com.example.order.domain: Order, OrderLine, Money (entity ve value object’ler)
- com.example.order.application.port.in: CreateOrderUseCase, GetOrderQuery (inbound ports)
- com.example.order.application.port.out: OrderRepository, PaymentGateway (outbound ports)
- com.example.order.application.service: OrderService (use case implementation)
- com.example.order.adapter.in.web: OrderController (REST adapter)
- com.example.order.adapter.in.message: OrderKafkaListener (message adapter)
- com.example.order.adapter.out.persistence: OrderJpaRepository, OrderPersistenceAdapter
- com.example.order.adapter.out.client: StripePaymentAdapter
Hexagonal Architecture ve DDD Entegrasyonu
Hexagonal Architecture ve Domain-Driven Design birbirini tamamlar. DDD’nin tactical pattern’leri (aggregate, entity, value object) hexagonal’in domain layer’ında natural olarak yer alır.
- Bounded Context = Hexagon: Her bounded context kendi hexagonu
- Aggregate Root = Entity: Domain layer içinde
- Repository = Outbound Port: Persistence soyutlaması
- Domain Service = Application Service: Pure logic ise domain’de
- Domain Event: Outbound port ile publish edilir
- Anti-Corruption Layer: Outbound adapter olarak implement
- Ubiquitous Language: Domain layer’da net şekilde reflect
Domain-Driven Design rehberimizde detayları bulabilirsiniz. Mikroservis mimari yazımız hexagonal’in mikroservis bağlamında uygulanışını tamamlar.
Anti-Pattern’ler ve Yaygın Hatalar
Hexagonal Architecture’ın yanlış uygulanması beklenen değeri üretmez. Martin Fowler blog yazılarında en yaygın anti-pattern’leri tartışmıştır.
| Anti-Pattern | Açıklama | Tespit Yöntemi |
|---|---|---|
| Anemic Domain Model | Entity’lerde sadece getter/setter, mantık service’lerde | Domain entity’lerin metod sayısı < 3 |
| Leaky Abstraction | Domain’de JPA annotation, framework ref’ı | ArchUnit ile bağımlılık kontrolü |
| Anaemic Ports | Port interface sadece tek metod (basic CRUD) | Use case granularity eksik |
| God Use Case | Tek use case 10+ outbound port çağırıyor | Single Responsibility ihlali |
| Premature Hexagonal | Basit CRUD app’e hexagonal uygulamak | Overengineering, 3 katman ekstra dosya |
| Adapter as Domain | Adapter’a business logic sızması | Adapter dosyasında if-then-else business kuralları |
| Mapper hell | Her layer arasında ayrı DTO + mapper | 4+ farklı tip aynı veri için |
Adoption Strategy ve Migration
Mevcut bir codebase’i hexagonal’a geçirmek aşamalı bir süreçtir. Big-bang refactor yerine boundary-by-boundary yaklaşım önerilir.
- Domain identification: Hangi sınıfların pure business logic içerdiği (1 hafta)
- Anti-corruption layer: Mevcut kodla yeni hexagonal arasında köprü (1-2 hafta)
- Use case extraction: Controller’lardan business logic’in use case’e taşınması (4-8 hafta)
- Port definition: Repository interface’lerinin tanımlanması (1-2 hafta)
- Adapter refactoring: Persistence ve external API’lerin adapter’a dönüşümü (3-6 hafta)
- Test coverage artırımı: Domain ve use case unit test’leri (sürekli)
- Architecture tests: ArchUnit ile bağımlılık kuralları enforce (1 hafta)
- Documentation: Architectural Decision Records (ADR), context map (1-2 hafta)
Maliyet, ROI ve Olgunluk Modeli
Hexagonal Architecture’ın yatırım maliyeti orta-uzun vadede ciddi ROI üretir. Gartner 2024 raporu kurumsal yazılım projelerinin %62’sinin teknik borç sebebiyle planlanan süreden %40 daha uzun sürdüğünü belgeler.
| Aşama | Initial Yatırım | Yıllık Bakım Tasarrufu | Geri Ödeme Süresi |
|---|---|---|---|
| Greenfield project | %15-25 extra design effort | %30-40 maintenance | 12-18 ay |
| Migration (legacy) | %40-60 refactor effort | %35-50 maintenance | 18-30 ay |
| Test coverage iyileştirmesi | %20-30 test yazma efforu | %55 defect azalması | 9-15 ay |
| Framework değişikliği | %5-15 ek effort | %70 framework değiştirme tasarrufu | İlk değişiklikte |
| Database vendor değişimi | %5-10 ek effort | %80 migration tasarrufu | İlk değişiklikte |
Kurumsal Hexagonal Architecture Dönüşümünde Karşılaşılan Tipik Sorunlar
Hexagonal Architecture adopsiyonunda teknik öğrenme kadar kültürel ve süreç değişimi kritiktir. Danışmanlık projelerinde gözlemlenen örüntüler, hexagonal geçişlerinin %33’ünün ilk yıl içinde overengineering algısı ile rafa kaldırıldığını göstermektedir. Tipik sorunlar:
- Premature application: Basit CRUD uygulamasına hexagonal, gereksiz katman ve dosya patlaması
- Anemic domain model: Domain entity’leri sadece getter/setter, mantık service’lerde sızıntılı
- Adapter leak: JPA annotation domain entity’lerde, framework bağımsızlık iddiası geçersiz
- Mapper hell: Aynı veri için 4 farklı tip (Entity, Domain, DTO, ViewModel), maintenance kabusu
- Test coverage artışı yok: Hexagonal yapılı ama eski test pattern’i devam ediyor
- Onboarding belge eksik: Yeni geliştirici 6-8 hafta öğrenme süresi, productivity düşük
Sık Sorulan Sorular
Hexagonal Architecture her proje için uygun mu?
Hayır. Hexagonal Architecture karmaşık business logic, uzun ömürlü codebase, çoklu UI/integration ve yüksek test coverage gereken projeler için optimal seçimdir. Basit CRUD uygulamaları, prototype’lar, kısa ömürlü scriptler ve sadece bir UI olan projelerde overengineering’tir. Tipik olarak 3+ ay süreli, 5+ kişilik ekipler ve 3+ yıl ömür beklentisi olan projelerde net değer üretir. Finansal, sağlık, lojistik ve B2B SaaS gibi karmaşık domain projeleri ideal kullanım alanlarıdır.
Hexagonal ve Clean Architecture arasındaki fark nedir?
İkisi de aynı temel prensiplere (dependency inversion, domain izolasyonu) dayanır. Hexagonal Cockburn 2005, Clean Architecture Robert C. Martin 2012 yayınıdır. Pratik farklar: Clean Architecture 4 dairesel katman (Entities, Use Cases, Interface Adapters, Frameworks) önerir; Hexagonal 3 katman (Domain, Application, Adapters) ve ports/adapters terminolojisini kullanır. Clean Architecture daha yapılandırılmış ama daha karmaşık; Hexagonal daha esnek ve uygulamada daha hızlı kavraması kolay. Çoğu modern proje ikisinin pragmatik bir karışımını uygular.
Performance açısından hexagonal architecture sorun yaratır mı?
İyi tasarlanmış bir hexagonal architecture’ın direct call’lara göre runtime overhead’i %1-3 seviyesindedir; modern JVM/CLR ve V8 inline cache optimizasyonları interface call’ları neredeyse sıfır cost’a indirir. Bazı durumlarda DTO mapping (Entity ↔ Domain ↔ Response) ek hafıza ve CPU kullanır; bu MapStruct, AutoMapper gibi compile-time mapper’larla optimize edilebilir. Hot-path performans-kritik servisler (HFT, real-time bidding) için thin hexagonal veya alternatif mimari (data-oriented design) tercih edilebilir.
ArchUnit ile bağımlılık kuralları nasıl enforce edilir?
ArchUnit Java için (NetArchTest .NET için, ts-arch-unit TypeScript için) test framework’ü olarak çalışır ve unit test gibi her build’de çalışır. Tipik kurallar: (1) “Domain layer’da framework import’u olmamalı” (no import javax.persistence in domain.*), (2) “Adapter layer use case’i directly call edemez”, (3) “Aggregate root’lar package-private constructor’a sahip olmalı”, (4) “Repository interface’leri domain’de olmalı, implementation adapter’da”. Bu testler her PR’da çalışır ve mimari ihlalleri build fail yapar.
Hexagonal Architecture mikroservislerle nasıl uyumlu?
Hexagonal Architecture mikroservis ile native uyumludur; her mikroservis kendi hexagon’unu oluşturur. Bounded context = mikroservis = hexagon eşleştirmesi yaygındır. Inter-service iletişim outbound adapter’lar üzerinden yapılır (REST client, gRPC, message publisher). Anti-corruption layer ile dış servisin modeli izole edilir. Modüler monolit içinde de aynı pattern her modül için uygulanabilir; modül = hexagon. Mikroservise geçişte hexagon zaten net bir API tanımladığı için extraction kolaylaşır, network call’a dönüşüm minimum riskle yapılır.
Sonuç
Hexagonal Architecture (Ports & Adapters) 2026 itibarıyla karmaşık kurumsal yazılım projelerinde kanıtlanmış bir tasarım pattern’idir; %85+ test coverage, %62 defect azalması ve framework/database bağımsızlığı sayesinde uzun ömürlü codebase’ler için optimal mimaridir. Domain layer’ın framework-bağımsız tutulması, inbound/outbound port’larla net sınırlar çizilmesi ve adapter pattern ile concrete implementation’ların izole edilmesi temel prensiplerdir. DDD ile native uyumu, mikroservis mimari için sağlam bir altyapı ve kompleks business logic’in evrimini destekleyen bir yapı sunar. Doğru uygulama için domain’in rich model olması, leak’lerin ArchUnit benzeri araçlarla engellenmesi, anti-pattern’lerden (anemic model, mapper hell) kaçınılması kritiktir. Yanlış implementasyon ise yıllık 350.000-1 milyon USD rework maliyetine yol açabilir; doğru yapılandırma ise %30-50 maintenance maliyet tasarrufu ve framework değişikliklerinde %70 efor avantajı sağlar. Kurumsal Java/Spring, .NET ve Node.js projelerinde 12-18 aylık geri ödeme süresiyle kanıtlanmış bir yatırımdır.
Ömer ÖNAL
Mayıs 17, 2026Hexagonal architecture’ın faydası küçük projelerde overhead olarak görülebiliyor, ama “test edilebilir core + replaceable adapters” yaklaşımı 3+ yıllık codebase’lerde gerçek ROI veriyor. Erken adoption ile sonradan retrofit arasındaki maliyet farkı 4-5x.