Dalam pengembangan aplikasi skala enterprise, arsitektur tiga lapis tradisional (Controller - Service - Repository) sering kali mengalami degradasi struktural seiring bertambahnya kompleksitas fitur. Service class berubah menjadi "god class" berisi ribuan baris kode campuran antara validasi HTTP, query SQL, dan logika bisnis. Entitas database hanya berupa kantong data pasif tanpa aturan validasi (Anemic Domain Model), sementara perubahan library atau database memaksa penulisan ulang seluruh logika sistem.
Untuk menjaga agar logika bisnis inti tetap murni, tahan lama, dan mudah diuji, arsitektur perangkat lunak modern menggabungkan prinsip Domain-Driven Design (DDD) dengan pola Hexagonal Architecture (dikenal juga sebagai Ports and Adapters).
Struktur Hexagonal Architecture (Ports and Adapters):
┌────────────────────────────────────────────────────────┐
│ Inbound / Driving Adapters (REST API, GraphQL, CLI) │
│ │ │
│ ▼ Memanggil melalui │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Inbound Ports (Use Case Interfaces) │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ Domain Core (Murni TypeScript Tanpa Framework) │ │ │
│ │ │ - Entities & Value Objects │ │ │
│ │ │ - Aggregate Roots │ │ │
│ │ │ - Domain Events & Invariants │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ Menggunakan definisi │ │
│ │ Outbound Ports (Repository / Gateway Interfaces) │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ Diimplementasikan oleh │
│ Outbound / Driven Adapters (PostgreSQL, Redis, Kafka) │
└────────────────────────────────────────────────────────┘
Prinsip Dependency Inversion: Inti Domain yang Terisolasi #
Aturan emas dalam Hexagonal Architecture adalah: Arah dependensi selalu mengarah ke dalam.
- Modul Domain Core tidak boleh mengimpor library luar apa pun, tidak ada decorator database (seperti TypeORM
@Entityatau Prisma), dan tidak ada kode HTTP framework (seperti Express atau NestJS). - Database dan antarmuka web dianggap sebagai detail teknis di lapisan luar. Jika database diganti dari PostgreSQL ke MongoDB, kode logika bisnis di dalam Domain Core tidak boleh berubah satu baris pun.
Mengimplementasikan Elemen Taktis DDD #
1. Value Object: Menjamin Immutability dan Validasi Bawaan #
Value Object adalah objek yang diidentifikasi oleh nilainya, bukan oleh ID unik. Value Object bersifat abadi (immutable) dan selalu valid sejak pertama kali dibuat.
// domain/value-objects/Money.ts
export class Money {
private readonly amount: number;
private readonly currency: string;
private constructor(amount: number, currency: string) {
if (amount < 0) {
throw new Error('Nominal uang tidak boleh bernilai negatif.');
}
this.amount = Math.round(amount * 100) / 100;
this.currency = currency.toUpperCase();
}
public static create(amount: number, currency = 'IDR'): Money {
return new Money(amount, currency);
}
public add(other: Money): Money {
if (this.currency !== other.currency) {
throw new Error(`Tidak dapat menjumlahkan mata uang berbeda: ${this.currency} dan ${other.currency}`);
}
return new Money(this.amount + other.amount, this.currency);
}
public getAmount(): number {
return this.amount;
}
public getCurrency(): string {
return this.currency;
}
public equals(other: Money): boolean {
return this.amount === other.amount && this.currency === other.currency;
}
}
2. Aggregate Root: Penjaga Batas Invarian Bisnis #
Aggregate Root adalah entitas utama yang mengontrol akses ke entitas-entitas di dalamnya, memastikan seluruh aturan konsistensi bisnis (invariants) selalu terpenuhi sebelum status disimpan.
// domain/aggregates/Order.ts
import { Money } from '../value-objects/Money';
export type OrderStatus = 'DRAFT' | 'CONFIRMED' | 'PAID' | 'CANCELLED';
export interface OrderItem {
productId: string;
unitPrice: Money;
quantity: number;
}
export class Order {
private readonly id: string;
private readonly customerId: string;
private items: OrderItem[] = [];
private status: OrderStatus = 'DRAFT';
private domainEvents: any[] = [];
constructor(id: string, customerId: string) {
this.id = id;
this.customerId = customerId;
}
public addItem(productId: string, unitPrice: Money, quantity: number): void {
if (this.status !== 'DRAFT') {
throw new Error('Tidak dapat mengubah item pada pesanan yang sudah difinalisasi.');
}
if (quantity <= 0) {
throw new Error('Kuantitas produk wajib lebih besar dari nol.');
}
this.items.push({ productId, unitPrice, quantity });
}
public calculateTotal(): Money {
return this.items.reduce(
(total, item) => total.add(Money.create(item.unitPrice.getAmount() * item.quantity)),
Money.create(0)
);
}
public confirm(): void {
if (this.items.length === 0) {
throw new Error('Pesanan kosong tidak dapat dikonfirmasi.');
}
this.status = 'CONFIRMED';
// Merekam Domain Event
this.domainEvents.push({
eventType: 'ORDER_CONFIRMED',
orderId: this.id,
totalAmount: this.calculateTotal().getAmount(),
occurredOn: new Date(),
});
}
public pullDomainEvents(): any[] {
const events = [...this.domainEvents];
this.domainEvents = [];
return events;
}
public getId(): string { return this.id; }
public getStatus(): OrderStatus { return this.status; }
}
Mendefinisikan Ports (Kontrak Antarmuka) #
Port adalah abstraksi murni berupa TypeScript interface yang menyatakan kebutuhan Domain Core terhadap lingkungan luar:
// domain/ports/OrderRepositoryPort.ts
import { Order } from '../aggregates/Order';
export interface OrderRepositoryPort {
save(order: Order): Promise<void>;
findById(id: string): Promise<Order | null>;
}
// domain/ports/NotificationGatewayPort.ts
export interface NotificationGatewayPort {
sendOrderConfirmationEmail(toEmail: string, orderId: string): Promise<void>;
}
Membangun Adapters: Menghubungkan Infrastruktur Riil #
Adapter adalah implementasi konkret dari Port yang berkomunikasi dengan teknologi spesifik di luar:
// infrastructure/adapters/PostgresOrderRepositoryAdapter.ts
import { OrderRepositoryPort } from '../../domain/ports/OrderRepositoryPort';
import { Order } from '../../domain/aggregates/Order';
import { Pool } from 'pg';
export class PostgresOrderRepositoryAdapter implements OrderRepositoryPort {
constructor(private readonly dbPool: Pool) {}
async save(order: Order): Promise<void> {
const client = await this.dbPool.connect();
try {
await client.query(
`INSERT INTO orders (id, status, total_amount)
VALUES ($1, $2, $3)
ON CONFLICT (id) DO UPDATE
SET status = EXCLUDED.status, updated_at = NOW()`,
[order.getId(), order.getStatus(), order.calculateTotal().getAmount()]
);
} finally {
client.release();
}
}
async findById(id: string): Promise<Order | null> {
// Mapping dari relasional database kembali ke objek Domain Order
return null;
}
}
Keuntungan dalam Pengujian Otomatis #
Manfaat terbesar dari arsitektur heksagonal adalah kemudahan pengujian unit (unit testing). Karena domain terisolasi murni dari database dan jaringan:
// tests/domain/Order.spec.ts
import { Order } from '../../domain/aggregates/Order';
import { Money } from '../../domain/value-objects/Money';
describe('Order Aggregate Root', () => {
it('harus menolak konfirmasi jika pesanan tidak memiliki item', () => {
const order = new Order('ord-1', 'cust-99');
expect(() => order.confirm()).toThrow('Pesanan kosong tidak dapat dikonfirmasi.');
});
it('harus menghitung total harga dengan benar dan menerbitkan event', () => {
const order = new Order('ord-1', 'cust-99');
order.addItem('prod-A', Money.create(50000), 2);
order.addItem('prod-B', Money.create(25000), 1);
expect(order.calculateTotal().getAmount()).toBe(125000);
order.confirm();
const events = order.pullDomainEvents();
expect(events).toHaveLength(1);
expect(events[0].eventType).toBe('ORDER_CONFIRMED');
});
});
Uji coba di atas berjalan dalam hitungan milidetik tanpa perlu menyalakan Docker database, mock server HTTP, atau ketergantungan eksternal apa pun. Arsitektur ini menjamin kode sistem enterprise tetap kokoh, mudah dirawat, dan terbebas dari jebakan keterikatan vendor (vendor lock-in).
