Memilih Penanganan URI Kustom: Parser Ketat vs Gateway Normalisasi

Memilih penanganan URI kustom adalah keputusan arsitektur, bukan sekadar detail implementasi parser. Saat format identifier belum benar-benar stabil, pilihan antara parser ketat di tiap service, shared parsing library, API gateway normalisasi, atau boundary adapter di edge akan memengaruhi coupling antar-layanan, kecepatan perubahan, observability, dan biaya operasional.

Jawaban singkatnya: tidak ada satu pola yang selalu paling benar. Jika aturan URI sudah stabil dan domain validation memang bagian dari logika bisnis, parser ketat di tiap service bisa masuk akal. Jika format masih bergerak, tim banyak, dan kompatibilitas mundur penting, normalisasi di boundary atau gateway biasanya lebih aman. Namun gateway terpusat juga bisa menjadi bottleneck dan titik coupling baru. Artikel ini membahas trade-off-nya secara praktis.

Mengapa URI kustom sering menjadi sumber masalah

URI atau identifier kustom sering terlihat sederhana di awal: sebuah string dengan skema, namespace, path, atau komponen lain. Masalah muncul ketika sistem berkembang dan beberapa hal berubah bersamaan:

• format awal ternyata terlalu longgar atau terlalu ketat,
• beberapa layanan mengimplementasikan parser sendiri dengan interpretasi berbeda,
• kompatibilitas lama harus tetap dijaga,
• edge case seperti encoding, case sensitivity, atau delimiter tidak diputuskan dengan jelas,
• tim berbeda merilis perubahan parser pada waktu berbeda.

Akibatnya, URI yang dianggap valid oleh satu layanan bisa ditolak layanan lain, atau lebih buruk: diterima semua layanan tetapi dimaknai berbeda. Ini lebih berbahaya daripada gagal cepat, karena kesalahannya berubah menjadi data inconsistency.

Sumber ambiguitas yang paling umum

• Normalisasi karakter: huruf besar/kecil, Unicode, percent-encoding.
• Delimiter ganda: misalnya penggunaan :, /, atau # yang tidak konsisten.
• Komponen opsional: host, authority, collection, fragment, query-like suffix.
• Alias historis: format lama masih hidup di klien lama.
• Perbedaan tujuan: satu layanan butuh validasi sintaks, layanan lain butuh validasi eksistensi atau otorisasi.

Karena itu, pembahasan tentang parser URI kustom sebaiknya dipisahkan menjadi tiga lapisan:

1. Parsing sintaks: apakah string bisa dipecah menjadi komponen yang sah?
2. Normalisasi: bentuk kanonik apa yang akan dipakai internal?
3. Validasi domain: apakah identifier ini bermakna dan diizinkan dalam konteks bisnis?

Banyak sistem bermasalah karena ketiganya dicampur dalam satu fungsi parser.

Empat pendekatan utama

1. Validasi ketat di tiap service

Pada pola ini, setiap layanan menerima string URI lalu mem-parsing dan memvalidasinya sendiri. Biasanya pendekatan ini muncul secara alami di arsitektur microservice, karena tiap layanan ingin mandiri dan tidak bergantung pada komponen sentral.

Kelebihan:

• Otonomi tinggi: layanan bisa berkembang tanpa menunggu gateway atau library pusat.
• Boundary jelas: tiap service bertanggung jawab atas input yang dia konsumsi.
• Cocok untuk domain validation lokal: misalnya layanan A hanya menerima subset URI tertentu.

Kekurangan:

• Risiko drift: implementasi parser berbeda sedikit demi sedikit antar-bahasa atau antar-tim.
• Biaya perubahan tinggi: perubahan format harus dirilis ke banyak layanan.
• Kompatibilitas mundur sulit: klien lama mungkin lolos di satu jalur, gagal di jalur lain.
• Observability terpecah: sulit menjawab "seberapa banyak URI format lama masih dipakai?" karena telemetry tersebar.

Kapan cocok: format URI sudah matang, jumlah layanan sedikit, dan parser bukan sumber perubahan yang sering.

2. Shared parsing library

Pola ini mencoba mengurangi drift dengan menyediakan satu library parser yang dipakai semua layanan. Ini sering terlihat ideal di atas kertas karena menjaga konsistensi tanpa harus membuat gateway sentral.

