Hexagonal Mimari — Bağımlılık Oku Hangi Yöne Bakıyor

Yurt dışına çıkınca bilgisayarını değiştirmezsin, yalnızca fişin ucundaki adaptörü değiştirirsin. Yazılımda ise çoğu zaman bilgisayarı prize lehimleriz.

Spring Boot projelerinin çoğu aynı üç klasörle başlar: controller, service, repository. Düzenli görünür. Ama service içindeki iş kuralı, bir JpaRepository’yi import ettiği anda verinin nasıl saklandığını bilmeye başlar.

Ok nereye bakıyor?

Klasik yapıda istek yukarıdan aşağı akar ve bağımlılıklar da aynı yöne bakar:

1
package com.shop.application;
2

3
import com.shop.infrastructure.OrderJpaRepository;   // JpaRepository<Order, Long>
4

5
@Service
6
public class PlaceOrder {
7
    private final OrderJpaRepository orders;
8
    …
9
}

Bu import bir oktur: application → infrastructure. Ok değişikliğin yayılacağı yönü gösterir. Veritabanını, sorgu stratejisini ya da Spring Data sürümünü değiştirdiğinde iş kuralını da açman gerekebilir.

Test tarafında da bedeli var. PlaceOrder’ı sınamak için ya bir veritabanı ayağa kaldırırsın ya da JpaRepository’nin onlarca metodunu taklit edersin.

Priz ve adaptör: oku çevirmek

Hexagonal mimari?Terimin tanımını açhexagonal mimariİş kuralını merkeze koyup dış dünyayla (veritabanı, HTTP, mesaj kuyruğu) yalnızca arayüzler üzerinden konuşan mimari. Bağımlılıklar her zaman merkeze doğru bakar.Sözlükte gör → iş kuralını merkeze koyar. Merkez, dış dünyadan ne beklediğini kendi arayüzleriyle tanımlar. Bu arayüzlere ve onları uygulayan sınıflara port ve adapter?Terimin tanımını açport ve adapterPort, iş kuralının dış dünyadan beklediğini tanımlayan arayüzdür ve iş kuralının paketinde durur. Adapter, onu belirli bir teknolojiyle (JPA, REST, Kafka) uygulayan sınıftır.Sözlükte gör → denir:

1
// com.shop.domain — iş kuralının dili
2
public interface OrderRepository {
3
    Order save(Order order);
4
    Optional<Order> findById(OrderId id);
5
}
6

7
// com.shop.infrastructure — teknolojinin dili
8
interface OrderJpaRepository extends JpaRepository<OrderEntity, Long> {}
9

10
@Component
11
class JpaOrderAdapter implements OrderRepository {
12
    private final OrderJpaRepository jpa;
13
    public Order save(Order order) { return jpa.save(OrderEntity.from(order)).toDomain(); }
14
    …
15
}

Artık PlaceOrder yalnızca OrderRepository’yi tanıyor. Ok infrastructure → domain yönünde: altyapı iş kuralına uyuyor, tersi değil. Bu, bağımlılığın tersine çevrilmesi?Terimin tanımını açbağımlılık tersine çevirmeİş katmanının neye ihtiyaç duyduğunu kendi tanımlaması, altyapının ona uyması. Arayüzün varlığı değil, hangi katmana ait olduğu belirleyicidir.Sözlükte gör → ilkesinin paket düzeyindeki hâlidir.

Spring tarafında ek bir şey gerekmez. PlaceOrder kurucusunda OrderRepository ister, Spring port’u uygulayan tek bean’i, yani adapter’ı enjekte eder.

Bir banka havalesinde görelim: testte port’u küçük bir sahte sınıfla değiştiriyoruz.

1
// Outgoing port: what the transfer rule needs, in its own words.
2
public interface Accounts {
3

4
    Optional<Account> byIban(Iban iban);
5

6
    void save(Account account);
7
}

1
@Service
2
public class SendInternalTransfer {
3

4
    private final Accounts accounts;
5

6
    public SendInternalTransfer(Accounts accounts) {
7
        this.accounts = accounts;
8
    }
9

10
    @Transactional
11
    public void send(Iban from, Iban to, Money amount) {
12
        Account source = accounts.byIban(from).orElseThrow(() -> new UnknownAccountException(from));
13
        Account target = accounts.byIban(to).orElseThrow(() -> new UnknownAccountException(to));
14

15
        source.debit(amount);    // refuses insufficient funds and a currency mismatch
16
        target.credit(amount);
17

18
        accounts.save(source);
19
        accounts.save(target);
20
    }
21
}

