Codifica URL Spiegata nel Dettaglio

La codifica URL è uno di quei temi che sembra banale finché la produzione non inizia a restituire 400 Bad Request su ogni ricerca che contiene un accento francese. Le regole sono semplici, ma sono distribuite tra quattro specifiche che non concordano completamente, e le funzioni di supporto JavaScript hanno nomi che ingannano attivamente. Questa guida raccoglie le regole in un unico posto e contrassegna i punti in cui gli standard discordano silenziosamente.

Cosa significa davvero “URL encoding”

Gli URL sono limitati a un piccolo sottoinsieme di ASCII. Qualsiasi carattere al di fuori di quel set — o qualsiasi carattere che ha un significato strutturale che il parser altrimenti interpreterebbe — deve essere rappresentato come uno o più byte preceduti da %. Questo è il percent-encoding, e le regole su cosa codificare provengono da RFC 3986. Potete provare qualsiasi esempio con il nostro encoder URL.

RFC 3986 divide i caratteri in tre gruppi. Il set non riservato è A-Z a-z 0-9 - . _ ~; questi sono sempre sicuri e non richiedono mai la codifica. Il set riservato (: / ? # [ ] @ ! $ & ' ( ) * + , ; =) ha un significato strutturale in qualche parte dell’URL; codificateli quando intendete il carattere letterale, lasciateli intatti quando intendete il delimitatore. Tutto il resto — inclusi spazio, ", <, >,{ e tutto il non-ASCII — deve essere percent-encoded.

Dove ogni carattere deve essere codificato

Lo stesso byte può o meno richiedere la codifica a seconda di quale componente dell’URL appare. Un segmento di percorso permette : e @ non codificati; un valore di query non ha bisogno di codificare / o ? (perché il parser si ferma a #); un frammento è il componente più permissivo di tutti. In pratica, quasi tutti ignorano queste distinzioni e codificano qualsiasi cosa al di fuori del set non riservato quando interpolano un valore in un URL. Questo è conservativo e corretto.

L’unico punto in cui questo è importante: non codificate i caratteri / che separano i segmenti del vostro percorso. Codificate ogni segmento, poi uniteli con /. Se codificate anche la barra, ottenete %2F nel percorso, che la maggior parte dei server rifiuterà per ragioni di sicurezza (altrimenti permetterebbe agli attaccanti di contrabbandare sequenze ..oltre i controlli di directory).

encodeURI vs encodeURIComponent in JavaScript

JavaScript include due encoder, e la differenza tra essi è la fonte di un’enorme quantità di tempo di debug sprecato.

• encodeURI(value) assume che value sia già un URL completo. Lascia intatti i caratteri riservati (; / ? : @ & = + $ , #) in modo che l’URL rimanga analizzabile. Codifica spazi, accenti e il piccolo insieme di caratteri che non sono mai permessi in nessuna parte di un URL.
• encodeURIComponent(value) assume che value sia un singolo componente che viene inserito in un URL — di solito un segmento di percorso o un valore di query. Codifica tutto tranne il set non riservato più ! ' ( ) *.

La regola generale: se state costruendo un URL per concatenazione, usate encodeURIComponent su ogni valore interpolato. Se state normalizzando un URL già costruito, encodeURI è lo strumento giusto. Non c’è quasi nessun caso in cui vogliate applicare entrambi.

Dati form: l’eccezione +/spazio

Gli invii di form HTML codificano usando il media type application/x-www-form-urlencoded, definito nello standard URL WHATWG. Quel formato diverge da RFC 3986 in due modi. Primo, gli spazi diventano + invece di %20. Secondo, un + letterale nel valore viene codificato come %2B in modo che il decoder possa distinguerli.

Sia %20 che + si decodificano in uno spazio in pratica — ogni parser server-side mainstream accetta entrambi in una query string. Ma gli emettitori dovrebbero essere coerenti. Usate + nei corpi dei form e nelle query string che imitano i corpi dei form; usate %20 altrove, specialmente nei segmenti di percorso dove + è un segno più letterale.

Array e oggetti annidati: non esiste uno standard

Le query string sono state progettate per coppie chiave=valore piatte. Le strutture dati annidate devono essere appiattite, e la regola di appiattimento è una decisione per-framework. Le quattro convenzioni ampiamente usate:

1. Chiavi ripetute. ?tag=js&tag=ts diventa un array sul server. La convenzione più semplice; default in Express, Go's net/url e la maggior parte dei parser Node.
2. Bracket stile PHP. ?tag[]=js&tag[]=ts per gli array; ?user[name]=alex per oggetti annidati. I bracket devono essere percent-encoded (%5B / %5D) per essere strettamente conformi agli standard, sebbene la maggior parte dei server accetti la forma grezza.
3. Notazione punto Rails. ?user.name=alex&user.age=30. Meno comune oggi; compare in alcune API Ruby e .NET più vecchie.
4. Separato da virgola. ?tag=js,ts. Comune nelle API REST (OpenAPI lo elenca come stileform/explode=false). Conciso ma ambiguo se i valori stessi possono contenere virgole.

Scegliete una convenzione per API e documentatela. I bug più dolorosi in quest’area provengono da un client che emette bracket parlando con un server che si aspetta chiavi ripetute: entrambi sembrano funzionare, ma uno di essi conserva silenziosamente solo l’ultimo valore.

CJK, emoji e altri non-ASCII

Ogni carattere al di fuori dell’ASCII deve essere codificato come suoi byte UTF-8, poi percent-encoded byte per byte. Il carattere 北 (U+5317) sono i tre byte E5 8C 97 in UTF-8, che diventano %E5%8C%97 in un URL. Le emoji seguono la stessa regola: 🔥 (U+1F525) sono i quattro byte F0 9F 94 A5, codificati come %F0%9F%94%A5.

I sistemi legacy a volte emettono lo stesso carattere in una codifica diversa — GBK per il cinese, Shift-JIS per il giapponese, Windows-1251 per il cirillico. Se state integrando con un backend precedente al 2010 e il vostro testo decodificato risulta incomprensibile, provate a interpretare i byte come Windows-1252 o la codifica nativa del locale prima di assumere che l’URL sia corrotto.

Nomi di dominio internazionalizzati

I nomi host seguono una regola diversa. I nomi host non ASCII vengono codificati come Punycode (RFC 3492), non percent-encoded. Il dominio 例え.jp diventa xn--r8jz45g.jp nell’effettiva query DNS. I browser mostrano la forma Unicode per gli script riconosciuti ma trasmettono la forma Punycode sul wire. Se vi trovate a costruire un URL con un host non-ASCII, convertite l’host con un encoder Punycode, non con l’encoder URL.

Insidie comuni

• Doppia codifica. La codifica di un valore e poi il passaggio del risultato attraverso un altro encoder produce %2520 invece di %20. Tracciate ogni passaggio di codifica esplicitamente; non “codificate tanto per sicurezza” su un valore che non avete prodotto voi.
• I frammenti hash sono solo lato client. Tutto ciò che viene dopo # non viene mai inviato al server. Mettere lo stato nel frammento è una scelta deliberata (privacy, routing di app a pagina singola); farlo accidentalmente nasconde i bug finché il server non inizia a dipendere da esso.
• I segni più nei link mailto. mailto:[email protected] funziona perché gli URL mailto usano le regole RFC 3986, non la codifica dei form. Costruite i link mailto a mano, non con un form-encoder.
• Il set non riservato esclude storicamente la tilde. RFC 2396 (il predecessore di 3986) trattava ~come riservato. I vecchi encoder emettono ancora %7E; lo standard moderno lo considera non riservato. Entrambi si decodificano ugualmente.
• I limiti di lunghezza sono reali. La maggior parte dei server limita gli URL a 8 KB. I browser variano da 2 KB (IE precedente) a 32 KB (Chrome moderno). Se la vostra query string si avvicina a quel limite, spostate il payload in un corpo POST.

Un flusso di lavoro pratico

Quando si costruiscono URL nel codice: costruire un oggetto che rappresenti i componenti (schema, host, segmenti di percorso, mappa delle query), poi serializzare una volta con una libreria di fiducia — URL e URLSearchParams nei browser, gli equivalenti in ogni altro linguaggio principale. Gli URL assemblati a mano sono i bug.

Quando si esegue il debug di un URL codificato che qualcuno ha inviato, incollatelo nel nostro URL encoder/decoder e cambiate la direzione. Lo strumento decodifica un clic alla volta, quindi se dovete cliccare due volte per ottenere testo leggibile avete confermato la doppia codifica a monte.

La conclusione onesta

Usate encodeURIComponent su ogni valore interpolato, mai su un URL completo. Abbinate la vostra codifica dei form (spazio-come-più) al vostro contesto di trasporto. Scegliete una convenzione di array per API e documentatela. Fidatevi di UTF-8. E quando qualcosa sembra doppiamente codificato, quasi certamente lo è — tracciate il secondo encoder invece di coprirlo con un passaggio di decodifica.