Gli URL possono contenere solo un insieme ristretto di caratteri ASCII. Tutto il resto — spazi, accenti, emoji e la punteggiatura che gli URL usano per la loro struttura — va scritto come un segno di percentuale seguito dal valore del byte in esadecimale. La codifica percentuale è tutta qui. La parte interessante è sapere quali caratteri codificare, perché codificarne troppi rompe un URL esattamente quanto codificarne troppo pochi.
Gli encoder sono due, e sbagliare quale usare rompe le cose
JavaScript ti dà encodeURI ed encodeURIComponent, e differiscono per esattamente undici caratteri: # $ & + , / : ; = ? @. encodeURI li lascia stare; encodeURIComponent li codifica.
Quell'elenco non è arbitrario: sono precisamente i caratteri che in un URL hanno un significato strutturale. La barra separa i segmenti di percorso, il punto interrogativo apre la query, la e commerciale separa i parametri, il cancelletto inizia il frammento. Quindi la regola discende da sé: usa encodeURI quando hai un URL intero e vuoi lasciarne intatto lo scheletro. Usa encodeURIComponent quando hai un singolo valore che sta per essere infilato dentro un URL: un parametro di query, un segmento di percorso.
Invertili e il guasto è silenzioso. Codifica un URL intero con encodeURIComponent e ottieni una stringa in cui https%3A%2F%2F non è più uno schema, e nessuno la scaricherà. Codifica un valore di query con encodeURI e un valore che contiene & si spacca in due parametri senza dire niente: che non è solo un bug, è il meccanismo con cui funziona la query-parameter injection. Questo strumento codifica l'insieme completo dei caratteri di componente, che è il default sicuro per il caso comune: codificare un valore.
Il più non è uno spazio, tranne quando lo è
È la trappola più sottile di tutta la materia, ed è genuinamente ambigua, non solo confusa. Nella RFC 3986, la specifica che governa gli URL, uno spazio è %20 e un più è un più letterale. Ma i form HTML non usano la RFC 3986: usano application/x-www-form-urlencoded, una convenzione più vecchia in cui uno spazio si scrive +.
Il risultato è che la stessa stringa si decodifica in due modi diversi a seconda di chi la legge. decodeURIComponent("a+b") restituisce "a+b", tenendosi il più. new URLSearchParams("q=a+b").get("q") restituisce "a b", trasformandolo in spazio. Nessuna delle due sbaglia: implementano specifiche diverse. È per questo che una ricerca di "C++" arriva così spesso come "C ": qualcosa nella catena ha applicato le regole del form-encoding a un URL.
In pratica: dentro una query string, dai per scontato che + significhi spazio, perché è ciò che danno per scontato i browser e praticamente ogni framework server. Ovunque altro in un URL — un segmento di percorso, un frammento — un più è un più. La casella RFC 1738 di questa pagina cambia l'output verso la convenzione form-encoded esattamente per questo motivo.
Perché decodificare "100%" lancia un errore
In un URL codificato il segno di percentuale non è un carattere qualsiasi: è un marcatore di escape, e il decoder pretende esattamente due cifre esadecimali dopo di esso. Passa la stringa "100%" a decodeURIComponent e non ti restituisce "100%": lancia URIError: URI malformed, perché dopo la percentuale non c'è niente da leggere.
Salta fuori di continuo con dati veri. Codici sconto, statistiche, qualsiasi cosa contenga una percentuale letterale romperà un decoder a meno che la percentuale non sia stata a sua volta codificata come %25 all'andata. Se vedi URIError su dati forniti dagli utenti, il bug è quasi sempre a monte: qualcosa ha costruito l'URL concatenando stringhe invece di codificare correttamente ogni valore.
I caratteri non ASCII diventano più byte ciascuno
La codifica percentuale lavora sui byte, non sui caratteri, e gli URL moderni trasportano UTF-8. Quindi un carattere fuori dall'ASCII diventa un escape per ogni byte: é sono due byte e si codifica in %C3%A9, mentre un'emoji sono quattro byte e diventa dodici caratteri di escape.
Vale la pena ricordarlo quando c'è di mezzo un limite di lunghezza. Un percorso o un parametro che in giapponese o in arabo sembra comodamente corto può diventare tre volte più lungo una volta codificato, e alcuni sistemi impongono ancora limiti attorno ai 2000 caratteri per l'URL intero.
Domande frequenti
Il mio URL viene inviato a un server?
No. Questo strumento è marcato "client": la codifica gira nella scheda del tuo browser e il testo non lascia mai la macchina. Vale la pena dirlo perché gli URL dei sistemi veri portano spesso token di sessione, chiavi API o identificatori di clienti nella query string: se è il caso del tuo, trattalo come una credenziale a prescindere da dove lo incolli.
Per uno spazio devo usare + o %20?
%20 funziona sempre: è valido in ogni parte di un URL e ogni decoder lo capisce. + significa spazio solo dentro una query string, e solo sotto le regole del form-encoding. Nel dubbio usa %20, non è mai sbagliato. Usa + solo quando stai deliberatamente producendo dati form-encoded e sai che chi legge se li aspetta.
Il mio URL codificato contiene %2520. Cos'è successo?
Doppia codifica. %25 è una percentuale codificata, quindi %2520 è ciò che ottieni quando %20 passa da un encoder una seconda volta: la % è diventata %25 e il 20 si è accodato. Qualcosa nella tua pipeline sta codificando un valore già codificato. Codifica esattamente una volta, nel punto in cui costruisci l'URL, e mai su una stringa che non hai costruito tu.
Perché la mia e commerciale spacca il parametro in due?
Perché non è stata codificata quando il valore del parametro è stato costruito. In una query string & è il separatore tra parametri, quindi un valore che contiene una & grezza è indistinguibile dall'inizio di un parametro nuovo. Deve diventare %26. È anche il meccanismo dietro la parameter injection, quindi conviene sistemarlo per bene nel punto in cui costruisci l'URL invece di rattoppare il sintomo.
Devo codificare un URL preso dalla barra degli indirizzi?
Quasi certamente no: è già codificato, e ricodificarlo produce il problema del %2520 qui sopra. I browser mostrano una versione decodificata e leggibile mentre internamente tengono quella codificata. Quello che vedi non è quello che viene inviato. Se un URL contiene già degli escape %, è stato codificato: decodificalo per leggerlo, non ricodificarlo.