Adapter ve Strategy: Dış Servisleri Domain'in Dışında Tutmak

Kurumsal bir uygulama er ya da geç başka bir sistemle konuşmak zorunda kalır. X firması size camelCase alanlardan oluşan bir JSON döner, Y firmasının gönderdiği şey ise geçen seneden kalma bir XML olabilir. Bir üçüncü firma ise size herhangi bir şey vermeden önce session token ister. Bunların hiçbiri sizin iş mantığınız değildir — ama gerekli önlemleri almazsanız hepsi dönüp dolaşıp iş mantığınızın içine girer.

Hedef söylemesi kolay, koruması ise daha zor bir şey: uygulamanın çekirdeği tek bir modeli bilmeli, sadece onu. Dış dünya hangi formatta gelirse gelsin, dönüşüm sınırda yapılır.

Bu yazıda bu işi birlikte yapan iki deseni Spring Boot tarafında ele alıyorum: farklılıkları gizlemek için Adapter, hangi adaptörün kullanılacağına karar vermek için ise Strategy.

Problemin şekli

graph LR
    C[Controller] --> UC["Use case"]
    UC -->|MenuResponse| P{{MenuAdapter}}
    P --> X[XFirmMenuAdapter]
    P --> Y[YFirmMenuAdapter]
    X -->|"X firması JSON"| XA[(X API)]
    Y -->|"Y firması XML"| YA[(Y API)]

MenuAdapter‘ın solundaki her şey sizin dilinizi konuşur, sağındaki her şey ise karşı tarafın dilini. Arayüz sınırdır, adaptörler ise o sınırdaki tercümanlardır.

Adapter: tek bir model üzerinde anlaşmak

İçeriden dışarıya doğru ilerleyin. Önce uygulamanızın gerçekten ihtiyaç duyduğu modeli tanımlayın, ardından bu modeli üreten portu oluşturun:

// Sistemin iç dünyasında bilinen tek menü modeli
public record MenuResponse(String menuId, List<String> items) {}

// Her adaptörün uygulayacağı port
public interface MenuAdapter {
    MenuResponse fetchMenu();
}

Burada dikkat edilmesi gereken iki nokta var, çünkü işin özü aslında bunlar:

• MenuResponse içinde, sırf X firması gönderiyor diye eklenmiş tek bir alan bile yok. X firma kırk alan gönderiyor olabilir; sizin sadece ikisine ihtiyacınız varsa record iki alanlıdır.
• Arayüz entegrasyonun değil, domain’in yanında durur. Adaptörler sizin soyutlamanıza bağımlıdır; tersi değil.

Adaptör de yaptığı iş yalnızca çeviri olan küçük ve sıkıcı bir sınıftır:

@Service
public class XFirmMenuAdapter implements MenuAdapter {

    @Override
    public MenuResponse fetchMenu() {
        return new MenuResponse("X-123", List.of("Kebap", "Ayran"));
    }
}

Gerçek bir entegrasyonda bunun içinde bir HTTP çağrısı ve ardından bir mapping olur. Yine de sınıfın sıkıcı kalması iyi bir şeydir — hatta olması gereken tam olarak budur. X firması kontratını değiştirdiğinde değişmesi gereken yer tek bir dosya olur.

Strategy: peki hangi adaptör çalışacak?

Asıl soru burada başlıyor. Elinizde iki adaptör ve tek bir arayüz var; bir şekilde hangisinin kullanılacağına karar vermeniz gerekiyor. Bunun doğru cevabı uygulamanın nasıl deploy edildiğine bağlı. Ve burada birbirinden gerçekten farklı iki senaryo var.

Senaryo A — single-tenant, açılışta seçim

Deployment müşteriye özelse çalışma zamanında seçim yapmaya gerek yoktur. @ConditionalOnProperty kullanarak Spring’in yalnızca o instance’ın ihtiyaç duyduğu adaptörü yüklemesini sağlayabilirsiniz:

// Yalnızca application.yml'da "integration.firm: X" yazıyorsa yaratılır
@Service
@ConditionalOnProperty(name = "integration.firm", havingValue = "X")
public class XFirmMenuAdapter implements MenuAdapter {

    @Override
    public MenuResponse fetchMenu() {
        return new MenuResponse("X-123", List.of("Kebap", "Ayran"));
    }
}

// Yalnızca application.yml'da "integration.firm: Y" yazıyorsa yaratılır
@Service
@ConditionalOnProperty(name = "integration.firm", havingValue = "Y")
public class YFirmMenuAdapter implements MenuAdapter {

    @Override
    public MenuResponse fetchMenu() {
        return new MenuResponse("Y-999", List.of("Pizza", "Kola"));
    }
}

Konfigürasyon tek satırdan ibaret ve firmanın adı geçen tek yer de burası:

integration:
  firm: X

integration:
  firm: Y

java -jar menu-service.jar --integration.firm=Y

Controller hangi adaptörü aldığını hiç bilmez:

@RestController
public class MenuController {

    private final MenuAdapter menuAdapter;

    public MenuController(MenuAdapter menuAdapter) {
        this.menuAdapter = menuAdapter;
    }

    // ... endpoint metotları
}

Desenin asıl değerini tam burada görüyorsunuz. MenuController, X veya Y firmasının varlığından haberdar olmadan çalışır.

Senaryo B — multi-tenant, istek bazında seçim

