Codifica URL dei caratteri speciali: guida di riferimento per sviluppatori

Caratteri speciali negli URL

Gli URL seguono una sintassi rigorosa definita dall'RFC 3986. Molti caratteri hanno significati speciali o non sono ammessi in determinate parti di un URL. Capire come codificare correttamente questi caratteri è fondamentale per costruire applicazioni web e API affidabili.

Il carattere spazio

Lo spazio è il carattere codificato più di frequente. Tuttavia, può essere codificato in due modi a seconda del contesto:

• %20 - Codifica percentuale secondo l'RFC 3986, usata nei percorsi degli URL e nella maggior parte dei contesti
• + - Usato nel formato application/x-www-form-urlencoded (invio dei form HTML)

Quando costruisci URL a livello di codice, preferisci %20 per coerenza. Quando componi i dati di un form, la notazione + è quella standard.

Approfondimento sui caratteri riservati

L'e commerciale (&)

L'e commerciale separa i parametri della query. Quando un'e commerciale compare nel valore di un parametro, deve essere codificata come %26 per evitare che venga interpretata come separatore. Nei contesti HTML deve inoltre essere codificata come entità, ovvero &.

Il punto interrogativo (?)

Il punto interrogativo separa il percorso dalla query string. Se un punto interrogativo compare nel valore di un parametro, deve essere codificato come %3F. Nota che encodeURI() NON codifica i punti interrogativi, mentre encodeURIComponent() lo fa.

Il cancelletto (#)

Il simbolo cancelletto introduce l'identificatore di frammento. Negli URL, qualsiasi # presente nel valore di un parametro della query deve essere codificato come %23, altrimenti il browser interpreterà tutto ciò che segue come identificatore di frammento e non lo invierà al server.

La barra (/)

Le barre separano i segmenti del percorso. Quando una barra compare nel valore di un segmento del percorso (ad esempio in un nome di file che contiene una barra), deve essere codificata come %2F. Nota che alcuni server potrebbero decodificare %2F e continuare comunque a trattarlo come separatore di percorso.

Caratteri Unicode

I caratteri non ASCII vengono codificati convertendoli prima nella loro sequenza di byte UTF-8 e applicando poi la codifica percentuale a ciascun byte. Ecco alcuni esempi:

• e latina con accento acuto (e) → UTF-8: 0xC3 0xA9 → %C3%A9
• carattere cinese (zhong) → UTF-8: 0xE4 0xB8 0xAD → %E4%B8%AD
• emoji (globo) → UTF-8: 0xF0 0x9F 0x8C 0x8D → %F0%9F%8C%8D

Codifica nei diversi componenti dell'URL

Componente	Da codificare	Esempio
Segmento del percorso	Spazi, ?, # e caratteri non ASCII	/path/my%20file
Chiave della query	=, &, #, +, spazi	my%20key=value
Valore della query	&, #, +, spazi, =	key=hello%20world
Frammento	Spazi e caratteri non ASCII	#section%20one

Errori comuni

• Dimenticare di codificare # nei valori della query (il resto dell'URL viene scartato silenziosamente)
• Codificare due volte stringhe già codificate (ottenendo %2520 invece di %20)
• Usare encodeURI() invece di encodeURIComponent() per i valori dei parametri
• Non codificare + nei valori della query (viene decodificato come uno spazio)
• Dare per scontato che tutti i server gestiscano %2F allo stesso modo nei percorsi