Kelebihan:

• Konsistensi implementasi lebih baik dibanding parser buatan tiap tim.
• Perubahan perilaku lebih terkendali karena aturan parsing terpusat dalam satu basis kode.
• Testing lebih efisien: satu test suite parser bisa dipakai lintas layanan.

Kekurangan:

• Coupling rilis: perbaikan parser tetap menuntut upgrade dependency di banyak service.
• Masalah multi-runtime: jika organisasi memakai beberapa bahasa, library harus di-port atau di-wrap.
• Versi campur aduk: layanan bisa berjalan dengan versi parser berbeda selama periode upgrade.
• Rasa aman palsu: konsisten di level sintaks, belum tentu konsisten di level normalisasi dan domain validation.

Kapan cocok: organisasi masih bisa menegakkan standardisasi dependency, bahasa runtime terbatas, dan format URI relatif stabil tetapi belum cukup stabil untuk hard-code tersebar.

3. API gateway normalisasi

Di pola ini, semua request yang masuk melewati gateway atau service ingress yang bertugas menerima variasi format lama, mem-normalisasi, lalu meneruskan bentuk kanonik ke backend.

Kelebihan:

• Kompatibilitas mundur lebih mudah: klien lama bisa tetap didukung tanpa mengotori semua backend.
• Rollout cepat: perubahan aturan penerimaan cukup dilakukan di satu tempat.
• Observability terpusat: mudah mengukur traffic format lama, parse error, atau pola input liar.
• Proteksi backend: layanan internal menerima bentuk yang lebih bersih dan seragam.

Kekurangan:

• Titik coupling sentral: perubahan gateway bisa berdampak ke banyak layanan sekaligus.
• Bottleneck operasional: performa, availability, dan rollback harus dikelola sangat hati-hati.
• Risiko semantik tersembunyi: backend mungkin lupa bahwa input awal sebenarnya ambigu atau sudah dimodifikasi.
• Tidak cocok untuk semua jalur: event internal, batch job, atau message bus bisa mem-bypass gateway.

Kapan cocok: banyak klien eksternal, kebutuhan kompatibilitas mundur tinggi, dan organisasi sanggup mengoperasikan ingress layer dengan disiplin yang baik.

4. Boundary adapter di edge

Pola ini mirip gateway normalisasi, tetapi adaptasi dilakukan di boundary yang lebih dekat ke sumber input: misalnya adapter per-protocol, per-API version, per-consumer, atau per-bounded context. Tujuannya bukan satu gateway besar yang mengetahui semua variasi, tetapi adapter yang mengubah format luar menjadi model internal yang stabil.

Kelebihan:

• Coupling lebih lokal: perubahan kompatibilitas untuk satu consumer tidak selalu menyentuh semua jalur.
• Lebih cocok untuk evolusi bertahap: tiap boundary bisa bermigrasi dengan jadwal berbeda.
• Domain internal tetap bersih: model kanonik hidup setelah boundary.

Kekurangan:

• Butuh disiplin desain: tanpa kontrak internal yang jelas, adapter hanya memindahkan kekacauan.
• Duplikasi parsial mungkin muncul antar-edge jika aturan dasar tidak dibagikan.
• Perlu governance agar semua edge mencatat telemetry dan error dengan format seragam.

Kapan cocok: ekosistem input beragam, tidak semua traffic masuk lewat satu gateway, atau organisasi ingin menghindari choke point sentral.

Tabel keputusan: pilih pendekatan berdasarkan konteks

Jika Anda butuh aturan praktis:

• Pilih parser ketat di tiap service bila URI sudah stabil dan layanan memang mengonsumsi subset domain yang berbeda.
• Pilih shared library bila masalah utamanya adalah inkonsistensi implementasi, bukan kompatibilitas eksternal.
• Pilih gateway normalisasi bila Anda harus menerima banyak variasi input lama dari klien eksternal.
• Pilih boundary adapter bila sumber input beragam dan Anda ingin menjaga inti sistem tetap stabil tanpa membuat gateway serba tahu.

Dampak arsitektur yang sering diremehkan

Skalabilitas tim