Şimdi SaaS tarafına geçelim. Tek deployment, birden fazla müşteri ve hangi firmanın kullanılacağı istekle birlikte geliyor: bir header, JWT claim’i veya subdomain üzerinden.

Burada @ConditionalOnProperty işinize yaramaz; tüm adaptörlerin aynı anda context’te bulunması ve hangi adaptörün kullanılacağının her çağrıda belirlenmesi gerekir.

Önce portumuza bir tanımlayıcı ekleyelim:

public interface MenuAdapter {
    String getFirmName();      // hangi firmayı temsil ettiği
    MenuResponse fetchMenu();
}

Ardından adaptörleri herhangi bir koşul olmadan kaydedelim:

@Service
public class XFirmMenuAdapter implements MenuAdapter {
    @Override public String getFirmName() { return "X"; }
    @Override public MenuResponse fetchMenu() { return new MenuResponse("X-123", List.of("Kebap")); }
}

@Service
public class YFirmMenuAdapter implements MenuAdapter {
    @Override public String getFirmName() { return "Y"; }
    @Override public MenuResponse fetchMenu() { return new MenuResponse("Y-999", List.of("Pizza")); }
}

Bu yapıyı kullanışlı hale getiren, Spring’in sık gözden kaçan bir özelliği: List<MenuAdapter> istediğinizde Spring bulduğu tüm implementasyonları size enjekte eder. Bunları constructor’da bir kez indeksleyebilirsiniz:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

@Service
public class MenuStrategyFactory {

    private final Map<String, MenuAdapter> adapterMap = new HashMap<>();

    // Spring, MenuAdapter'ı implemente eden tüm bean'leri toplayıp buraya verir
    public MenuStrategyFactory(List<MenuAdapter> adapters) {
        for (MenuAdapter adapter : adapters) {
            adapterMap.put(adapter.getFirmName(), adapter);
        }
    }

    public MenuAdapter getAdapter(String firmName) {
        MenuAdapter adapter = adapterMap.get(firmName);
        if (adapter == null) {
            throw new IllegalArgumentException("Desteklenmeyen firma: " + firmName);
        }
        return adapter;
    }
}

Map açılışta bir kez oluşturuluyor ve sonrasında değiştirilmiyor. Dolayısıyla lookup maliyeti yok denecek kadar az ve ayrıca senkronize edilmesi gereken bir yapı da kalmıyor.

public MenuStrategyFactory(List<MenuAdapter> adapters) {
    this.adapterMap = adapters.stream()
            .collect(Collectors.toUnmodifiableMap(
                    MenuAdapter::getFirmName,
                    Function.identity()));
}

Controller tenant’ı okur ve factory’den ilgili adaptörü ister:

@RestController
@RequestMapping("/api/menu")
public class MenuController {

    private final MenuStrategyFactory strategyFactory;

    public MenuController(MenuStrategyFactory strategyFactory) {
        this.strategyFactory = strategyFactory;
    }

    @GetMapping
    public MenuResponse getMenu(@RequestHeader("X-Tenant-ID") String tenantId) {
        // Gelen id "X" ise X adaptörü, "Y" ise Y adaptörü çalışır
        MenuAdapter adapter = strategyFactory.getAdapter(tenantId);
        return adapter.fetchMenu();
    }
}

Uçtan uca tek bir istek şöyle ilerler:

sequenceDiagram
    participant C as İstemci
    participant Ctl as MenuController
    participant F as MenuStrategyFactory
    participant A as YFirmMenuAdapter
    C->>Ctl: GET /api/menu (X-Tenant-ID: Y)
    Ctl->>F: getAdapter("Y")
    F-->>Ctl: YFirmMenuAdapter
    Ctl->>A: fetchMenu()
    A-->>Ctl: MenuResponse
    Ctl-->>C: 200 + MenuResponse

Üçüncü bir firma eklemek

Bir yapının gerçekten iyi olup olmadığını büyürken anlarsınız. Z firması pazartesi günü sözleşmeyi imzaladı:

Karar matrisi

İki satırda da aynı adaptörleri kullanıyoruz. Bu bilinçli bir tercih. Single-tenant başlayıp daha sonra multi-tenant’a geçerseniz değişecek olan şey anotasyon ve factory olur; entegrasyon kodu değil.

Bunun testlerde karşılığı

Kolayca gözden kaçan kısım burası. Use case yalnızca MenuAdapter‘a bağlı olduğu için onu test etmek için ne HTTP’ye, ne WireMock’a, ne de ağa ihtiyacınız var:

MenuAdapter fake = () -> new MenuResponse("TEST-1", List.of("Kebap"));

Tek metotlu bir arayüz aynı zamanda lambda olarak kullanılabilir. Adaptörlerin kendisi yine gerçek sağlayıcıya karşı entegrasyon testini hak eder; ancak asıl önemli hataların bulunduğu iş mantığı milisaniyeler içinde test edilebilir.

Altta yatan kural

Controller’larınız ve use case’leriniz X, Y, Z firmalarının varlığından haberdar olmamalı. Bildikleri tek şey MenuResponse olmalı.

Yukarıdaki her şey bu tek cümlenin hizmetinde. Bir kod parçasının adaptöre mi yoksa domain’e mi ait olduğundan emin olamadığınızda kendinize şunu sorun: sağlayıcı yarın değişse hangi tarafın değişmesi gerekirdi? Cevap çoğu zaman doğru sınırı gösterir.