Entita HTML vs codifica URL: quale dovresti usare

Le entita HTML servono a far visualizzare letteralmente caratteri riservati di HTML e simboli speciali dentro HTML. Se vuoi mostrare `<div>` come testo invece di lasciare che il browser lo tratti come un tag, le entita HTML sono la soluzione giusta. Lo stesso vale per ampersand, virgolette, apostrofi, simboli dell'euro e altri caratteri che possono cambiare la struttura del markup o essere renderizzati in modo incoerente tra sistemi diversi.

La codifica URL, chiamata anche codifica percentuale, risolve un problema diverso. Tiene un valore al sicuro dentro la sintassi di un URL quando quel valore deve stare in una query string, in un segmento di path, in una destinazione di redirect o in un link condiviso. Spazi, ampersand, segni di uguale, punti interrogativi e altri caratteri riservati dell'URL possono rompere o deformare il significato di un link se restano grezzi. La codifica URL preserva la struttura dell'URL cosi il parser successivo puo recuperare il valore previsto.

Questo significa che la domanda giusta non e Quale codifica sembra piu tecnica. La domanda giusta e Quale parser legge questo valore dopo. Se il parser successivo e il rendering HTML, pensa alle entita HTML. Se il parser successivo e la sintassi URL, pensa alla codifica URL.

Le entita HTML sono la scelta corretta quando devi mantenere il testo visibile e letterale in un contesto HTML. Le pagine di documentazione sono un esempio classico, perche spesso devono mostrare tag di esempio come `<a>` o `<section>` senza renderizzarli. La stessa cosa succede nel testo di aiuto nei CMS, negli snippet di supporto, nelle note di rilascio e negli esempi copiati dentro articoli di knowledge base.

Questo conta anche per il testo normale, non solo per il codice. Se un blocco CMS viene renderizzato come HTML e il testo contiene caratteri riservati come `&`, `<` o virgolette in un contesto di attributo sensibile, il testo grezzo puo cambiare il markup o creare un output confuso. Codificare la versione da mostrare con entita HTML protegge il risultato visibile e lascia intatto il testo sorgente originale da qualche altra parte.

Una scorciatoia mentale utile e semplice: se l'utente deve vedere il carattere stesso e non far interpretare il browser la sua struttura, le entita HTML sono di solito la risposta giusta.

La codifica URL e la scelta giusta quando un valore deve attraversare in sicurezza un confine URL. Esempi comuni includono parametri di redirect, query di ricerca, stato dei filtri, link di campagne, callback URL e URL annidati passati come valori di query. In questi flussi il browser, il router del framework, il proxy o il parser backend hanno prima di tutto bisogno di una sintassi URL valida.

Un esempio realistico e un valore di redirect come `/checkout?step=shipping&plan=pro` che deve stare dentro un altro URL come `/login?next=...`. Se inserisci il valore annidato cosi com'e, ampersand e segni di uguale possono essere interpretati come parte della query string esterna. La codifica URL mantiene intatto il valore annidato cosi puo essere decodificato piu tardi senza perdere la struttura.

Qui molte squadre fanno la scelta sbagliata. Vedono un ampersand e pensano alle entita HTML perche anche in HTML gli ampersand sono problematici. Ma se il confine successivo e un parser URL, il livello corretto e la codifica percentuale. Il problema non e il markup visibile. Il problema e la sintassi URL.

I flussi reali spesso coinvolgono piu di un confine, ed e per questo che la confusione ritorna sempre. Lo stesso valore puo richiedere codifica URL a un livello e entita HTML a un altro. Per esempio, un URL di redirect puo aver bisogno della codifica percentuale internamente perche i suoi parametri di query restino intatti, ma quando in seguito mostri quell'URL completo come codice visibile dentro una pagina di documentazione, la versione mostrata puo avere bisogno anche di entita HTML attorno ad ampersand o parentesi angolari.