Skalabilitas tim bukan hanya jumlah layanan, tetapi juga jumlah koordinasi yang dibutuhkan untuk mengubah aturan format. Jika satu perubahan syntax rule menuntut sinkronisasi lintas 8 layanan dan 3 bahasa, maka parser menjadi masalah organisasi, bukan masalah kode.

Tanda bahwa desain saat ini tidak skala secara tim:

• perubahan parser harus diumumkan manual ke banyak tim,
• incident terjadi karena satu service belum upgrade parser,
• review PR parser berubah menjadi debat semantik lintas domain,
• tim tidak tahu di mana bentuk kanonik resmi didefinisikan.

Dalam situasi seperti itu, boundary normalization sering lebih efektif daripada memaksa semua tim seragam lewat proses.

Coupling antar-layanan

Shared library dan gateway sama-sama mengurangi drift, tetapi bentuk coupling-nya berbeda:

• Shared library menciptakan coupling di level dependency dan jadwal upgrade.
• Gateway menciptakan coupling di level perilaku runtime dan availability.

Mana yang lebih aman tergantung pola perubahan Anda. Jika parser berubah sering tetapi deployment backend lambat, gateway lebih fleksibel. Jika perubahan jarang dan availability layer sentral menjadi kekhawatiran besar, shared library bisa lebih sederhana.

Kompatibilitas mundur

Kompatibilitas mundur paling sulit ketika bentuk input lama sudah tersebar ke banyak jalur: HTTP API, queue, cron importer, event replay, dan admin tool. Jika Anda hanya menormalisasi di API gateway, tapi worker internal tetap membaca format mentah dari queue lama, maka konsistensi tetap gagal.

Karena itu, putuskan sejak awal: di mana bentuk mentah boleh hidup, dan di mana bentuk kanonik wajib digunakan. Ini harus menjadi aturan desain, bukan asumsi.

Biaya operasional

Gateway normalisasi terlihat murah secara pengembangan karena perubahan cepat dilakukan di satu tempat. Namun biaya operasionalnya bisa naik:

• harus highly available,
• menambah latensi dan titik observability,
• butuh rollback aman,
• harus diuji terhadap semua consumer.

Sebaliknya, parser tersebar tampak murah secara infrastruktur, tetapi mahal di koordinasi, regresi kompatibilitas, dan debugging.

Observability

Untuk masalah URI kustom, observability yang berguna bukan hanya error rate umum. Anda perlu tahu:

• berapa persen input masih memakai format lama,
• komponen mana yang paling sering gagal diparse,
• apakah normalisasi mengubah nilai secara semantik atau hanya kosmetik,
• layanan mana yang paling sering menerima bentuk non-kanonik,
• apakah parse failure terjadi di ingress, queue consumer, atau internal RPC.

Tanpa telemetry ini, tim cenderung membuat keputusan migrasi berdasarkan tebakan.

Contoh failure mode yang realistis

1. Parser menerima, resolver menolak

Sebuah layanan berhasil mem-parse URI karena hanya mengecek sintaks dasar. Namun layanan resolver yang dipanggil berikutnya menganggap komponen tertentu wajib. Hasilnya request gagal jauh setelah masuk sistem.

Dampak: error terlihat seperti kegagalan downstream, padahal akar masalah ada di boundary validation.

Perbaikan: pisahkan syntax validation dan domain validation, lalu dokumentasikan kontrak antar-layer.

2. Normalisasi mengubah identitas

Gateway mengubah huruf besar ke huruf kecil atau menghapus encoding tertentu, dengan asumsi dua representasi itu ekuivalen. Ternyata salah satu komponen bersifat case-sensitive atau encoding membawa makna.

Dampak: collision identifier, cache poisoning logis, atau salah target data.

Perbaikan: normalisasi hanya boleh dilakukan pada aturan yang benar-benar dipastikan ekuivalen secara semantik.

3. Shared library berbeda versi di beberapa service

Layanan A sudah menerima delimiter baru, layanan B belum. Input berhasil membuat resource, tetapi gagal saat dibaca ulang oleh layanan lain.

Dampak: sistem menjadi write-compatible tetapi tidak read-compatible.

Perbaikan: gunakan rollout berbasis capability atau version acceptance window, bukan sekadar upgrade dependency bertahap tanpa kontrol.

4. Queue menyimpan bentuk mentah tanpa schema evolution

