Il bug che mi ha fatto costruire questo strumento era esasperantemente piccolo Stavo riempiendo un modello di email HTML - poche centinaia di righe con virgolette, interruzioni di riga e la barra rovesciata dispari - in un campo JSON da inviare a un'API, e la richiesta continuava a tornare come un 400 Il modello andava bene Il JSON andava bene da solo Ma nel momento in cui i due si incontrarono, una doppia citazione senza escape di trecento caratteri chiuse silenziosamente la stringa in anticipo, e tutto dopo che si trasformò in spazzatura il parser non poté dare un senso. Avevo incollato testo valido in un contenitore valido e prodotto un documento non valido.
Questo è l'intero problema che JSON sfugge risolve, e vale la pena capire piuttosto che lavorare intorno Questa guida copre ciò che fugge fa effettivamente, quali personaggi devono essere sfuggiti e perché, come unescaping lo inverte e come usare il libero Fuga di JSON / Unescape strumento per spostare testo arbitrario dentro e fuori le stringhe JSON senza un singolo guasto silenzioso Si trova accanto alle altre utilità di dati di cui ho scritto nel Guida definitiva agli strumenti JSON.
tl; dr: Una stringa JSON non può contenere una virgoletta doppia grezza, una barra rovesciata grezza o caratteri di controllo grezzi come newline e schede. L'evasione sostituisce ciascuno con una sequenza di barra rovesciata -
"diventa\", una nuova riga diventa\n, una scheda diventa\te qualsiasi altra cosa al di sotto di U+0020 diventa\uXXXX. Unescaping trasforma di nuovo quelle sequenze nei personaggi originali Il Fuga di JSON / Unescape tool fa entrambe le cose nel tuo browser, con opzioni per avvolgere il risultato tra virgolette, sfuggire non ASCII come\uXXXX, o sfuggire alla barra in avanti.
Cosa significa sfuggire a una stringa per JSON?
JSON ha una grammatica precisa e pubblicata: è definita da RFC 8259 e secondo lo standard ECMA-404 - e le regole per ciò che può apparire all'interno di una stringa sono rigide Una stringa JSON è una serie di caratteri avvolti in virgolette doppie Poiché la virgoletta doppia segna l'inizio e la fine della stringa, una virgoletta doppia interiore il testo lo finirebbe prematuramente Poiché la barra rovesciata inizia una sequenza di escape, una barra rovesciata grezza verrebbe interpretata erroneamente come l'inizio di una E poiché le stringhe JSON sono pensate per essere un'unica riga logica di testo, i caratteri di controllo letterali - newline, tab, ritorni a capo - non possono sedersi al loro interno senza escape.
Fuggire è il processo di sostituzione di ciascuno di quei personaggi problematici con una sequenza di backslash di due caratteri che JSON capisce Una doppia citazione diventa \". Una barra rovesciata diventa \\. Una nuova riga diventa \n. Il risultato è un testo che aspetto un po 'più brutto ma ora è sicuro di cadere tra due segni di citazione senza rompere il documento circostante Il significato è identico - una lettura parser JSON \n produce di nuovo una vera e propria newline - ma la rappresentazione è ora legale.
Questo è fondamentalmente diverso dalla formattazione di un documento JSON Un formattatore dispone la struttura di un intero oggetto: indentazione, ordinamento dei tasti, spazi bianchi tra gli elementi Escaping opera un livello verso il basso, sul contenuto di un valore di stringa singola. Raggiungi il Formattatore JSON quando hai un intero documento da stampare o convalidare, e per il Fuga di JSON / Unescape strumento quando si dispone di un grumo di testo grezzo è necessario adattarsi all'interno di un campo.
Quali personaggi hanno effettivamente bisogno di scappare?
La specifica JSON è piacevolmente specifica qui All'interno di una stringa, esattamente due caratteri muffa essere sempre sfuggito, più l'intera gamma di caratteri di controllo.
Le due fughe obbligatorie a carattere singolo sono la doppia citazione (\") e la barra rovesciata (\\). Oltre a questi, JSON definisce brevi escape per cinque caratteri di controllo comuni: backspace (\b), formare mangime (\f), nuova riga (\n), ritorno del carrello (\r) e scheda orizzontale (\t). Qualsiasi altro carattere di controllo - tutto ciò che ha un punto di codice sotto U + 0020 che non ha una forma breve - deve essere scritto come un \u escape seguito da quattro cifre esadecimali, quindi diventa un byte nullo \u0000 e il separatore di unità & quot; diventa \u001F.
Altri due personaggi sono opzionale per scappare, ed è qui che si insinua la confusione La barra in avanti può essere scritta come \/ma non deve essere una pianura / è perfettamente valido JSON. E qualsiasi carattere al di sopra della gamma ASCII, come un accentato é oppure un'emoji, può essere scritta letteralmente in un documento UTF-8 o sfuggita come \uXXXX; entrambi sono legali. IL Fuga di JSON / Unescape tool gestisce sempre le escape obbligatorie e ti offre levette per le due opzionali in modo da poter abbinare qualunque cosa il tuo sistema di destinazione si aspetti.
Dovrei sfuggire alla barra in avanti e ai caratteri non ASCII?
Queste due fughe opzionali esistono per motivi reali, anche se raramente ne hai bisogno.
L'escape forward-slash è importante esattamente in una situazione comune: quando JSON è incorporato all'interno di un HTML <script> tag. Il parser HTML del browser's cerca la sequenza letterale </ per trovare la fine di un blocco di script, quindi una stringa contenente </script> nel tuo JSON puoi chiudere prematuramente il tag e rompere la pagina Scrivendo la barra come <\/script> - ancora valido JSON, ancora la stessa stringa una volta analizzato - evita che Al di fuori degli script in linea, è possibile lasciare da solo le barre, motivo per cui lo strumento lascia la barra in avanti senza escape per impostazione predefinita.
Fuggire da personaggi non ASCII come \uXXXX riguarda la portabilità piuttosto che la correttezza Se il tuo JSON potrebbe passare attraverso un sistema che manipola i byte UTF-8 - una vecchia pipeline di registrazione, un proxy configurato in modo errato, un canale che presuppone ASCII - trasformando ogni carattere al di sopra dell'intervallo ASCII in un puro-ASCII \u escape garantisce che sopravviva intatto L'output è più ingombrante e meno leggibile dall'uomo, quindi è disattivato per impostazione predefinita, ma il & quot; Escape Unicode" toggle è lì per il momento hai bisogno di un trasporto a prova di proiettile Un punto di codice come é diventa \u00e9, e un parser JSON ricostruisce il personaggio originale mentre esce.
Come funziona l'inevitabilità e quando ne ho bisogno?
L'inevasione è l'esatto inverso: cammina attraverso una stringa sfuggita e trasforma nuovamente ogni sequenza di barra rovesciata nel carattere grezzo che rappresenta. \n diventa una vera e propria newline, \t diventa una scheda, \" diventa una doppia citazione, e \uXXXX diventa il carattere in quel punto di codice Ne hai bisogno ogni volta che sei sul lato ricevente - hai copiato un valore di stringa direttamente da un file JSON, una riga di registro o una risposta API e vuoi leggere il testo originale senza una schermata di backslash nel modo.
Un buon unescaper fa due cose che un ingenuo trova e sostituisci non. Innanzitutto, spoglia una singola coppia di virgolette doppie circostanti se viene citato l'intero valore, quindi puoi incollare "line one\nline two" direttamente da un documento JSON e ottieni un testo pulito. Secondo, lo validate come va: una sequenza di escape non valida come \x, o una barra rovesciata vagante all'estremità della stringa, è un errore reale e il Fuga di JSON / Unescape tool riporta la sua posizione piuttosto che indovinare e produrre output silenziosamente sbagliato Ottenere un chiaro & quot; fuga non valida alla posizione 14" batte ottenere testo che sembra quasi giusto ma è sottilmente corrotto.
La proprietà chiave di cui fidarsi è che fuggire e non sfuggire sono inversioni esatte. Fuggi da qualsiasi testo e poi sfuggi al risultato e ottieni esattamente ciò con cui hai iniziato, carattere per carattere. Quella garanzia di andata e ritorno è ciò che rende sicuro utilizzare lo strumento come passaggio di routine in una pipeline piuttosto che come trasformazione rischiosa, devi ricontrollare manualmente.
Escape rispetto alle operazioni relative alle stringhe
JSON escape fa parte di una famiglia di & quot; rendi questo testo sicuro per quel contesto" si trasforma e aiuta a mantenerli dritti. Ecco come si confronta con i vicini con cui gli sviluppatori molto spesso lo confondono.
| Operazione | Protegge contro | esempio | strumento |
|---|---|---|---|
| fuga JSON | Rompere una stringa JSON con virgolette, barre rovesciate o caratteri di controllo | he said "hi" → he said \"hi\" |
Fuga di JSON / Unescape |
| Codifica entità HTML | Interruzione dell'HTML o abilitazione di XSS con <, >, & |
<b> → <b> |
Entità HTML |
| Codice percentuale URL | Rompere un URL con spazi o caratteri riservati | a b → a%20b |
- |
| formato JSON/validato | Errori strutturali in un intero documento | minificato → piuttosto stampato | Formattatore JSON |
| JSON → YAML | Spostamento di una configurazione tra i formati di serializzazione | {"a":1} → a: 1 |
JSON a Yaml |
Lo schema da notare è che ogni fuga prende di mira a differente contenitore. Le entità HTML impediscono al testo di violare l'HTML; la codifica percentuale impedisce di violare un URL; L'escape JSON gli impedisce di rompere una stringa JSON. L'utilizzo di quello sbagliato, ovvero la codifica HTML di qualcosa che necessita dell'escape di JSON, lascia il problema reale irrisolto e aggiunge un nuovo livello di rumore. Poiché tutto questo viene eseguito su testo che potresti non voler consegnare a un server di terze parti, mantengo ognuno di questi strumenti lato client, che è l'argomento che ho fatto per intero guida alla privacy dei dati per gli strumenti online.
Quali sono gli errori comuni quando si incorpora il testo in JSON?
Il singolo errore più comune è quello che mi è costato un pomeriggio: incollare testo multi-riga con virgolette non escaped direttamente in un campo JSON e supponendo che, poiché entrambe le parti sono valide, l'insieme non lo è - il contenitore ha regole a cui il contenuto deve obbedire.
Un secondo vicino è doppia fuga. Se una stringa è già stata fuoriuscita una volta e la si sfugge di nuovo, ogni \n diventa \\n e le tue newline si trasformano in una backslash-n letterale che nessun parser convertirà indietro Questo di solito accade quando un valore passa attraverso due sistemi che sfuggono utilmente ciascuno Se il tuo output ha esecuzioni sospette di \\ dove ti aspettavi singole barre rovesciate, probabilmente sei scappato due volte, e una volta senza fuga lo risolverà La terza trappola è dimenticare che un percorso di Windows come C:\Users\me è pieno di barre rovesciate, ognuna delle quali deve diventare \\ - un percorso senza escape in JSON è una classica fonte di & quot; perché il mio JSON non è valido" confusione.
La correzione per tutti e tre è la stessa: lascia che lo strumento esegua l'escape esattamente una volta, al confine in cui il testo grezzo incontra JSON, e leggi il riepilogo del conteggio dei caratteri che mostra per verificare la sanità mentale che qualcosa è cambiato Quando devi verificare manualmente, scappa con & quot; avvolgi virgolette" abilitato e incolla il risultato nel Formattatore JSON - se viene analizzato come una stringa valida, la tua fuga è corretta.
Un esempio funzionante: incorporare uno snippet HTML in JSON
Lasciami camminare attraverso la situazione esatta che ha iniziato questo, perché vedere la trasformazione una volta rende la regola bastone Dire che si vuole inviare questo frammento come il body campo di una richiesta API:
<p>Hi "there",</p>
<p>Visit https://example.com/path</p>
Tre cose in quel testo combatteranno con JSON. Le due virgolette doppie in giro there ognuno cercherà di terminare la stringa La nuova riga tra i paragrafi è un carattere di controllo letterale che JSON proibisce all'interno di una stringa. E il </p> le sequenze sono innocue in un semplice file JSON ma pericolose se questo JSON viene mai stampato all'interno di un HTML <script> tag. Incolla il frammento nel Fuga di JSON / Unescape strumento, attiva & quot; avvolgi tra virgolette, & quot; e ottieni una singola stringa JSON valida: le virgolette diventano \", la nuova riga diventa \n, e con & quot; escape forward slash" abilitato i tag di chiusura diventare <\/p>. Rilascia l'intero valore quotato direttamente nel tuo body campo e la richiesta passa attraverso.
Il viaggio inverso è altrettanto di routine Quando un compagno di squadra ti invia una linea di registro con un JSON-scappato message campo pieno di \n e \", incollalo nello strumento, passa a Unescape e leggi il testo originale a più righe con le barre rovesciate scomparse Poiché le due operazioni sono inverse esatte, puoi spostare un payload fuori per modificarlo e rientrare senza timore di corruzione - il riepilogo del conteggio dei caratteri conferma l'esecuzione della trasformazione e qualsiasi fuga malformata viene segnalata con la sua posizione invece di manipolare silenziosamente il testo Quella sicurezza di andata e ritorno è ciò che trasforma la fuga da un passaggio manuale nervoso in qualcosa che puoi collegare in un flusso di lavoro e dimenticare.
Domande frequenti
Cosa significa sfuggire a una stringa per JSON? I valori delle stringhe JSON non possono contenere una virgoletta doppia grezza, una barra rovesciata grezza o caratteri di controllo grezzi come le nuove righe e le schede Escaping sostituisce ognuno di questi con una sequenza di barra rovesciata - & quot; diventa & quot;, una nuova riga diventa \n, una scheda diventa \t - quindi il testo può essere inserito all'interno di una stringa JSON senza rompere la struttura circostante.
In che modo è diverso da un formattatore JSON? Un formattatore JSON imprime o minimizza un intero documento JSON e ne convalida la struttura. Questo strumento funziona un livello in meno, sul contenuto di una singola stringa: rende sicuro l'incorporamento di un testo arbitrario all'interno di un valore JSON o decodifica un valore escape nel testo grezzo. Utilizzare il formattatore per i documenti e questo strumento per le singole stringhe.
Quali personaggi vengono fuggiti? La doppia citazione (& quot;), la barra rovesciata (\), lo spazio arretrato (\b), il feed della forma (\f), la nuova riga (\n), il ritorno del carrello (\r) e la scheda (\t) vengono sempre eliminati, insieme a qualsiasi altro carattere di controllo inferiore a U+0020 come \uXXXX. Facoltativamente, la barra in avanti diventa /e ogni carattere non ASCII diventa \uXXXX.
Devo sfuggire al taglio in avanti? È opzionale Le specifiche JSON consentono sia / che /, quindi è valido il semplice /. L'unico posto/ conta è all'interno di un HTML
