URL Encoding (Percent-Encoding) Nedir?
Bir URL yalnızca sınırlı bir karakter kümesini güvenle taşıyabilir. RFC 3986 standardına göre bir URL'de doğrudan kullanılabilecek karakterler İngilizce harfler, rakamlar ve birkaç işaretle (- _ . ~) sınırlıdır; bunun dışında kalan her şey — boşluk, Türkçe karakterler (ü, ı, ş, ğ, ö, ç), &, =, % gibi işaretler ya da herhangi bir Unicode karakter — bir URL'nin içine ham hâliyle güvenle yerleştirilemez. Bir sorgu dizesinde geçen boşluk, parametreleri ayıran & karakteriyle karışabilir; bir Unicode karakter ise farklı sistemler tarafından farklı yorumlanabilir.
URL encoding (percent-encoding, yüzde-kodlama) bu sorunu çözer: izin verilmeyen her karakteri, o karakterin bayt değerine karşılık gelen %XX biçiminde bir onaltılık (hexadecimal) koda çevirir. Böylece URL, yalnızca güvenli ASCII karakterlerinden oluşan, her yerde aynı şekilde yorumlanan bir metne dönüşür.
Yüzde-Kodlama Nasıl Çalışır?
Kodlama, karakterin UTF-8 baytları üzerinden çalışır. ASCII aralığındaki bir karakter (İngilizce harfler, rakamlar) tek bir bayt olduğundan tek bir %XX grubuna dönüşür; örneğin boşluk karakteri her zaman %20 olur. Çok baytlı bir UTF-8 karakter ise birden fazla %XX grubuna dönüşür: Türkçe ü harfi UTF-8'de iki bayttan oluştuğu için %C3%BC şeklinde kodlanır.
RFC 3986, karakterleri iki gruba ayırır. Ayrılmamış (unreserved) karakterler — A-Z a-z 0-9 - _ . ~ — hiçbir zaman kodlanmaz, çünkü bunların bir URL yapısında özel bir anlamı yoktur. Ayrılmış (reserved) karakterler ise : / ? # [ ] @ (genel ayırıcılar) ile ! $ & ' ( ) * + , ; = (alt ayırıcılar) gibi bir URL'nin yapısını (protokol, yol, sorgu, parça) belirleyen karakterlerdir; bu karakterler bağlama göre ya olduğu gibi bırakılır ya da kodlanır.
Somut bir örnek üzerinden bakalım: encodeURIComponent("merhaba dünya") çalıştırıldığında sonuç merhaba%20d%C3%BCnya olur. Boşluk tek baytlık bir karakter olduğu için %20'ye dönüşür; iki baytlık ü harfi ise UTF-8'deki C3 BC baytlarına karşılık gelen %C3%BC'ye dönüşür. Sonuçta yalnızca ayrılmamış karakterler (harfler, rakamlar, - _ . ~) olduğu gibi kalır; geri kalan her şey yüzde işaretiyle başlayan bir koda çevrilir.
encodeURIComponent ile encodeURI Arasındaki Fark
JavaScript iki farklı kodlama fonksiyonu sunar ve ikisi birbirinin yerine kullanılamaz. encodeURIComponent, ayrılmamış karakterler (A-Z a-z 0-9 - _ . ~) dışındaki her karakteri kodlar; &, =, ?, / gibi URL yapısal karakterlerini de içine alır. Bu fonksiyon, bir sorgu parametresine veya path segmentine yerleştirilecek tek bir değeri kodlamak için tasarlanmıştır — örneğin kullanıcı girdisindeki bir & karakterini %26'ya çevirerek, bu karakterin yanlışlıkla bir parametre ayırıcısı gibi yorumlanmasını engeller.
encodeURI ise bir URL'nin yapısını oluşturan karakterlere (: / ? # [ ] @ ! $ & ' ( ) * + , ; =) dokunmaz. Bu fonksiyon, zaten birleştirilmiş ve yapısının korunması gereken tam bir URL'yi kodlamak için tasarlanmıştır — örneğin adres çubuğuna yapıştırılacak veya bağlantı olarak paylaşılacak tam bir URL.
Her iki fonksiyon da boşluğu %20'ye çevirir. Tek bir tarihsel istisna vardır: klasik HTML formlarının application/x-www-form-urlencoded ile gönderdiği veride boşluk, %20 yerine + işaretiyle kodlanır. Bu, form verilerine özgü ayrı bir kural olup encodeURIComponent veya encodeURI'nin ürettiği bir çıktı değildir.
Hangi Durumda Hangisini Kullanmalı?
| Senaryo | Kullanılacak Fonksiyon | Neden |
|---|---|---|
| Bir sorgu parametresinin değeri (ör. arama kelimesi) | encodeURIComponent | Değer içindeki &, =, boşluk gibi karakterler sorgu yapısını bozmasın diye tamamen kodlanır |
| Zaten oluşturulmuş, tam bir URL | encodeURI | URL'nin : / ? gibi yapısal karakterleri korunur, yalnızca boşluk ve Unicode karakterler kodlanır |
| Kodlanmış bir URL'yi çözmek (decode) | decodeURIComponent / decodeURI | Hangi fonksiyonla kodlandıysa aynı çift ile çözülmeli; aksi hâlde bazı karakterler yanlış yorumlanabilir |
Sık Yapılan Hatalar
- Tam bir URL'yi encodeURIComponent ile kodlamak: En klasik hatadır.
:ve/gibi yapısal karakterler de%3A/%2F'ye dönüşür ve elinizde artık geçerli bir URL değil, opak bir metin dizesi kalır. Tam URL için her zamanencodeURI, URL'nin içine gömülecek tek bir değer içinencodeURIComponentkullanılmalıdır. - Çift kodlama (double encoding): Zaten
%20içeren bir dizeyi tekrarencodeURIComponentile kodlarsanız,%işaretinin kendisi de kodlanır ve sonuç%2520gibi bozuk bir değere dönüşür. Bir değerin daha önce kodlanıp kodlanmadığını kontrol etmeden encode işlemini tekrarlamak, adres çubuğunda veya API isteklerinde garip karakter dizileriyle sonuçlanır. - Sorgu parametresi değerlerini hiç kodlamamak: Kullanıcıdan gelen bir metni doğrudan sorgu dizesine eklemek (
?q=+ ham metin), metinde&,#veya boşluk geçtiğinde URL'nin diğer parametrelerini bozar ya da sorguyu erken keser. Her parametre değeri ayrı ayrıencodeURIComponentile kodlanmalı, sonra&ile birleştirilmelidir. - Bozuk yüzde-kodlamasını çözmeye çalışmak:
decodeURIComponent, geçersiz bir%XXdizisiyle karşılaştığında (örneğin yarım kalmış bir%) hata fırlatır. Kullanıcı girdisiyle çalışan kodda bu çağrıyı bir hata yakalama bloğuyla sarmalamak gerekir.
KEYDAL URL Encode / Decode Aracı
Bir değeri mi yoksa tam bir URL'yi mi kodlayacağınızdan emin değilseniz, aradaki farkı canlı örneklerle görmek en hızlı yoldur. KEYDAL'ın URL encode/decode aracı, component modu (encodeURIComponent) ile tam URL modu (encodeURI) arasında geçiş yapmanızı sağlar; girdiğiniz metni anında kodlar veya çözer, tamamı tarayıcınızda çalışır ve hiçbir veri sunucuya gönderilmez.
Metni veya tam URL'yi component ya da tam URL moduyla kodlayın veya çözün.