HTTP ingress menormalisasi URI, tetapi event yang lama masih menyimpan string mentah. Worker baru mengasumsikan semua event sudah kanonik dan gagal memproses replay data historis.

Dampak: replay, backfill, atau disaster recovery memunculkan bug lama yang tidak terlihat pada traffic live.

Perbaikan: versi-kan payload event, atau simpan baik bentuk mentah maupun bentuk kanonik saat masa transisi.

5. Logging tidak menyimpan bentuk awal

Gateway langsung mengganti input ke bentuk kanonik dan log hanya menyimpan hasil akhir. Saat incident terjadi, tim tidak bisa membedakan apakah masalah berasal dari klien yang mengirim format aneh atau dari bug normalisasi.

Perbaikan: log dua nilai: raw_identifier dan canonical_identifier, dengan kebijakan redaksi jika sensitif.

Pola implementasi yang lebih aman

Pisahkan tipe data internal dari string mentah

Jangan oper-oper string URI mentah ke seluruh kode. Parse seawal mungkin di boundary yang tepat, lalu gunakan representasi terstruktur secara internal.

type CustomUri = {
  scheme: string,
  authority?: string,
  namespace: string,
  resource: string,
  fragment?: string,
  canonical: string,
  raw: string
}

function parseAtBoundary(raw: string): CustomUri | ParseError {
  // 1. parse sintaks
  // 2. validasi komponen wajib minimum
  // 3. bentuk canonical bila aman
  // 4. simpan raw untuk observability
}

Intinya bukan bahasa yang dipakai, tetapi kontrak: bentuk mentah tetap tersedia untuk audit, sedangkan logika internal memakai struktur yang sudah jelas.

Bedakan mode ketat dan mode toleran

Dalam banyak sistem, Anda butuh dua mode:

• Toleran saat menerima input eksternal agar kompatibilitas transisi bisa dikelola.
• Ketat di dalam sistem agar data baru tidak terus memperluas permukaan ambiguitas.

Ini lebih sehat daripada satu parser yang mencoba sekaligus menerima semua variasi dan menghasilkan perilaku berbeda-beda diam-diam.

Gunakan contract test untuk parser

Jika parser dipakai lintas layanan atau lintas bahasa, siapkan shared corpus berisi kasus valid, invalid, legacy, dan canonicalization expectation.

cases:
  - raw: "example:acct:User123"
    accept: true
    canonical: "example:acct:User123"
  - raw: "example://acct/User123"
    accept_legacy: true
    canonical: "example:acct:User123"
  - raw: "example:acct:"
    accept: false
    error_code: "missing-resource"

Setiap implementasi parser harus lulus corpus yang sama. Ini lebih andal daripada mengandalkan dokumentasi teks saja.

Tambahkan telemetry khusus parser

Minimal catat metrik dan log berikut:

• parse_attempt_total
• parse_failure_total per reason
• legacy_format_seen_total
• normalization_applied_total
• non_canonical_input_total

Dengan begitu, keputusan kapan mematikan format lama bisa didasarkan pada data.

Strategi migrasi bertahap tanpa memutus klien lama

1. Tetapkan bentuk kanonik resmi

Sebelum menyentuh kode, putuskan satu representasi internal yang dianggap benar. Tanpa ini, migrasi hanya memindahkan ambiguitas dari satu tempat ke tempat lain.

2. Inventarisasi semua boundary

Daftar semua titik masuk dan propagasi identifier:

• public API,
• internal RPC,
• message broker,
• ETL/importer,
• CLI/admin tools,
• database persistence.

Banyak migrasi gagal karena hanya memikirkan HTTP request, padahal data historis masuk lagi lewat replay event atau batch.

3. Mulai dengan accept-and-observe

Untuk format lama, jangan langsung blokir. Terima di boundary, normalisasi, lalu catat semua kemunculannya. Tujuannya adalah mendapatkan peta penggunaan nyata.

Catatan: accept-and-observe bukan berarti membiarkan semua bentuk liar. Tetap tolak input yang ambigu atau berbahaya. Toleransi hanya untuk variasi yang masih bisa dipetakan secara deterministik ke bentuk kanonik.

4. Emit bentuk kanonik ke downstream

Begitu input diterima, keluarkan hanya bentuk kanonik ke backend, event baru, dan storage baru. Ini mencegah utang kompatibilitas terus menyebar.

