yolando/example-soa-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
yolando
2026-03-02 02:46:39 +00:00
parent e468ff18c0
commit 4581b4b547
1 changed files with 32 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
README.md
View File

@@ -1,69 +1,61 @@
# 🚀 Dynamic SOA Mapper (Configuration-Driven Payload Engine) # 🚀 Dynamic SOA Mapper (Configuration-Driven Payload Engine)
## 📖 Apa itu Dynamic SOA Mapper? ## 📖 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**. **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**. 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)**.
Jika ada perubahan format dari SOA, tim operasional cukup mengubah data di tabel konfigurasi tanpa perlu melakukan kompilasi kode atau *deployment* ulang (*Zero Downtime*).
--- ---
## ✨ Fitur Utama ## ✨ 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. 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. **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. 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. **High Performance (SpEL Caching):** Aturan SpEL di-*parse* dan disimpan dalam *ConcurrentHashMap In-Memory Cache*. Eksekusi *mapping* berjalan dalam hitungan mikrosekon (O(1)). 3. **Auto Nested-JSON (Dot Notation):** Cukup gunakan titik pada konfigurasi (contoh: `header.message.id`), *engine* otomatis merakit struktur JSON bertingkat.
4. **Resilient & Fail-Safe:** Dilengkapi dengan fitur *Safe Navigation* (mencegah *NullPointerException*), kolom *Default Value* (*fallback* jika data kosong), dan validasi *Mandatory Field*. 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 ## 🏗️ Arsitektur & Cara Kerja
Saat *endpoint* API dipanggil dengan membawa `transactionId` dan `kotran`: Saat *endpoint* API dipanggil (misal: Kotran `1001`):
1. **Data Aggregation:** Sistem menarik data sumber (`Transaction` dan `Payment`) dari database dan membungkusnya ke dalam `StandardEvaluationContext`. 1. **Data Aggregation:** Sistem menarik data (`Transaction`, `Payment`) dan menyimpannya ke `StandardEvaluationContext`.
2. **Fetch Configuration:** Sistem mengambil daftar aturan *mapping* khusus untuk `kotran` tersebut dari tabel `SOA_MAPPING_CONFIG`. 2. **Fetch & Merge Configuration:** Sistem mengambil aturan `GLOBAL` dan aturan spesifik `1001` dari tabel `SOA_MAPPING_CONFIG`, lalu menggabungkannya.
3. **SpEL Evaluation:** *Engine* melakukan iterasi pada setiap aturan, mengeksekusi `expression_rule` terhadap *Context* data sumber. 3. **SpEL Evaluation:** *Engine* 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. 4. **JSON Assembly:** Hasil diekstrak menjadi *Map* dan *List* (termasuk *nested*), lalu dikembalikan sebagai JSON utuh.
--- ---
## 💻 Panduan Penggunaan & Konfigurasi ## 💻 Panduan Penggunaan & Konfigurasi
### 1. Struktur Tabel Konfigurasi (`SOA_MAPPING_CONFIG`) ### 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 | | Kolom | Penjelasan | Contoh Pengisian |
| :--- | :--- | :--- | | :--- | :--- | :--- |
| `KOTRAN` | Kode transaksi sebagai pengelompokan *rules*. | `1001`, `1002`, `POS_PAYMENT` | | `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*. | `TLBF01` atau `header.msgId` | | `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` | | `TARGET_FIELD_TYPE` | Tipe data target (saat ini sebagai referensi dokumentasi). | `String`, `Number`, `List` |
| `EXPRESSION_RULE` | **Aturan SpEL** untuk mengambil/mengubah data dari objek sumber. | `#transaction.amount * 100` | | `EXPRESSION_RULE` | **Aturan SpEL** untuk mengambil/mengubah data. | `#transaction.amount * 100` |
| `DEFAULT_VALUE` | Nilai *fallback* jika hasil evaluasi *rule* menghasilkan `null`. | `0`, `NO_DATA` | | `DEFAULT_VALUE` | Nilai *fallback* jika hasil evaluasi *rule* bernilai `null`. | `0`, `NO_DATA` |
| `IS_MANDATORY` | `1` (Wajib). Jika evaluasi dan default *null*, sistem akan *error*. `0` (Opsional). | `1`, `0` | | `IS_MANDATORY` | `1` (Wajib). Jika evaluasi dan default *null*, sistem akan *throw Error*. | `1`, `0` |
### 2. Cheatsheet Penulisan Expression Rule (SpEL) ### 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` * **Mapping Langsung:** `#payment.debitAccountNo`
* **Hardcode Value:** `'PT BUMI MAKMUR'` *(Gunakan kutip satu)* * **Hardcode Value:** `'PT BUMI MAKMUR'` *(Gunakan kutip satu)*
* **Operasi Matematika:** `#transaction.amount * 15000` * **Matematika & Logika:** `#transaction.amount * 15000`
* **Konkatenasi String:** `'REF-' + #transaction.id`
* **Format Tanggal:** `new java.text.SimpleDateFormat('yyyyMMdd').format(#transaction.effectiveDate)` * **Format Tanggal:** `new java.text.SimpleDateFormat('yyyyMMdd').format(#transaction.effectiveDate)`
* **Ternary Operator (If-Else):** `#transaction.status == 'SUCCESS' ? '00' : '99'` * **Ternary (If-Else):** `#transaction.status == 'SUCCESS' ? '00' : '99'`
* **Safe Navigation (Anti-NPE):** `#transaction?.promoCode` *(Gunakan `?.` jika curiga field tersebut bisa null)* * **Safe Navigation (Anti-NPE):** `#transaction?.promoCode`
--- ### 3. Panduan Membuat JSON Array (Array of Objects)
Jika SOA meminta format JSON Array seperti ini:
## 🚀 Cara Menjalankan Aplikasi Lokal ```json
"property": [
### Prasyarat: { "key": "teller", "value": "811" },
* Java 17 atau lebih baru { "key": "trxId", "value": "TRX-123" }
* 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