Lo stesso schema appare nei pannelli di amministrazione, nelle anteprime CMS e nei documenti di supporto. Un link puo essere tecnicamente corretto come URL e comunque essere mostrato male quando viene incollato in un articolo renderizzato come HTML. Oppure una stringa puo essere codificata con entita per essere mostrata letteralmente e poi fallire quando qualcuno la riusa dentro un parametro di query, perche il parser successivo non e piu HTML. E il parser URL.

Per questo aiuta pensare in sequenza invece di scegliere una sola etichetta di codifica per tutto il flusso. Chiedi cosa si aspetta il livello corrente, codifica per quel livello e evita di assumere che una sola trasformazione risolva ogni contesto successivo.

Un errore comune e usare entita HTML in un valore che dovrebbe restare un parametro URL funzionante. Questo spesso produce valori che si vedono bene nel markup ma smettono di comportarsi correttamente quando passano attraverso redirect, filtri o link di callback. Un altro errore e l'opposto: codificare con percentuali un esempio di codice che invece doveva essere mostrato letteralmente dentro documentazione HTML. Il link puo diventare tecnicamente sicuro per un URL, ma l'output per le persone diventa piu difficile da leggere e risolve il problema sbagliato.

Un terzo errore e codificare troppo presto e poi dimenticare quale versione e quella canonica. I team finiscono per copiare una stringa codificata con entita in un campo URL, oppure riusare una destinazione di redirect codificata con percentuali dentro la documentazione come se fosse pensata per la visualizzazione letterale. Quando le forme codificate iniziano a muoversi tra contesti non correlati, il debug diventa complicato perche ogni sistema sta leggendo il livello sbagliato.

Un quarto errore e credere che entita HTML e codifica URL siano intercambiabili perche entrambe modificano ampersand, virgolette o punteggiatura. Non sono intercambiabili. Appartengono a parser diversi. La sovrapposizione superficiale dei caratteri e proprio cio che rende plausibile la scelta sbagliata.

Parti da una domanda: qual e il parser successivo. Se il parser successivo e il browser che renderizza HTML, le entita HTML sono probabilmente rilevanti. Se il parser successivo e il parser URL, la codifica URL e probabilmente rilevante. Poi fai una seconda domanda: questo valore deve essere mostrato letteralmente o eseguito come struttura. Se la risposta e mostrato letteralmente, pensa alle entita. Se la risposta e parsato come parte di un URL, pensa alla codifica percentuale.

Un esempio di flusso realistico aiuta. Supponi che un articolo di supporto debba mostrare un esempio di link di redirect che contiene parametri di query. La destinazione reale del redirect puo richiedere la codifica URL per restare sintatticamente valida. Ma lo snippet visibile dentro l'articolo puo anche richiedere entita HTML cosi gli utenti leggono l'esempio senza che il browser lo interpreti come markup attivo. Entrambe le codifiche possono essere corrette, ma solo se applicate nella fase giusta.

Questa regola e piu affidabile che memorizzare elenchi di caratteri. Mantiene l'attenzione sul confine e sull'intento, che e dove inizia la maggior parte degli errori.

Quando qualcosa sembra rotto, non iniziare cambiando i caratteri alla cieca. Parti controllando da dove proviene il valore, in quale forma codificata si trova ora e quale parser lo legge dopo. Se un valore contiene gia `&amp;`, potresti stare guardando una forma di visualizzazione HTML, non testo grezzo. Se un valore e pieno di sequenze percentuali come `%26` e `%3D`, potresti stare guardando una rappresentazione sicura per URL, non qualcosa pensato per la visualizzazione diretta nei contenuti.

Poi testa un confine alla volta. Prima verifica il testo sorgente grezzo o l'URL grezzo. Poi verifica la forma codificata pensata per il target immediato. Infine verifica se un altro livello a valle ha ancora bisogno della propria codifica. Questo approccio e particolarmente utile nei flussi CMS, nella documentazione di supporto e negli strumenti admin, dove il testo viene copiato tra interfacce che non condividono le stesse regole di parsing.

La maggior parte dei bug di codifica smette di sembrare misteriosa quando separi i livelli. La parte difficile raramente e la conversione in se. La parte difficile e accorgersi di quale rappresentazione appartiene a quale contesto.