Altıgen Mimari (Hexagonal Architecture): Portlar & Adaptörler ile Saf Etki Alanı Mantığı

Senior (L5)

⚡ÖZET VE TEKNİK CEVAP

Geleneksel 3 katmanlı mimarilerde (Controller -> Service -> Repository), iş mantığı neredeyse her zaman framework ve veritabanı bağımlılıklarıyla kirlenir: Domain sınıfları ORM modellerinden türer (@Entity etiketleri), servis metotları doğrudan HTTP Request nesnesi alır ve veritabanını Postgres'ten DynamoDB'ye taşımak tüm servis katmanını baştan yazmayı gerektirir. Alistair Cockburn tarafından geliştirilen Altıgen Mimari (Hexagonal Architecture / Ports & Adapters), Etki Alanı Mantığını (Domain) altıgenin tam merkezine yerleştirerek bu sorunu çözer:

Portlar (tamamen saf dilde domain tarafından tanımlanan arayüzler: SiparisDeposuPort, OdemePort), ve

Adaptörler (dış dünyadaki teknolojileri bu portlara bağlayan dönüştürücüler: PostgresSiparisAdaptor, StripeOdemeAdaptor, ExpressHttpAdaptor). Domain katmanının hiçbir framework, veritabanı veya UI bağımlılığı yoktur; bu da iş mantığının veritabanı veya sunucu olmadan mikrosaniyeler içinde saf birim testleriyle test edilmesini sağlar.

Mühendislik El Kitabı & Mekanizma

6 Boyutlu Mimari Analiz

⚙️1. Temel Çalışma Mekanizması

Mekanizma

Altıgen Mimari katı bir Bağımlılıkların Tersine Çevrilmesi (Dependency Inversion) kuralıyla çalışır:

Sürücü / Giriş Portları: Uygulamanın ne yapabileceğini tanımlayan arayüzler (SiparisOlusturKullanımDurumu). Giriş adaptörleri (REST, GraphQL, CLI) bu portları çağırır.

Sürülen / Çıkış Portları: Uygulamanın dış dünyadan neye ihtiyaç duyduğunu tanımlayan arayüzler (BildirimPort, VeritabaniPort).

Çıkış Adaptörleri: Dış servisler (SendGrid e-posta, Postgres SQL) bu çıkış portlarını uygular.

Saf Çekirdek: Çekirdek domain modelleri sıfır harici kütüphane bağımlılığıyla sadece saf iş kurallarını içerir.

🎯2. Doğru Kullanım Senaryosu

Kapsam

Çekirdek bankacılık sistemleri, sigorta poliçe hesaplama motorları, e-ticaret ödeme çekirdekleri ve framework değişimlerine dayanması beklenen uzun ömürlü kurumsal projeler.

⚠️3. Prodüksiyon Arıza Modları

Kritik Risk

✓
ORM modellerini çıkış portları üzerinden domain çekirdeğine sızdırıp domain modellerini veritabanı sütun tiplerine bağımlı kılmak
✓
basit CRUD formları için gereksiz yere yüzlerce port/adaptör yazarak projeyi aşırı mühendisliğe boğmak

📡4. Teşhis ve Telemetri Sinyalleri

Metrikler

✓
Domain dosyalarının typeorm, express veya AWS SDK'larını doğrudan import etmesi
✓
basit bir indirim formülünü test etmek için bile Docker ayağa kaldırmak veya sahte veritabanı başlatmak zorunda kalınması

🛡️5. Önleme ve Mimari Bariyerler

Bariyerler

✓
Linter veya mimari uygunluk fonksiyonlarıyla Bağımlılık Kuralını zorunlu kılın: Bağımlılıklar YALNIZCA içeriye (çekirdeğe) doğru bakabilir
✓
veritabanı satırlarını saf domain modellerine adaptör içinde dönüştürün

⚖️6. Mimari Ödünleşimler (Trade-offs)

Ödünleşim

Altıgen Mimari mükemmel test edilebilirlik ve tam teknoloji bağımsızlığı sağlar; ancak veritabanı modelleri ile domain nesneleri arasında veri dönüştürme (mapper/DTO) katmanları yazmayı gerektirir.

