Entitas HTML vs encoding URL: mana yang harus dipakai

Entitas HTML dipakai untuk menampilkan karakter HTML yang bersifat reserved dan simbol khusus secara literal di dalam HTML. Jika Anda ingin menampilkan `<div>` sebagai teks, bukan membuat browser menganggapnya sebagai tag, entitas HTML adalah solusi yang tepat. Hal yang sama berlaku untuk ampersand, tanda kutip, apostrof, simbol euro, dan karakter lain yang dapat mengubah struktur markup atau membuat hasil render tidak konsisten di berbagai sistem.

Encoding URL, yang juga dikenal sebagai percent encoding, menyelesaikan masalah yang berbeda. Ia menjaga sebuah nilai tetap aman di dalam sintaks URL saat nilai itu harus hidup di query string, segmen path, target redirect, atau tautan yang dibagikan. Spasi, ampersand, tanda sama dengan, tanda tanya, dan karakter URL reserved lain dapat merusak atau mengubah makna sebuah tautan jika dibiarkan mentah. Encoding URL menjaga struktur URL agar parser berikutnya bisa memulihkan nilai yang dimaksud.

Itu berarti pertanyaan yang benar bukan Mana encoding yang terlihat lebih teknis. Pertanyaan yang benar adalah Parser mana yang akan membaca nilai ini berikutnya. Jika parser berikutnya adalah rendering HTML, pikirkan entitas HTML. Jika parser berikutnya adalah sintaks URL, pikirkan encoding URL.

Entitas HTML adalah langkah yang tepat ketika Anda perlu membuat teks tetap terlihat dan literal di dalam lingkungan HTML. Halaman dokumentasi adalah contoh klasik karena sering perlu menampilkan tag contoh seperti `<a>` atau `<section>` tanpa merendernya. Hal yang sama juga terjadi pada teks bantuan CMS, snippet dukungan, catatan rilis, dan contoh yang disalin ke artikel basis pengetahuan.

Ini juga penting untuk copy biasa, bukan hanya kode. Jika sebuah blok CMS dirender sebagai HTML dan teksnya mengandung karakter reserved seperti `&`, `<`, atau tanda kutip dalam konteks atribut yang sensitif, teks mentah dapat mengubah markup atau menghasilkan keluaran yang membingungkan. Meng-encode versi tampilan dengan entitas HTML akan melindungi hasil yang terlihat sambil tetap mempertahankan teks sumber asli di tempat lain.

Jalan pintas mental yang berguna cukup sederhana: jika pengguna harus melihat karakternya sendiri, bukan membuat browser menafsirkannya secara struktural, entitas HTML biasanya merupakan jawaban yang tepat.

Encoding URL adalah pilihan yang tepat ketika suatu nilai harus melintasi batas URL dengan aman. Contoh umum meliputi parameter redirect, query pencarian, status filter, tautan kampanye, callback URL, dan URL bersarang yang dikirim sebagai nilai query. Dalam alur seperti ini, browser, router framework, proxy, atau parser backend pertama-tama membutuhkan sintaks URL yang valid.

Contoh realistisnya adalah nilai redirect seperti `/checkout?step=shipping&plan=pro` yang perlu ditempatkan di dalam URL lain seperti `/login?next=...`. Jika Anda memasukkan nilai bersarang itu apa adanya, ampersand dan tanda sama dengan bisa diparse sebagai bagian dari query string luar. Encoding URL menjaga nilai bersarang itu tetap utuh sehingga bisa didekode nanti tanpa kehilangan struktur.

Di sinilah banyak tim membuat pilihan yang salah. Mereka melihat ampersand lalu memikirkan entitas HTML karena ampersand juga bermasalah di HTML. Tetapi jika batas berikutnya adalah parser URL, percent encoding adalah lapisan yang benar. Masalahnya bukan markup yang terlihat. Masalahnya adalah sintaks URL.

Alur kerja nyata sering melibatkan lebih dari satu batas, itulah sebabnya kebingungan ini terus muncul. Nilai yang sama bisa memerlukan encoding URL pada satu lapisan dan entitas HTML pada lapisan lain. Misalnya, sebuah URL redirect mungkin memerlukan percent encoding secara internal agar parameter query-nya tetap utuh, tetapi ketika Anda kemudian menampilkan URL redirect penuh itu sebagai kode yang terlihat di halaman dokumentasi, versi yang ditampilkan mungkin juga memerlukan entitas HTML di sekitar ampersand atau tanda kurung sudut.

Pola yang sama muncul di panel admin, pratinjau CMS, dan dokumentasi dukungan. Sebuah tautan bisa saja benar secara teknis sebagai URL, tetapi tetap tampil buruk ketika ditempelkan ke artikel yang dirender sebagai HTML. Atau sebuah string bisa di-entity encode untuk tampilan literal lalu gagal ketika seseorang memakainya kembali di dalam parameter query, karena parser berikutnya bukan lagi HTML. Parser berikutnya adalah parser URL.

