Pada modul sebelumnya kita sudah membahas bagaimana SOLID dan hexagonal architecture memaksa kita memisahkan domain dari detail infrastruktur. Modul ini masuk ke level implementasi: empat pola struktural yang paling sering muncul di kode produksi—Adapter, Decorator, Proxy, dan Composite—beserta jebakan desain yang sering terjadi kalau dipakai tanpa pertimbangan trade-off.

Keempatnya sering disalahpahami sebagai "cara membungkus objek lain", padahal masing-masing punya niat (intent) yang berbeda. Kesalahan paling umum di kode production adalah memakai Decorator padahal yang dibutuhkan Proxy, atau membuat Adapter yang justru menambah logic bisnis — padahal tugasnya murni translasi interface.

1. Adapter: Translasi Interface, Bukan Tempat Logic

Adapter dipakai saat port domain (sesuai hexagonal architecture) tidak cocok secara langsung dengan SDK atau API eksternal. Prinsip ketat: Adapter tidak boleh mengandung business rule, hanya transformasi data dan pemetaan exception.

interface PaymentGateway {
    public function charge(Money $amount, string $token): PaymentResult;
}

final class StripeAdapter implements PaymentGateway
{
    public function __construct(private StripeClient $client) {}

    public function charge(Money $amount, string $token): PaymentResult
    {
        try {
            $response = $this->client->charges->create([
                'amount'   => $amount->toCents(),
                'currency' => $amount->currency(),
                'source'   => $token,
            ]);
        } catch (StripeApiException $e) {
            // translasi exception vendor ke domain exception
            throw PaymentFailedException::fromVendor($e);
        }

        return PaymentResult::fromStripeResponse($response);
    }
}

Jebakan produksi: tim sering menaruh validasi bisnis (misal cek limit transaksi harian) di dalam Adapter karena "sudah ada di situ". Ini melanggar single responsibility — Adapter jadi tahu aturan domain, sehingga ganti vendor pembayaran berarti harus menulis ulang validasi di setiap adapter baru. Validasi semacam itu seharusnya ada di use case / domain service, bukan di adapter.

Adapter vs Facade

Keduanya sering tertukar. Facade menyederhanakan subsistem kompleks dengan interface baru yang lebih mudah dipakai, tapi tidak wajib menyesuaikan ke interface target tertentu. Adapter punya kontrak spesifik yang harus dipenuhi (biasanya port yang sudah didefinisikan domain). Kalau Anda membungkus beberapa service jadi satu pintu masuk tanpa kontrak formal, itu Facade, bukan Adapter — penamaan yang salah akan membingungkan tim saat code review.

2. Decorator: Menambah Tanggung Jawab Secara Transparan

Decorator dipakai ketika Anda ingin menambah behavior (logging, caching, retry, rate limiting) tanpa mengubah kelas asli dan tanpa membuat eksplosi subclass untuk tiap kombinasi fitur. Kuncinya: Decorator mengimplementasikan interface yang sama dengan objek yang dibungkus, dan bisa ditumpuk (stacked).

interface ProductRepository {
    public function find(int $id): ?Product;
}

final class CachingProductRepository implements ProductRepository
{
    public function __construct(
        private ProductRepository $inner,
        private CacheInterface $cache,
    ) {}

    public function find(int $id): ?Product
    {
        $key = "product:{$id}";
        if ($cached = $this->cache->get($key)) {
            return $cached;
        }

        $product = $this->inner->find($id);
        if ($product !== null) {
            $this->cache->set($key, $product, ttl: 300);
        }

        return $product;
    }
}

final class LoggingProductRepository implements ProductRepository
{
    public function __construct(
        private ProductRepository $inner,
        private LoggerInterface $logger,
    ) {}

    public function find(int $id): ?Product
    {
        $this->logger->debug("Fetching product {$id}");
        return $this->inner->find($id);
    }
}

Komposisi di container DI (akan dibahas lebih dalam di modul 4):

$repo = new LoggingProductRepository(
    new CachingProductRepository(
        new SqlProductRepository($pdo),
        $cache
    ),
    $logger
);

Urutan stacking penting dan sering jadi bug tersembunyi: kalau LoggingProductRepository dipasang di dalam CachingProductRepository, log hanya tercatat saat cache miss — padahal mungkin Anda butuh log setiap request masuk. Diskusikan urutan ini secara eksplisit di code review, jangan asumsikan "pasti benar" karena compiler tidak akan menangkap kesalahan urutan ini.

Decorator vs Middleware

