Hexagonal Architecture (Ports and Adapters) #

Dalam pengembangan aplikasi modern, kompleksitas sistem terus meningkat: ada database, API eksternal, message broker, UI, dan berbagai teknologi lain yang silih berganti. Tantangan utamanya bukan hanya membuat fitur bekerja, tetapi menjaga agar core business logic tetap bersih, mudah diuji, dan tidak terikat pada teknologi tertentu.

Hexagonal Architecture—juga dikenal sebagai Ports and Adapters Architecture—hadir sebagai solusi untuk masalah tersebut. Arsitektur ini menekankan pemisahan yang tegas antara domain (logika bisnis) dan detail teknis (framework, database, UI, external service).

Untuk membantu visualisasi, berikut adalah bagan text-based dari Hexagonal Architecture:

                +-------------------+
                |   External World  |
                | (UI / API / CLI)  |
                +---------+---------+
                          |
                    [Inbound Adapter]
                          |
                  +-------v-------+
                  |   Inbound     |
                  |     Port      |
                  +-------+-------+
                          |
            +-------------v-------------+
            |      Application /        |
            |       Domain Core         |
            |  (Use Case & Business)    |
            +-------------+-------------+
                          |
                  +-------v-------+
                  |  Outbound     |
                  |    Port       |
                  +-------+-------+
                          |
                   [Outbound Adapter]
                          |
            +-------------v-------------+
            | External Services         |
            | (DB / Cache / API / MQ)  |
            +---------------------------+

Intinya: domain tidak tahu apa-apa tentang dunia luar. Justru dunia luar yang menyesuaikan diri dengan domain.

Apa itu Hexagonal Architecture? #

Hexagonal Architecture adalah pola arsitektur yang memusatkan aplikasi pada domain dan use case, sementara interaksi dengan dunia luar dilakukan melalui port (interface) dan adapter (implementasi).

• Port: kontrak (interface) yang didefinisikan oleh domain atau application layer
• Adapter: implementasi konkret dari port untuk teknologi tertentu (HTTP, database, message broker, dll)

Prinsip utama:

• Dependency mengarah ke dalam (inward)
• Domain tidak bergantung pada framework
• Framework adalah detail, bukan fondasi

Tujuan Architecture #

Tujuan utama Hexagonal Architecture antara lain:

1. Isolasi Business Logic Logika bisnis tidak tercemar oleh detail teknis seperti ORM, HTTP handler, atau SDK pihak ketiga.

2. Mudah Diuji (Testability) Domain dapat diuji tanpa database, tanpa HTTP server, dan tanpa dependency eksternal.

3. Fleksibilitas Teknologi Ganti database dari MySQL ke PostgreSQL? Atau REST ke gRPC? Core logic tetap sama.

4. Maintainability Jangka Panjang Struktur kode lebih tahan terhadap perubahan requirement dan teknologi.

Kapan Cocok Digunakan? #

Hexagonal Architecture sangat cocok digunakan ketika:

• Aplikasi memiliki business logic yang kompleks
• Sistem diproyeksikan berumur panjang
• Perlu integrasi dengan banyak external service
• Tim ingin high test coverage di level domain
• Framework sering berubah atau dieksperimenkan

Namun, kurang cocok jika:

• Aplikasi sangat sederhana (CRUD kecil)
• Time-to-market sangat ketat
• Tim belum familiar dengan konsep interface dan dependency inversion

Pros dan Cons #

✅ Pros #

1. Loose Coupling Tinggi Domain benar-benar terlepas dari detail teknis.

2. Test-Friendly Mock adapter dengan mudah tanpa hack framework.

3. Technology Agnostic Framework bisa diganti tanpa rewrite core logic.

4. Clean Boundary Arsitektur memaksa disiplin desain sejak awal.

❌ Cons #

1. Boilerplate Lebih Banyak Banyak interface dan struktur folder.

2. Learning Curve Tidak intuitif bagi developer junior.

3. Overkill untuk App Kecil Terlalu berat untuk aplikasi sederhana.

4. Disiplin Tim Sangat Dibutuhkan Tanpa konsistensi, arsitektur bisa runtuh.

Best Practice #

1. Domain Tidak Boleh Import Adapter Jika domain mulai mengimpor package HTTP, DB, atau framework—itu tanda pelanggaran.

2. Gunakan Interface sebagai Port Port selalu didefinisikan di sisi domain atau application layer.

3. Adapter Bersifat Tipis Adapter hanya bertugas menerjemahkan data, bukan menyimpan business logic.

4. Pisahkan Inbound dan Outbound Port

   • Inbound: Use case / service interface
   • Outbound: Repository, external API, publisher, dsb

5. Gunakan Dependency Injection Adapter di-inject ke application layer saat runtime.

6. Nama yang Jelas dan Konsisten Contoh:

   • UserRepository (port)
   • PostgresUserRepository (adapter)

Perbandingan dengan Arsitektur Lain #

• Layered Architecture: lebih sederhana, tapi domain sering bocor ke infrastructure
• Clean Architecture: konsep sangat mirip, Hexagonal lebih menekankan metafora port & adapter
• Onion Architecture: fokus pada dependency ring, mirip secara prinsip

Secara filosofi, ketiganya berada dalam keluarga DDD-friendly architecture.

Penutup #

Hexagonal Architecture bukan sekadar cara menyusun folder, melainkan cara berpikir tentang isolasi domain dan arah dependency. Ia mendorong developer untuk menempatkan business logic sebagai pusat semesta, sementara teknologi hanyalah alat yang bisa diganti.

Jika Anda membangun sistem yang kompleks, jangka panjang, dan kritis terhadap perubahan—Hexagonal Architecture adalah investasi desain yang sangat layak. Namun, seperti semua arsitektur, gunakan dengan bijak dan sesuai konteks, bukan karena tren.

Frameworks come and go, but business rules should stay.