From 4581b4b5477f0e17f01ab25d3cf6f3b5eaf99978 Mon Sep 17 00:00:00 2001 From: yolando Date: Mon, 2 Mar 2026 02:46:39 +0000 Subject: [PATCH] Update README.md --- README.md | 72 +++++++++++++++++++++++++------------------------------ 1 file changed, 32 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index f3f5e1d..41b4b85 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,61 @@ # 🚀 Dynamic SOA Mapper (Configuration-Driven Payload Engine) ## 📖 Apa itu Dynamic SOA Mapper? -Dalam sistem integrasi perbankan/Enterprise, memetakan data internal ke format JSON yang diminta oleh *Service Oriented Architecture* (SOA) seringkali memakan waktu. Jika ada 100+ jenis transaksi (Kotran) dan setiap Kotran memiliki 30-40 field, melakukan *hardcode* menggunakan `if-else` di Java akan menghasilkan *spaghetti code* yang sulit di-*maintain*. +Dalam sistem integrasi perbankan/Enterprise, memetakan data internal ke format JSON yang diminta oleh *Service Oriented Architecture* (SOA) seringkali memakan waktu. Jika ada 120+ jenis transaksi (Kotran), dan setiap Kotran memiliki puluhan field hingga struktur *Array*, melakukan *hardcode* di Java akan menghasilkan *spaghetti code* yang sulit di-*maintain*. -**Dynamic SOA Mapper** memecahkan masalah ini dengan pendekatan **Metadata-Driven Architecture**. -Alih-alih menulis aturan *mapping* di dalam kode Java, seluruh aturan transformasi, operasi matematika, hingga pembentukan JSON berjenjang (*nested JSON*) **disimpan di dalam tabel Database**. - -Jika ada perubahan format dari SOA, tim operasional cukup mengubah data di tabel konfigurasi tanpa perlu melakukan kompilasi kode atau *deployment* ulang (*Zero Downtime*). +**Dynamic SOA Mapper** memecahkan masalah ini dengan pendekatan **Metadata-Driven Architecture**. +Seluruh aturan transformasi, operasi matematika, pembentukan JSON berjenjang (*nested*), hingga pembuatan **JSON Array** diserahkan 100% kepada konfigurasi di tabel Database menggunakan **Spring Expression Language (SpEL)**. --- ## ✨ Fitur Utama -1. **100% Dynamic Rules:** Menggunakan **Spring Expression Language (SpEL)** untuk memanipulasi data (*string concatenation*, matematika, *ternary operator*, format tanggal) langsung dari teks di database. -2. **Auto Nested-JSON (Dot Notation):** Mendukung pembuatan JSON bertingkat tanpa mengubah struktur tabel. Cukup gunakan notasi titik pada konfigurasi (contoh: `header.message.id`), *engine* akan otomatis merakit objek JSON-nya. -3. **High Performance (SpEL Caching):** Aturan SpEL di-*parse* dan disimpan dalam *ConcurrentHashMap In-Memory Cache*. Eksekusi *mapping* berjalan dalam hitungan mikrosekon (O(1)). -4. **Resilient & Fail-Safe:** Dilengkapi dengan fitur *Safe Navigation* (mencegah *NullPointerException*), kolom *Default Value* (*fallback* jika data kosong), dan validasi *Mandatory Field*. +1. **100% Dynamic Rules:** Menggunakan **SpEL** untuk manipulasi data (*string concatenation*, matematika, *ternary operator*, format tanggal) langsung dari teks di database tanpa *deploy* ulang (*Zero Downtime*). +2. **Global Configuration:** Mendukung Kotran `GLOBAL` untuk mendefinisikan *Header* atau *field* statis yang otomatis digabungkan (*merged*) ke seluruh request Kotran lainnya. Sangat *DRY (Don't Repeat Yourself)*! +3. **Auto Nested-JSON (Dot Notation):** Cukup gunakan titik pada konfigurasi (contoh: `header.message.id`), *engine* otomatis merakit struktur JSON bertingkat. +4. **JSON Array Support:** Mendukung pembuatan *Array of Objects* (List of Maps) secara dinamis hanya dari satu baris konfigurasi teks. +5. **High Performance:** Aturan SpEL di-*parse* dan di-*cache* (*ConcurrentHashMap*). Eksekusi *mapping* berjalan dalam hitungan mikrosekon (O(1)). +6. **Resilient & Fail-Safe:** Dilengkapi dengan fitur *Safe Navigation* (mencegah NPE), *Default Value* (*fallback*), dan validasi *Mandatory Field*. --- ## 🏗️ Arsitektur & Cara Kerja -Saat *endpoint* API dipanggil dengan membawa `transactionId` dan `kotran`: -1. **Data Aggregation:** Sistem menarik data sumber (`Transaction` dan `Payment`) dari database dan membungkusnya ke dalam `StandardEvaluationContext`. -2. **Fetch Configuration:** Sistem mengambil daftar aturan *mapping* khusus untuk `kotran` tersebut dari tabel `SOA_MAPPING_CONFIG`. -3. **SpEL Evaluation:** *Engine* melakukan iterasi pada setiap aturan, mengeksekusi `expression_rule` terhadap *Context* data sumber. -4. **JSON Assembly:** Hasil evaluasi dirakit menjadi *Map* (mendukung *nested* berkat notasi titik) dan dikembalikan sebagai representasi JSON siap kirim. +Saat *endpoint* API dipanggil (misal: Kotran `1001`): +1. **Data Aggregation:** Sistem menarik data (`Transaction`, `Payment`) dan menyimpannya ke `StandardEvaluationContext`. +2. **Fetch & Merge Configuration:** Sistem mengambil aturan `GLOBAL` dan aturan spesifik `1001` dari tabel `SOA_MAPPING_CONFIG`, lalu menggabungkannya. +3. **SpEL Evaluation:** *Engine* mengeksekusi `expression_rule` terhadap *Context* data sumber. +4. **JSON Assembly:** Hasil diekstrak menjadi *Map* dan *List* (termasuk *nested*), lalu dikembalikan sebagai JSON utuh. --- ## 💻 Panduan Penggunaan & Konfigurasi ### 1. Struktur Tabel Konfigurasi (`SOA_MAPPING_CONFIG`) -Ini adalah jantung dari *project* ini. Memahami cara mengisi tabel ini berarti menguasai seluruh *mapping*. +Ini adalah jantung dari *mapping engine* ini. | Kolom | Penjelasan | Contoh Pengisian | | :--- | :--- | :--- | -| `KOTRAN` | Kode transaksi sebagai pengelompokan *rules*. | `1001`, `1002`, `POS_PAYMENT` | -| `TARGET_FIELD_NM` | Nama *key* JSON tujuan. Gunakan titik (`.`) untuk *nested object*. | `TLBF01` atau `header.msgId` | -| `TARGET_FIELD_TYPE` | Tipe data target (saat ini sebagai referensi dokumentasi). | `String`, `Number` | -| `EXPRESSION_RULE` | **Aturan SpEL** untuk mengambil/mengubah data dari objek sumber. | `#transaction.amount * 100` | -| `DEFAULT_VALUE` | Nilai *fallback* jika hasil evaluasi *rule* menghasilkan `null`. | `0`, `NO_DATA` | -| `IS_MANDATORY` | `1` (Wajib). Jika evaluasi dan default *null*, sistem akan *error*. `0` (Opsional). | `1`, `0` | +| `KOTRAN` | Kode transaksi. Gunakan `GLOBAL` untuk rule yang berlaku di semua Kotran. | `GLOBAL`, `1001`, `1304` | +| `TARGET_FIELD_NM` | Nama *key* JSON tujuan. Gunakan titik (`.`) untuk *nested object*. | `messageHeader.tellerId` | +| `TARGET_FIELD_TYPE` | Tipe data target (saat ini sebagai referensi dokumentasi). | `String`, `Number`, `List` | +| `EXPRESSION_RULE` | **Aturan SpEL** untuk mengambil/mengubah data. | `#transaction.amount * 100` | +| `DEFAULT_VALUE` | Nilai *fallback* jika hasil evaluasi *rule* bernilai `null`. | `0`, `NO_DATA` | +| `IS_MANDATORY` | `1` (Wajib). Jika evaluasi dan default *null*, sistem akan *throw Error*. | `1`, `0` | ### 2. Cheatsheet Penulisan Expression Rule (SpEL) -Dalam *project* ini, objek yang didaftarkan ke dalam *Context* adalah `#transaction` dan `#payment`. +Objek yang tersedia di dalam *Context* saat ini adalah: `#transaction` dan `#payment`. * **Mapping Langsung:** `#payment.debitAccountNo` * **Hardcode Value:** `'PT BUMI MAKMUR'` *(Gunakan kutip satu)* -* **Operasi Matematika:** `#transaction.amount * 15000` -* **Konkatenasi String:** `'REF-' + #transaction.id` +* **Matematika & Logika:** `#transaction.amount * 15000` * **Format Tanggal:** `new java.text.SimpleDateFormat('yyyyMMdd').format(#transaction.effectiveDate)` -* **Ternary Operator (If-Else):** `#transaction.status == 'SUCCESS' ? '00' : '99'` -* **Safe Navigation (Anti-NPE):** `#transaction?.promoCode` *(Gunakan `?.` jika curiga field tersebut bisa null)* +* **Ternary (If-Else):** `#transaction.status == 'SUCCESS' ? '00' : '99'` +* **Safe Navigation (Anti-NPE):** `#transaction?.promoCode` ---- - -## 🚀 Cara Menjalankan Aplikasi Lokal - -### Prasyarat: -* Java 17 atau lebih baru -* Maven 3.x -* Database Oracle (atau ubah URL di `application.yaml` jika menggunakan database lain) - -### Langkah-langkah: -1. Pastikan database Oracle menyala dan konfigurasi di `src/main/resources/application.yaml` sudah sesuai dengan *username* dan *password* lokalmu. -2. Jalankan perintah Maven: - ```bash - ./mvnw spring-boot:run \ No newline at end of file +### 3. Panduan Membuat JSON Array (Array of Objects) +Jika SOA meminta format JSON Array seperti ini: +```json +"property": [ + { "key": "teller", "value": "811" }, + { "key": "trxId", "value": "TRX-123" } +] \ No newline at end of file