5. Tambahkan peringatan deprecation yang terukur

Jika memungkinkan, beri sinyal ke consumer bahwa format lama akan dihentikan, misalnya melalui header peringatan, dokumentasi kontrak, atau dashboard integrasi. Tetapi pastikan Anda punya data pemakaian aktual sebelum menetapkan tenggat.

6. Ketatkan parser internal lebih dulu

Langkah yang aman biasanya bukan memutus klien eksternal dulu, tetapi memastikan semua komponen internal sudah bisa bekerja hanya dengan bentuk kanonik.

7. Hapus acceptance legacy secara bertahap

Lakukan per boundary atau per consumer, bukan sekaligus. Gunakan feature flag jika perlu, sehingga rollback bisa dilakukan tanpa deploy besar.

Kapan monolit modular lebih masuk akal daripada microservice

Untuk kasus parsing format yang belum stabil, monolit modular sering lebih masuk akal daripada microservice. Alasannya praktis:

• Satu implementasi parser langsung dipakai semua modul tanpa masalah versi dependency antar-service.
• Refactor lebih murah saat aturan syntax dan canonicalization masih berubah.
• Observability lebih sederhana karena seluruh jalur data lebih mudah ditelusuri.
• Kompatibilitas internal lebih terjaga karena perubahan parser dan konsumen bisa dirilis bersama.

Microservice menjadi pilihan lebih masuk akal jika:

• domain sudah jelas terpisah,
• format identifier sudah matang atau setidaknya kontraknya stabil,
• beban organisasi untuk sinkronisasi parser bisa ditangani,
• ada kebutuhan operasional yang nyata untuk pemisahan deployment.

Jika format URI masih diperdebatkan dan edge case baru terus ditemukan, memecahnya terlalu cepat ke banyak layanan hanya memperbesar biaya koordinasi. Dalam kondisi ini, monolit modular dengan boundary yang disiplin sering memberikan fleksibilitas evolusi yang lebih baik daripada microservice.

Panduan keputusan praktis

Pilih parser ketat di tiap service jika:

• format sudah stabil dan terdokumentasi jelas,
• setiap service memang punya kebutuhan validasi domain yang berbeda,
• jumlah layanan terbatas,
• risiko drift bisa dikendalikan lewat contract test.

Pilih shared parsing library jika:

• masalah utama adalah inkonsistensi implementasi,
• organisasi tidak terlalu heterogen secara bahasa/runtime,
• Anda ingin konsistensi tanpa menambah komponen runtime sentral.

Pilih API gateway normalisasi jika:

• klien eksternal beragam dan kompatibilitas mundur adalah prioritas,
• variasi format terutama muncul di ingress,
• Anda butuh telemetry terpusat tentang input lama dan parse failure.

Pilih boundary adapter di edge jika:

• input datang dari banyak boundary berbeda,
• Anda ingin menghindari gateway global yang terlalu pintar,
• domain internal perlu tetap stabil sementara kontrak luar berevolusi.

Kesalahan desain yang sebaiknya dihindari

• Menganggap parsing sama dengan validasi bisnis.
• Menyebarkan string mentah ke seluruh sistem.
• Menormalisasi tanpa definisi ekuivalensi semantik yang jelas.
• Berpikir shared library otomatis menyelesaikan compatibility problem.
• Hanya memigrasi jalur HTTP dan melupakan queue, event, serta data historis.
• Tidak menyimpan raw input untuk debugging.

Penutup

Dalam memilih penanganan URI kustom, pertanyaan utamanya bukan parser mana yang paling elegan, tetapi di mana toleransi terhadap variasi input seharusnya ditempatkan, dan di mana sistem harus mulai bersikap ketat. Jika format belum stabil, menaruh toleransi di boundary lalu menjaga inti sistem tetap kanonik biasanya memberi hasil terbaik. Jika format sudah matang, parser ketat di tiap service atau shared library bisa lebih sederhana.

Keputusan yang baik biasanya mengikuti prinsip ini: terima variasi hanya di tepi, minimalkan ambiguitas di inti, dan ukur semua fase transisi. Dengan begitu, kompatibilitas mundur tetap terjaga tanpa menjadikan seluruh arsitektur bergantung pada string format yang belum benar-benar selesai.