encodeURIComponent vs encodeURI: quando usare l'uno o l'altro

Le due funzioni JavaScript per la codifica degli URL

JavaScript mette a disposizione due funzioni integrate per la codifica degli URL: encodeURI() ed encodeURIComponent(). Anche se possono sembrare simili, usare quella sbagliata può portare a URL corrotti, vulnerabilità di sicurezza o corruzione dei dati. Comprendere la differenza è fondamentale per gli sviluppatori web.

encodeURI() - Per URI completi

encodeURI() è pensata per codificare un URI completo. Codifica tutti i caratteri tranne quelli che hanno un significato speciale nella struttura di un URI. In particolare, NON codifica:

• Caratteri riservati: ; , / ? : @ & = + $ #
• Caratteri non riservati: lettere, cifre, - _ . ! ~ * ' ( )

// encodeURI preserva la struttura dell'URI
encodeURI('https://example.com/path?q=hello world&lang=en')
// "https://example.com/path?q=hello%20world&lang=en"
// Nota: :, /, ?, =, & NON vengono codificati

encodeURIComponent() - Per i componenti di un URI

encodeURIComponent() è pensata per codificare un singolo componente di un URI (come il valore di un parametro di query). Codifica TUTTI i caratteri tranne:

• Caratteri non riservati: lettere, cifre, - _ . ! ~ * ' ( )

// encodeURIComponent codifica tutto tranne i caratteri non riservati
encodeURIComponent('hello world & goodbye')
// "hello%20world%20%26%20goodbye"
// Nota: & VIENE codificato perché è un carattere riservato

// Usarla per il valore di un parametro di query
const url = 'https://example.com/search?q=' +
  encodeURIComponent('cats & dogs');
// "https://example.com/search?q=cats%20%26%20dogs"

Errori comuni

Errore 1: usare encodeURI per i valori di query

Se usi encodeURI() per codificare il valore di un parametro di query che contiene una e commerciale, quest'ultima non verrà codificata e verrà interpretata come separatore di parametri, corrompendo il tuo URL.

// SBAGLIATO: la e commerciale nel valore corrompe l'URL
const badUrl = 'https://api.example.com/search?q=' +
  encodeURI('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20&%20Jerry"
// Il server interpreta: q="Tom " e un parametro " Jerry" senza valore

// CORRETTO: usa encodeURIComponent
const goodUrl = 'https://api.example.com/search?q=' +
  encodeURIComponent('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20%26%20Jerry"
// Il server interpreta correttamente: q="Tom & Jerry"

Errore 2: usare encodeURIComponent per URL completi

Se usi encodeURIComponent() su un intero URL, codificherà i due punti, le barre, i punti interrogativi e gli altri caratteri strutturali, rendendo l'URL completamente inutilizzabile.

Quando usare l'uno o l'altro: la regola semplice

• Usa encodeURI() quando hai un URI completo che potrebbe contenere spazi o caratteri non ASCII ma la cui struttura è valida
• Usa encodeURIComponent() quando stai codificando un singolo elemento di dati che verrà inserito in un URI (valori di parametri di query, segmenti di percorso, ecc.)

L'alternativa URLSearchParams

Il JavaScript moderno offre l'API URLSearchParams, che gestisce la codifica automaticamente. Spesso è l'approccio migliore per costruire le query string:

const params = new URLSearchParams({
  q: 'Tom & Jerry',
  category: 'cartoons & animation',
  page: '1'
});

const url = 'https://example.com/search?' + params.toString();
// "https://example.com/search?q=Tom+%26+Jerry&category=cartoons+%26+animation&page=1"

// Oppure usa l'API URL
const url2 = new URL('https://example.com/search');
url2.searchParams.set('q', 'Tom & Jerry');
console.log(url2.toString());