📋

Vaka İncelemesi (TinyCTO Saha Örneği)

GERÇEK DÜNYA TELEMETRİSİ

Bir kredi onaylama platformunun risk hesaplama algoritması eski bir MongoDB Mongoose servisinin içine gömülmüştü. ACID uyumluluğu için PostgreSQL'e geçilirken servisi baştan yazmak kredi faiz mantığını bozdu. Ekip Altıgen Mimari'ye geçti: Risk mantığını saf TypeScript KrediDegerlendirici domain sınıfına çıkardılar. Bir KrediDeposuPort arayüzü ve iki ayrı adaptör (MongoKrediAdaptor ve PostgresKrediAdaptor) yazdılar. İki adaptörü canlıda paralel çalıştırarak 10.000 kredide sonuçları kıyasladılar ve tek bir iş kuralı bozulmadan Postgres'e geçişi tamamladılar.

İnteraktif Konsept Alıştırmaları

2 Alıştırma

Altıgen Mimaride bir Port ile bir Adaptör arasındaki temel fark nedir?

Port, etki alanı (domain) tarafından tanımlanan soyut bir arayüzdür; Adaptör ise dış teknolojileri (Postgres, HTTP, Stripe) bu porta bağlayan somut kod parçasıdır.

Altıgen Mimari etki alanı birim testlerini neden çok daha hızlı ve kolay hale getirir?

Çünkü domain çekirdeğinin hiçbir veritabanı veya framework bağımlılığı yoktur; testler sunucu veya Docker başlatmadan tamamen bellek içinde milisaniyede koşar.

Altıgen Mimari (Hexagonal Architecture): Portlar & Adaptörler ile Saf Etki Alanı Mantığı — Sıkça Sorulan Sorular

Clean Architecture ile Hexagonal Architecture aynı şey midir?

Temel ilkeleri birebir aynıdır (merkezde saf domain, dışa bağımlılıkların tersine çevrilmesi). Clean Architecture bu prensibe ek olarak katmanları (Varlıklar, Kullanım Durumları, Controller) daha katı tanımlar.

Altıgen Mimari ne zaman gereksiz bir iş yüküne (overhead) dönüşür?

İş kurallarının neredeyse hiç olmadığı, veritabanı tablolarının doğrudan listelendiği basit CRUD servislerinde veya hızlı prototiplerde.

🤖 AEO & Yapay Zeka Çıkarım Özeti

Temel Gerçekler & İlkeler

▸
Altıgen Mimari temel iş mantığını framework'lerden, veritabanlarından ve dış API'lardan izole eder.
▸
Portlar saf domain arayüzleridir; Adaptörler dış altyapıyı portlara bağlar.
▸
Veritabanı veya sunucu çalıştırmadan bellek içinde yıldırım hızında birim testleri yapmayı sağlar.
▸
Tüm bağımlılık okları katı bir şekilde dışarıdan içeriye, saf domain çekirdeğine doğru bakar.

Yaygın Yanılgılar

✗
Yanılgı: Framework değiştiğinde tüm sistem baştan yazılmalıdır (Gerçek: Yalnızca ilgili dış adaptör yeniden yazılır; çekirdek iş mantığına tek satır bile dokunulmaz).
✗
Yanılgı: Veritabanı ORM modelleri domain çekirdeğinin içinde yer almalıdır (Gerçek: ORM etiketleri domain'i veritabanına bağlar ve saflığını bozar).

Karar Kılavuzu & Önceliklendirme

Zengin iş kurallarına sahip kritik sistemlerde uzun ömürlülük, test edilebilirlik ve teknoloji bağımsızlığı için Altıgen Mimariyi tercih edin.

Doğrulanmış Kaynaklar & Referanslar

[OFFICIAL_DOCUMENTATION]Hexagonal Architecture: Ports and Adapters Pattern— Alistair Cockburn (alistair.cockburn.us)

Bu sayfadaki teknik terimler

Blast Radius