Qual è la differenza tra encodeURI e encodeURIComponent?

Cos'è encodeURI()?

encodeURI() è una funzione JavaScript integrata progettata per codificare un Uniform Resource Identifier (URI) completo. Converte i caratteri non validi in un URI nei loro equivalenti percent-encoded, ma preserva intenzionalmente i caratteri che hanno un significato strutturale all'interno di un URI.

In particolare, encodeURI() non codifica i seguenti caratteri: A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #. Ciò significa che la struttura complessiva dell'URL rimane intatta dopo la codifica.

// encodeURI() preserva la struttura dell'URL
const url = 'https://example.com/my page?name=John Doe&city=New York';
console.log(encodeURI(url));
// "https://example.com/my%20page?name=John%20Doe&city=New%20York"
// Nota: :, /, ?, & e = NON vengono codificati

Questo comportamento rende encodeURI() ideale quando hai un URL completo che può contenere spazi o caratteri non ASCII, ma i cui caratteri strutturali (separatore di protocollo, delimitatori di percorso, marcatori della query string) devono rimanere invariati.

Cos'è encodeURIComponent()?

encodeURIComponent() è progettata per codificare un singolo componente di un URI, come il valore di un parametro di query o un segmento del percorso. A differenza di encodeURI(), codifica quasi ogni carattere speciale, compresi quelli che hanno un significato strutturale negli URL.

Gli unici caratteri che encodeURIComponent() non codifica sono: A-Z a-z 0-9 - _ . ! ~ * ' ( ). Tutto il resto, inclusi /, ?, &, =, # e :, viene percent-encoded.

// encodeURIComponent() codifica tutto tranne i caratteri unreserved
const value = 'Tom & Jerry / Friends?';
console.log(encodeURIComponent(value));
// "Tom%20%26%20Jerry%20%2F%20Friends%3F"
// Nota: &, / e ? VENGONO codificati

// Costruzione di un URL con un parametro di query
const url = 'https://example.com/search?q=' + encodeURIComponent(value);
// "https://example.com/search?q=Tom%20%26%20Jerry%20%2F%20Friends%3F"

Poiché codifica i caratteri strutturali, non dovresti mai usare encodeURIComponent() su un URL completo. Farlo codificherebbe i ://, tutti i separatori di percorso / e il delimitatore di query ?, rendendo l'URL inutilizzabile.

Differenze principali a colpo d'occhio

Caratteristica	encodeURI()	encodeURIComponent()
Scopo	Codificare un URI completo	Codificare un componente di URI
Codifica /	No	Sì (%2F)
Codifica ?	No	Sì (%3F)
Codifica &	No	Sì (%26)
Codifica =	No	Sì (%3D)
Codifica #	No	Sì (%23)
Codifica :	No	Sì (%3A)
Codifica gli spazi	Sì (%20)	Sì (%20)
Codifica Unicode	Sì	Sì

Quando usare ciascuna funzione

La regola è semplice: usa encodeURI() quando vuoi codificare un URL completo mantenendone valida la struttura. Usa encodeURIComponent() quando vuoi codificare un singolo valore che verrà inserito in un URL.

// Scenario 1: Codifica di un URL completo con spazi
const fullUrl = 'https://example.com/my documents/file name.pdf';
const encoded = encodeURI(fullUrl);
// "https://example.com/my%20documents/file%20name.pdf"

// Scenario 2: Costruzione di un URL a partire dai componenti
const baseUrl = 'https://api.example.com/search';
const query = 'price >= 100 & category = books';
const finalUrl = baseUrl + '?q=' + encodeURIComponent(query);
// "https://api.example.com/search?q=price%20%3E%3D%20100%20%26%20category%20%3D%20books"

// Scenario 3: Codifica di un URL di reindirizzamento come parametro
const redirectUrl = 'https://example.com/callback?token=abc';
const loginUrl = 'https://auth.example.com/login?redirect=' +
  encodeURIComponent(redirectUrl);
// L'intero URL di reindirizzamento viene codificato come un singolo valore di parametro

Errori comuni e come evitarli

Errore 1: Usare encodeURI() per i valori dei parametri di query. Poiché encodeURI() non codifica & o =, usarla su un valore di parametro che contiene questi caratteri corromperà la struttura della query string.

// SBAGLIATO
const bad = 'https://example.com/search?q=' + encodeURI('salt & pepper');
// "https://example.com/search?q=salt%20&%20pepper"
// Il server vede q="salt " e un parametro extra " pepper"

// CORRETTO
const good = 'https://example.com/search?q=' + encodeURIComponent('salt & pepper');
// "https://example.com/search?q=salt%20%26%20pepper"

Errore 2: Usare encodeURIComponent() su un URL completo. Questo distrugge la struttura dell'URL codificando tutte le barre, i due punti e i punti interrogativi.

// SBAGLIATO
console.log(encodeURIComponent('https://example.com/path?key=value'));
// "https%3A%2F%2Fexample.com%2Fpath%3Fkey%3Dvalue"
// Questo non è più un URL valido!

// CORRETTO
console.log(encodeURI('https://example.com/path?key=value'));
// "https://example.com/path?key=value" (già valido, niente da codificare)

Errore 3: Doppia codifica. Se una stringa è già percent-encoded, codificarla di nuovo codificherà i segni %, trasformando %20 in %2520. Verifica sempre se un valore è già stato codificato prima di applicare le funzioni di codifica.

Un'alternativa moderna più sicura è rappresentata dalle API URL e URLSearchParams, che gestiscono la codifica automaticamente e ti aiutano a evitare del tutto queste insidie.