Middleware (PSR-15) sebenarnya penerapan Decorator pattern pada level request/response HTTP. Memahami Decorator secara eksplisit membantu Anda menulis middleware custom dengan lebih percaya diri, termasuk menentukan kapan middleware harus short-circuit (tidak memanggil $next) — analog dengan Decorator yang memilih tidak memanggil inner.

3. Proxy: Kontrol Akses, Bukan Penambahan Fitur

Proxy terlihat mirip Decorator secara struktur kode, tapi niatnya berbeda: Proxy mengontrol akses ke objek asli — lazy loading, access control, atau representasi objek remote — tanpa mengubah perilaku fungsional objek tersebut.

interface ReportGenerator {
    public function generate(int $reportId): Report;
}

final class LazyReportGeneratorProxy implements ReportGenerator
{
    private ?HeavyReportGenerator $realGenerator = null;

    public function __construct(private ReportGeneratorFactory $factory) {}

    public function generate(int $reportId): Report
    {
        // objek berat hanya dibuat saat benar-benar dibutuhkan
        if ($this->realGenerator === null) {
            $this->realGenerator = $this->factory->createHeavyGenerator();
        }

        return $this->realGenerator->generate($reportId);
    }
}

Contoh lain: Proxy untuk access control berbasis role.

final class AuthorizedReportGenerator implements ReportGenerator
{
    public function __construct(
        private ReportGenerator $inner,
        private AuthContext $auth,
    ) {}

    public function generate(int $reportId): Report
    {
        if (!$this->auth->can('generate_report')) {
            throw new AccessDeniedException();
        }
        return $this->inner->generate($reportId);
    }
}

Pembeda praktis Decorator vs Proxy: Decorator menambah behavior baru yang memang bagian dari fitur (caching adalah fitur), Proxy mengontrol apakah dan bagaimana request sampai ke objek asli tanpa menambah fitur baru pada hasil akhirnya. Secara teknis kode bisa identik, tapi niat desain ini menentukan bagaimana Anda menamai kelas dan menjelaskannya ke tim — penamaan yang tepat mengurangi miskomunikasi saat onboarding developer baru.

4. Composite: Hierarki Objek yang Diperlakukan Seragam

Composite dipakai ketika domain Anda punya struktur pohon (tree) dan klien harus bisa memperlakukan node tunggal maupun grup node dengan interface yang sama. Contoh klasik produksi: sistem diskon bertingkat, struktur organisasi, atau validasi komposit.

interface DiscountRule {
    public function apply(Money $price): Money;
}

final class PercentageDiscount implements DiscountRule
{
    public function __construct(private float $percentage) {}

    public function apply(Money $price): Money
    {
        return $price->subtractPercentage($this->percentage);
    }
}

final class CompositeDiscount implements DiscountRule
{
    /** @var DiscountRule[] */
    private array $rules = [];

    public function add(DiscountRule $rule): void
    {
        $this->rules[] = $rule;
    }

    public function apply(Money $price): Money
    {
        foreach ($this->rules as $rule) {
            $price = $rule->apply($price);
        }
        return $price;
    }
}

Penggunaan:

$discount = new CompositeDiscount();
$discount->add(new PercentageDiscount(10));
$discount->add(new FlatAmountDiscount(Money::fromRupiah(5000)));

$finalPrice = $discount->apply($originalPrice);

Trade-off yang sering diabaikan: urutan penerapan diskon memengaruhi hasil akhir (diskon persentase lalu potongan flat beda hasilnya dengan urutan sebaliknya). Composite pattern tidak menyelesaikan masalah ini secara otomatis — Anda tetap butuh aturan bisnis eksplisit soal urutan rule, dan sebaiknya urutan ini dites dengan unit test berbasis data provider (dibahas detail di modul 7), bukan diasumsikan dari urutan `add()`.

Kombinasi Pattern dalam Satu Alur

Di produksi, keempat pattern ini jarang berdiri sendiri. Satu request bisa melewati: Proxy (cek otorisasi) → Decorator (logging) → Decorator (caching) → Adapter (ke API eksternal), dengan hasil akhirnya diproses oleh Composite (gabungan beberapa aturan bisnis). Memahami niat masing-masing pattern membuat Anda bisa menyusun layer ini tanpa membuat satu kelas "dewa" yang melakukan semuanya sekaligus — yang justru melanggar prinsip yang sudah dibahas di modul SOLID.

Studi Kasus: Sistem Integrasi Multi-Payment Gateway dengan Fallback dan Observabilitas