Karena itu, lebih membantu untuk berpikir secara berurutan daripada memilih satu label encoding untuk seluruh alur. Tanyakan apa yang diharapkan lapisan saat ini, encode untuk lapisan itu, dan jangan berasumsi bahwa satu transformasi akan menyelesaikan setiap konteks berikutnya.

Salah satu kesalahan umum adalah memakai entitas HTML pada nilai yang seharusnya tetap menjadi parameter URL yang berfungsi. Hasilnya sering berupa nilai yang terlihat rapi di dalam markup tetapi berhenti bekerja dengan benar saat melewati redirect, filter, atau tautan callback. Kesalahan sebaliknya juga sering terjadi: melakukan percent encoding pada contoh kode yang seharusnya ditampilkan secara literal di dokumentasi HTML. Tautan itu mungkin menjadi aman secara teknis untuk URL, tetapi keluaran untuk manusia jadi lebih sulit dibaca dan menyelesaikan masalah yang salah.

Kesalahan ketiga adalah melakukan encoding terlalu awal lalu lupa versi mana yang kanonis. Tim akhirnya menyalin string yang sudah di-entity encode ke kolom URL, atau memakai ulang target redirect yang sudah di-percent encode di dalam dokumentasi seolah-olah itu dibuat untuk tampilan literal. Setelah bentuk-bentuk ter-encode mulai berpindah di antara konteks yang tidak saling terkait, proses debug menjadi berantakan karena setiap sistem sekarang membaca lapisan yang salah.

Kesalahan keempat adalah menganggap entitas HTML dan encoding URL bisa dipertukarkan karena keduanya sama-sama mengubah ampersand, kutip, atau tanda baca. Keduanya tidak dapat dipertukarkan. Keduanya milik parser yang berbeda. Tumpang tindih karakter di permukaan justru membuat pilihan yang salah tampak masuk akal.

Mulailah dengan satu pertanyaan: parser berikutnya apa. Jika parser berikutnya adalah browser yang merender HTML, entitas HTML mungkin relevan. Jika parser berikutnya adalah parser URL, encoding URL mungkin relevan. Lalu tanyakan pertanyaan kedua: apakah nilai ini harus ditampilkan secara literal atau diproses sebagai bagian dari struktur. Jika jawabannya ditampilkan secara literal, pikirkan entitas. Jika jawabannya diparse sebagai bagian dari URL, pikirkan percent encoding.

Contoh alur nyata membantu memperjelas. Misalkan sebuah artikel dukungan perlu menampilkan contoh tautan redirect yang mengandung parameter query. Target redirect sebenarnya mungkin memerlukan encoding URL agar tetap valid secara sintaks. Tetapi snippet yang terlihat di dalam artikel mungkin juga memerlukan entitas HTML agar pengguna bisa membaca contoh itu tanpa browser menafsirkannya sebagai markup aktif. Kedua encoding bisa sama-sama benar, tetapi hanya jika diterapkan pada tahap yang tepat.

Aturan ini lebih andal daripada menghafal daftar karakter. Aturan ini menjaga perhatian Anda tetap pada batas dan niat, karena di situlah sebagian besar kesalahan sebenarnya dimulai.

Ketika sesuatu tampak rusak, jangan mulai dengan mengganti karakter secara membabi buta. Mulailah dengan memeriksa dari mana nilai itu berasal, bentuk encoding apa yang sedang dipakai, dan parser mana yang membacanya berikutnya. Jika sebuah nilai sudah berisi `&amp;`, mungkin Anda sedang melihat bentuk tampilan HTML, bukan teks mentah. Jika nilainya penuh dengan urutan persen seperti `%26` dan `%3D`, mungkin Anda sedang melihat representasi yang aman untuk URL, bukan sesuatu yang dimaksudkan untuk tampil langsung di konten.

Lalu uji satu batas pada satu waktu. Pertama verifikasi teks sumber mentah atau URL mentah. Berikutnya verifikasi bentuk ter-encode yang dimaksudkan untuk target terdekat. Terakhir verifikasi apakah lapisan di hilir masih memerlukan encodingnya sendiri. Pendekatan ini sangat berguna dalam alur CMS, dokumentasi dukungan, dan alat admin, tempat teks sering disalin antar antarmuka yang tidak berbagi aturan parsing yang sama.

Sebagian besar bug encoding berhenti terasa misterius begitu Anda memisahkan lapisan-lapisannya. Bagian yang sulit jarang terletak pada konversinya sendiri. Bagian yang sulit adalah menyadari representasi mana yang milik konteks yang mana.