Setiap Panggilan Jaringan Wajib Tunduk pada Aturan yang Sama#
Dalam aplikasi mobile produksi yang memproses ribuan transaksi harian mulai dari pembayaran tagihan bulanan, pengisian pulsa, tiket kereta api, bus antarkota, hingga kapal laut penumpang, komunikasi jaringan adalah perimeter yang paling rawan insiden. Jika setiap modul fitur membangun pemanggilan HTTP-nya sendiri-sendiri secara bebas, kekacauan teknis tidak akan terhindarkan:
Ada developer yang lupa menyisipkan token otorisasi Bearer; developer lain tidak menyertakan header bahasa aplikasi; developer berikutnya membungkus timeout koneksi dengan blok try-catch kosong; dan response error 502 Bad Gateway dari server tembus mentah tanpa penanganan, menyebabkan seluruh pohon widget antarmuka crash dan membeku menjadi layar putih kosong.
Ketika tim kami mengaudit basis kode warisan lama Holigo, kami mendapati duplikasi konfigurasi HTTP di puluhan berkas, aturan retry jaringan yang tidak seragam, hingga penyimpanan token otentikasi pengguna dalam bentuk teks polos (plain text). Sebagai bagian dari migrasi clean architecture, kami menetapkan aturan arsitektur yang tidak bisa ditawar:
Tidak ada modul fitur yang diizinkan memanggil library HTTP pihak ketiga secara langsung maupun menyimpan token sensitif ke penyimpanan tanpa enkripsi. Setiap byte data yang masuk dan keluar dari aplikasi wajib mengalir melalui lapisan Data Layer terpusat yang tangguh di dalam folder core.
Pada Part 5 ini, saya akan membedah bagaimana kami merancang klien Dio terpusat, menstandarisasi penanganan kegagalan dengan batas fungsional Either, serta memisahkan cache tampilan dari brankas kredensial terenkripsi berbasis hardware.
Feature Service
Data SourceService memanggil endpoint spesifik tanpa pusing memikirkan base URL, token, atau header.
Core Dio Interceptor
Security & HeadersOtomatis inject Bearer Token, App Version, Bahasa aktif, Timeout, dan Request Logger.
Network Transport
HTTPS TLSPengiriman request aman ke backend server dengan proteksi SSL pinning dan timeout terukur.
Functional Mapping
Either<Exception, T>Exception jaringan diubah ke AppException terstruktur; JSON di-parse ke Model sukses.
Satu wrapper jaringan terpusat memastikan seluruh request aplikasi mematuhi standar keamanan, logging, dan header yang seragam tanpa repetisi kode.
Satu Jalur Tol Terpadu di Atas Dio#
Alih-alih membiarkan service di setiap fitur membuat instance klien HTTP sendiri, lapisan core kami menyediakan satu wrapper DioClient yang kokoh dan didaftarkan sebagai singleton di get_it. Setiap request yang keluar secara otomatis melewati rangkaian interceptor yang teratur:
- Base URL dan Timeout yang Deterministik: Alamat server dasar diikat secara ketat ke environment aktif (
developatauproduction), dengan batas waktu koneksi (timeout) yang disiplin guna mencegah aplikasi hang ketika pengguna berada di sinyal 3G yang tidak stabil. - Injeksi Header Otomatis Sesuai Konteks: Interceptor secara otomatis menyuntikkan token
Bearersesi aktif pengguna jika sudah login, kode bahasa aktif (idatauen), versi semantik binary aplikasi yang terpasang, serta header standar JSON. - Pencatatan Log Jaringan Terstruktur: Pada build debug dan staging, perintah curl lengkap dan payload JSON diformat rapi untuk memudahkan inspeksi developer, namun otomatis dibersihkan pada build produksi demi melindungi kerahasiaan data pengguna.
- Interceptor Refresh Token Otomatis: Saat request menerima status 401 Unauthorized, interceptor menahan request yang mengantre, memicu pertukaran refresh token di latar belakang, memperbarui brankas aman, dan mengulang kembali (replay) request yang sempat gagal tanpa disadari oleh pengguna.
Karena seluruh mekanisme ini berjalan otomatis di pipeline core, developer fitur dapat memusatkan 100% energi mereka pada domain bisnisnya: menentukan endpoint, parameter query, serta mapping model data.
Arsitektur Penyimpanan: Cache Cepat vs Vault Terenkripsi Hardware#
Kelemahan keamanan klasik pada banyak aplikasi mobile adalah menyimpan kredensial login, identitas pengguna, dan kode PIN di berkas preferensi key-value teks biasa. Jika perangkat Android di-root atau cadangan iOS dibongkar, token yang tidak terenkripsi dapat diekstrak dengan sangat mudah.
Untuk menyeimbangkan standar keamanan perbankan dengan kecepatan render antarmuka yang tinggi, Holigo menerapkan Arsitektur Penyimpanan Ganda (Dual-Storage) yang tegas:
- 01Karakteristik: Penyimpanan key-value unencrypted yang sangat cepat untuk data preferensi tampilan.
- 02Data yang Disimpan: Pilihan tema (dark/light), kode bahasa aktif, onboarding flag, dan riwayat pencarian rute.
- 03Dampak Jika Terbaca: Nol risiko keamanan finansial bagi pengguna maupun platform.
- 01Karakteristik: Menggunakan iOS Keychain dan Android KeyStore dengan enkripsi hardware AES-256.
- 02Data yang Disimpan: JWT Access & Refresh Token, hash verifikasi PIN, biometric secrets, dan user session ID.
- 03Dampak Jika Bocor: Risiko pembajakan akun dan transaksi ilegal; wajib terlindungi enkripsi ketat.
Membedakan tempat simpan berdasarkan sensitivitas data memberikan performa baca kilat untuk preferensi tampilan tanpa mengorbankan keamanan data kredensial.
1. shared_preferences (Cache Tampilan Cepat)
Dikhususkan hanya untuk data konfigurasi UI yang tidak sensitif:
- Preferensi mode tampilan (gelap / terang)
- Pilihan kode bahasa antarmuka (
id/en) - Flag penyelesaian panduan onboarding
- Riwayat pencarian rute pelabuhan dan stasiun kereta terakhir
Karena data ini sama sekali tidak memiliki risiko finansial maupun privasi jika terbaca, menyimpannya dalam format key-value unencrypted memberikan performa baca kilat tanpa beban proses enkripsi kriptografi.
2. flutter_secure_storage (Vault Terenkripsi Hardware)
Wajib digunakan untuk seluruh data kredensial rahasia:
- JWT Access Token dan Refresh Token
- Hash verifikasi PIN transaksi pengguna
- Kunci otentikasi biometrik
- Fingerprint perangkat terenkripsi
Di balik layar, library ini mendelegasikan penyimpanan ke iOS Keychain dan Android KeyStore, menggunakan enkripsi hardware AES-256. Token rahasia tidak pernah menyentuh memori penyimpanan dalam bentuk teks polos.
Resiliensi Tahan Banting: Functional Either vs Try-Catch Berserakan#
Pada aplikasi lama kami, penanganan error adalah hal yang penuh ketidakpastian. Developer menyebarkan blok try-catch di sembarang tempat: di controller, di widget UI, hingga di dalam callback tombol. Jika ada SocketException atau kegagalan parsing format JSON yang lolos dari blok catch lokal, error itu tembus ke layar dan membuat tombol membeku atau menampilkan pesan crash yang membingungkan.
Guna menghapus kebocoran exception untuk selamanya, kami menerapkan pola functional result pada seluruh kontrak repository menggunakan Either<AppException, T>:
Semua metode repository mengembalikan tipe Either: sisi Kiri (Left) membawa AppException terstruktur, sisi Kanan (Right) membawa payload data sukses.
- ✕Exception Bocor ke Layar: SocketException atau DioError tembus mentah ke UI dan memicu layar putih.
- ✕Blok Catch Berulang: Tiap widget menulis parsing error sendiri dengan format pesan tidak seragam.
- ✓Penangkapan Terisolasi di Data: Semua kendala HTTP, parse JSON, dan timeout ditransformasi ke AppException.
- ✓State Bersih Berbasis Enum: BLoC state memantau status via enum (initial, loading, success, failure) yang rapi.
Functional result pattern mengubah error dari sesuatu yang 'meledak tak terduga' menjadi nilai data biasa yang wajib ditangani secara sadar di setiap layar.
- Data Layer Sebagai Perisai Pelindung: Lapisan Data menangkap seluruh exception Dio, kendala DNS, putus koneksi, dan kesalahan format JSON. Seluruh kendala tersebut ditransformasikan menjadi turunan
AppExceptionyang terstruktur (NetworkException,ServerException,AuthException,ValidationException). - Kontrak Pengembalian Nilai Deterministik: Metode repository dilarang melempar (throw) exception ke luar. Mereka mengembalikan instance
Either: sisi Kiri (Left) membawa objekAppException, sedangkan sisi Kanan (Right) membawa data model yang berhasil diparse. - State BLoC Berbasis Enum yang Bersih: BLoC memetakan hasil
Eitherke dalam pembaruan state yang terprediksi. Dengan memantau siklus hidup request lewat enumRequestStatus(initial,loading,success,failure), layar antarmuka cukup mengamati perubahan status tersebut dan merender banner error yang ramah pengguna tanpa memerlukan satu baris pun kode try-catch di UI.
Harga Nyata di Lapangan: Titik Risiko Tunggal dan Transparansi Pipeline#
Meskipun sentralisasi infrastruktur data berhasil mengeliminasi ratusan potensi bug edge-case, pendekatan ini membawa trade-off arsitektur yang menuntut kewaspadaan tinggi:
Pertama, Dampak Risiko di Core Sangat Besar: Karena semua modul berbagi klien Dio dan rantai interceptor yang sama, kesalahan kecil (regresi) yang tidak sengaja masuk ke wrapper core dapat melumpuhkan seluruh transaksi di aplikasi sekaligus. Mengubah interceptor jaringan menuntut pengujian integrasi yang sangat mendalam.
Kedua, Perilaku Tersembunyi Bagi Developer Baru: Ketika token otentikasi, header bahasa, dan logika refresh token disuntikkan otomatis oleh interceptor, engineer yang baru bergabung mungkin tidak langsung memahami apa yang sebenarnya terjadi pada request mereka. Dokumentasi internal yang jelas menjadi krusial agar tim memahami pekerjaan yang dilakukan oleh core wrapper di balik layar.
Ketiga, Upacara Penulisan Either: Mengelola Either menuntut pattern matching eksplisit (fold(), map()) di setiap pemanggilan repository. Pola ini membutuhkan baris kode yang lebih banyak dibanding penulisan biasa. Namun bagi tim kami, jaminan aplikasi bebas dari layar crash di production adalah imbal hasil yang sepadan dengan baris kode ekstra tersebut.
Apa yang Bisa Dibawa dari Cerita Ini#
Jika kamu sedang menata lapisan data untuk aplikasi mobile-mu:
- Pusatkan Klien Jaringan Sejak Awal: Bangun satu wrapper HTTP terpadu di lapisan core untuk mengelola base URL, injeksi token auth, header bahasa, dan timeout secara konsisten di seluruh modul.
- Pisahkan Tempat Simpan Berdasarkan Sensitivitas: Jangan pernah menyimpan token JWT di shared preferences biasa. Gunakan secure storage terenkripsi hardware untuk kredensial rahasia, dan gunakan cache biasa hanya untuk pengaturan antarmuka.
- Gunakan Functional Result untuk Menghindari Crash: Gantikan blok try-catch yang berserakan dengan
Either<AppException, T>. Tangkap exception di batas lapisan Data agar layar antarmuka hanya berurusan dengan state data yang bersih dan terprediksi. - Otomatisasi Refresh Token di Interceptor: Lindungi layar aplikasi dari kerumitan sesi login yang kadaluarsa dengan menjalankan pembaruan token secara hening di dalam interceptor jaringan.
Penutup#
Lapisan data yang tangguh adalah fondasi tak terlihat yang menjaga keandalan aplikasi mobile berskala besar. Dengan mengalirkan seluruh panggilan HTTP melalui pipeline Dio terpusat, mengunci kredensial pengguna di dalam brankas terenkripsi hardware, dan menerapkan batas penanganan error fungsional, Holigo memastikan gangguan jaringan di lapangan tidak pernah merusak stabilitas transaksi pengguna.
Pada Part 6 nanti, kita akan meninjau Fitur Kapal (Pelni) sebagai studi kasus implementasi end-to-end: bagaimana modul perjalanan lainnya memakai ulang cetak biru ini, bagaimana konfigurasi dinamis backend mengendalikan tema hari raya tanpa rilis store, serta bagaimana otomatisasi lokalisasi multibahasa dikelola menggunakan pipeline berkas ARB terpisah.
Terima kasih telah membaca :)
P.S. Seri ini ditulis di level keputusan desain arsitektur dan sistem rekayasa perangkat lunak, tanpa membuka kode rahasia, endpoint internal, atau data perusahaan. Jika kamu memiliki pertanyaan mengenai interceptor Dio, functional error handling, atau strategi secure storage, mari berdiskusi!