Konteks: Sebuah platform e-commerce skala menengah-besar memproses ribuan transaksi per menit melalui tiga payment gateway berbeda (Midtrans, Xendit, dan provider bank lokal) karena alasan redundansi dan biaya transaksi. Masalah yang dihadapi tim engineering:

• Kode awal menaruh logic retry, logging, dan validasi fraud langsung di dalam masing-masing class gateway — menyebabkan duplikasi di tiga tempat dan sulit diaudit saat terjadi insiden.
• Saat gateway utama down, sistem harus otomatis fallback ke gateway kedua tanpa mengubah kode di use case pemrosesan order.
• Tim compliance butuh audit trail lengkap (siapa yang akses, kapan, request/response apa) tanpa mengotori logic bisnis pembayaran.

Solusi yang dipilih:

interface PaymentGateway {
    public function charge(Money $amount, string $token): PaymentResult;
}

// 1. Adapter murni per vendor — hanya translasi
final class MidtransAdapter implements PaymentGateway { /* ... */ }
final class XenditAdapter implements PaymentGateway { /* ... */ }

// 2. Decorator untuk audit logging — ditempel ke semua gateway seragam
final class AuditLoggingGateway implements PaymentGateway
{
    public function __construct(
        private PaymentGateway $inner,
        private AuditLogger $audit,
    ) {}

    public function charge(Money $amount, string $token): PaymentResult
    {
        $this->audit->logRequest($amount, $token);
        try {
            $result = $this->inner->charge($amount, $token);
            $this->audit->logResponse($result);
            return $result;
        } catch (PaymentFailedException $e) {
            $this->audit->logFailure($e);
            throw $e;
        }
    }
}

// 3. Proxy untuk fallback otomatis — mengontrol akses ke gateway berikutnya
final class FallbackPaymentGateway implements PaymentGateway
{
    /** @var PaymentGateway[] */
    private array $gateways;

    public function __construct(PaymentGateway ...$gateways)
    {
        $this->gateways = $gateways;
    }

    public function charge(Money $amount, string $token): PaymentResult
    {
        $lastException = null;
        foreach ($this->gateways as $gateway) {
            try {
                return $gateway->charge($amount, $token);
            } catch (PaymentFailedException $e) {
                $lastException = $e;
                continue; // coba gateway berikutnya
            }
        }
        throw $lastException ?? new PaymentFailedException('Semua gateway gagal');
    }
}

// Komposisi akhir
$gateway = new FallbackPaymentGateway(
    new AuditLoggingGateway(new MidtransAdapter($midtransClient), $audit),
    new AuditLoggingGateway(new XenditAdapter($xenditClient), $audit),
);

Kenapa kombinasi ini, bukan yang lain:

• Adapter dipilih murni untuk isolasi SDK vendor — tanpa ini, ganti SDK Midtrans versi baru akan memaksa perubahan di banyak tempat termasuk logic fallback dan audit.
• Audit logging dibuat Decorator, bukan ditulis manual di tiap adapter, karena requirement compliance berubah-ubah (misalnya suatu saat harus menambah hashing data sensitif di log). Dengan Decorator, perubahan ini satu tempat, otomatis berlaku untuk semua gateway tanpa menyentuh Adapter.
• Fallback dipilih sebagai Proxy, bukan Decorator, karena perannya murni mengontrol ke mana request diarahkan — tidak menambah fitur baru pada hasil transaksi. Ini juga alasan kenapa penamaan class FallbackPaymentGateway tetap valid secara konsep meski secara struktur kode mirip Decorator: niatnya kontrol alur, bukan penambahan behavior.
• Alternatif yang ditolak: tim sempat mempertimbangkan membuat satu PaymentManager besar yang menangani retry, logging, dan pemilihan gateway sekaligus. Ditolak karena class tersebut akan punya terlalu banyak alasan untuk berubah (melanggar SRP), sulit ditest secara terisolasi (setiap unit test harus mock tiga gateway sekaligus), dan tidak bisa dikonfigurasi ulang urutan gateway tanpa redeploy kode inti.

Dampak terukur: waktu investigasi insiden turun signifikan karena audit trail konsisten di semua gateway dari satu titik implementasi. Penambahan gateway keempat (provider bank baru) hanya butuh satu Adapter baru plus satu baris komposisi, tanpa menyentuh logic fallback atau audit yang sudah stabil dan sudah diuji — keuntungan langsung dari pemisahan niat pattern yang jelas sejak awal desain.