1
@Component
2
class JpaAccountsAdapter implements Accounts {
3

4
    private final AccountJpaRepository jpa;   // extends JpaRepository of AccountEntity
5

6
    JpaAccountsAdapter(AccountJpaRepository jpa) {
7
        this.jpa = jpa;
8
    }
9

10
    @Override
11
    public Optional<Account> byIban(Iban iban) {
12
        return jpa.findByIban(iban.value()).map(AccountEntity::toDomain);
13
    }
14

15
    @Override
16
    public void save(Account account) {
17
        // The entity carries the version column, so a concurrent update still fails loudly.
18
        jpa.save(AccountEntity.from(account));
19
    }
20
}

1
class SendInternalTransferTest {
2

3
    private static final Currency TRY = Currency.getInstance("TRY");
4
    private static final Iban ALICE = new Iban("TR330006100519786457841326");
5
    private static final Iban BOB = new Iban("TR320010009999901234567890");
6

7
    // A hand-written fake: the port is small enough to implement in a few lines.
8
    private final Map<Iban, Account> store = new HashMap<>();
9
    private final Accounts accounts = new Accounts() {
10
        public Optional<Account> byIban(Iban iban) { return Optional.ofNullable(store.get(iban)); }
11
        public void save(Account account) { store.put(account.iban(), account); }
12
    };
13

14
    @Test
15
    void movesMoneyBetweenTwoAccounts() {
16
        accounts.save(Account.open(ALICE, new Money(new BigDecimal("1000.00"), TRY)));
17
        accounts.save(Account.open(BOB, new Money(BigDecimal.ZERO, TRY)));
18

19
        new SendInternalTransfer(accounts).send(ALICE, BOB, new Money(new BigDecimal("250.00"), TRY));
20

21
        assertThat(store.get(ALICE).balance()).isEqualTo(new Money(new BigDecimal("750.00"), TRY));
22
        assertThat(store.get(BOB).balance()).isEqualTo(new Money(new BigDecimal("250.00"), TRY));
23
    }
24
}

Satır satır: kuralı ArchUnit ile korumak

Paket kuralını yazıya dökmek yetmez. İlk acele eden kişi domain’e bir JPA import’u ekler ve kimse fark etmez. Kural bir testte durmalı.

İlk kural kırmızı. Ya domain’deki @Entity’yi ayrı bir OrderEntity’ye taşırsın ya da kuralı bilinçli olarak gevşetirsin.

İkisi de meşru. Önemli olan, kararın testte görünür olması.

Kendin gör

Üç kararı değiştir, adımlayarak kodu, bağımlılık grafiğini, ArchUnit sonucunu ve veritabanı değişikliğinin etkisini gör.

1. Varsayılanla adımla. Repository infrastructure’da, entity’lerde JPA var. Grafikte iki kırmızı ok, veritabanını değiştirmek üç pakete dokunuyor.
2. Repository’yi port’a çevir. application → infrastructure oku kayboluyor, yerine infrastructure → domain geliyor. Use case artık sahte bir repository ile test edilebiliyor.
3. Domain’deki JPA’yı kapat. Üç kural da yeşil, veritabanı değişikliği tek pakete indi.
4. Controller’ın repository’yi doğrudan çağırmasını aç. Tek bir kısayol, temiz grafiği yeniden bozuyor. Üç görevi de tamamla; sonuncusu bilinçli bir ödün.

Tuzaklar

CRUD servise hexagonal giydirmek. Korunacak bir iş kuralı yoksa her tablo için port, adapter ve iki model arasında dönüşüm yalnızca dosya sayısını artırır. Spring Data repository’yi doğrudan kullanmak dürüst bir seçimdir.

İki model, iki kat bakım. Domain’de saf Order, infrastructure’da OrderEntity tutmak domain’i JPA’dan tamamen kurtarır ama her alan için bir dönüşüm yazmayı gerektirir.

Pek çok ekip @Entity’yi domain’de bırakır ve yalnızca port’u uygular. Bu bir ödündür; kuralı da buna göre yaz.

Katmana göre paketlemek. controller/, service/, repository/ klasörleri bir özelliği dört yere dağıtır.

Özelliğe göre paketle (order/, payment/) ve katmanları her özelliğin içine koy. Sınırlar paket sınırı olur; Spring Modulith ya da ArchUnit ile doğrulanabilir.

Her şey için bir port. Her use case için ayrı bir giriş port’u, her tablo için ayrı bir çıkış port’u açmak, kalıbı törene çevirir. Port bir ihtiyaçtır; ihtiyaç yoksa port da yoktur.

Kendini sına