De bug die me deze tool deed bouwen was waanzinnig klein Ik was een HTML e-mail template aan het vullen - een paar honderd regels met aanhalingstekens, regeleindes, en een vreemde backslash - in een JSON veld om naar een API te sturen, en het verzoek bleef terugkomen als een 400. de template was prima op zichzelf De JSON was prima Maar op het moment dat de twee elkaar ontmoetten, sloot een onontsnapt dubbel citaat driehonderd tekens in stilte de string vroeg, en alles nadat het in vuilnis veranderde kon de parser niet begrijpen Ik had geldige tekst in een geldige container geplakt en een ongeldig document geproduceerd.
Dat is het hele probleem dat JSON escaping oplost, en het is de moeite waard om te begrijpen in plaats van om te werken Deze gids behandelt wat ontsnappen eigenlijk doet, welke karakters moeten worden ontsnapt en waarom, hoe unescaping het omkeert, en hoe je de gratis kunt gebruiken Json ontsnapping / onontgonnen hulpmiddel om willekeurige tekst in en uit JSON-strings te verplaatsen zonder een enkele stille storing. Het staat naast de andere gegevenshulpprogramma's waarover ik in de Ultieme gids voor JSON-tools.
tl;dr: Een JSON-tekenreeks kan geen onbewerkte dubbele aanhalingstekens, een onbewerkte backslash of onbewerkte besturingstekens zoals nieuwe regels en tabbladen bevatten. Escaping vervangt elk een backslash-reeks -
"HALD\", een nieuwe regel wordt\n, een tabblad wordt\t, en al het andere onder U+0020 wordt\uXXXX. Onontsnappen verandert die sequenties weer in de originele karakters De Json ontsnapping / onontgonnen tool doet beide in uw browser, met opties om het resultaat in aanhalingstekens te verpakken, ontsnap aan niet-ASCII als\uXXXX, of ontsnap aan de voorwaartse schuine streep.
Wat betekent het om te ontsnappen aan een touwtje voor JSON?
JSON heeft een precieze, gepubliceerde grammatica - het wordt gedefinieerd door RFC 8259 en volgens de ECMA-404 standaard - en de regels voor wat er in een string mag voorkomen zijn streng Een JSON string is een reeks tekens die in dubbele aanhalingstekens zijn verpakt Omdat het dubbele aanhalingsteken het begin en einde van de string markeert, een dubbele aanhalingstekens binnenzijde de tekst zou er voortijdig een einde aan maken Omdat de backslash een escape sequence begint, zou een rauwe backslash verkeerd worden gelezen als het begin van een En omdat JSON strings bedoeld zijn om een enkele logische regel tekst te zijn, mogen letterlijke besturingstekens - nieuwe regels, tabbladen, koetsretouren - niet ongeëxcaped erin zitten.
Ontsnappen is het proces waarbij elk van die lastige karakters wordt vervangen door een backslash-reeks van twee tekens die JSON begrijpt. Een dubbele aanhalingstekens wordt \". Een terugslag wordt \\. Een nieuwe lijn wordt \n. Het resultaat is tekst die eruit zien iets lelijker maar is nu veilig om tussen twee aanhalingstekens te laten vallen zonder het omringende document te breken De betekenis is identiek - een JSON-parserlezing \n levert weer een echte nieuwe lijn op - maar de vertegenwoordiging is nu legaal.
Dit is fundamenteel anders dan het formatteren van een JSON-document Een formatter rangschikt de structuur van een heel object: inspringen, sleutelvolgorde, witruimte tussen elementen Escaping werkt één niveau naar beneden, op de inhoud van een enkele stringwaarde. Je reikt naar de JSON-formatter wanneer u een heel document mooi moet afdrukken of valideren, en voor de Json ontsnapping / onontgonnen tool als u een klomp ruwe tekst heeft die u in één veld moet passen.
Welke personages moeten eigenlijk ontsnappen?
De JSON specificatie is hier verfrissend specifiek Binnenin een string, precies twee karakters moest altijd ontsnapt zijn, plus het hele scala aan besturingstekens.
De twee verplichte ontsnappingen van één teken zijn de dubbele aanhalingstekens (\") en de backslash (\\). Daarnaast definieert JSON korte ontsnappingen voor vijf veel voorkomende besturingstekens: backspace (\b), formulierinvoer (\f), nieuwe regel (\n), retour van het vervoer (\r), en horizontaal tabblad (\t). Elk nog controleteken - alles met een codepunt onder U+0020 dat geen kort formulier heeft - moet worden geschreven als een \u escape gevolgd door vier hexadecimale cijfers, dus een nulbyte wordt \u0000 en de "unit separator" wordt \u001F.
Nog twee personages zijn facultatief om te ontsnappen, en hier sluipt verwarring binnen. De voorwaartse schuine streep kan worden geschreven als \/, maar het hoeft niet zo te zijn: een vlakte / is perfect valide JSON. En elk teken boven het ASCII-bereik, zoals een geaccentueerd teken é of een emoji, kan letterlijk in een UTF-8-document worden geschreven of ontsnapt als \uXXXX; beide zijn legaal De Json ontsnapping / onontgonnen tool verwerkt altijd de verplichte ontsnappingen en geeft u schakelaars voor de twee optionele, zodat u kunt matchen wat uw doelsysteem verwacht.
Moet ik ontsnappen aan de voorwaartse schuine streep en niet-ASCII-tekens?
Deze twee optionele ontsnappingen bestaan om echte redenen, zelfs als je ze zelden nodig hebt.
De forward-slash escape is van belang in precies één veel voorkomende situatie: wanneer JSON is ingebed in een HTML <script> tag. De browser's HTML-parser zoekt naar de letterlijke reeks </ om het einde van een scriptblok te vinden, dus een tekenreeks met daarin </script> in uw JSON kan de tag voortijdig sluiten en de pagina breken Schrijven van de schuine streep als <\/script> - nog steeds geldig JSON, nog steeds dezelfde string eenmaal geparseerd - vermijdt dat Buiten inline scripts, kunt u slashes met rust laten, daarom laat de tool de voorwaartse slash standaard onbegaan.
Ontsnappen aan niet-ASCII-tekens als \uXXXX gaat eerder over draagbaarheid dan over correctheid Als je JSON door een systeem zou kunnen gaan dat UTF-8 bytes verminkt - een oude logging pipeline, een verkeerd geconfigureerde proxy, een kanaal dat ASCII aanneemt - waardoor elk teken boven het ASCII-bereik in een pure-ASCII verandert \u escape garandeert dat het intact overleeft De uitvoer is omvangrijker en minder voor mensen leesbaar, dus standaard is deze uitgeschakeld, maar de & quot; Escape Unicode" toggle is er voor het moment dat u kogelvrij transport nodig hebt Een codepunt als é HALD \u00e9, en een JSON-parser reconstrueert het originele personage op weg naar buiten.
Hoe werkt unescaping, en wanneer heb ik het nodig?
Onontsnappen is precies het omgekeerde: het loopt door een ontsnapte reeks en verandert elke backslash-reeks terug in het ruwe teken dat het vertegenwoordigt. \n wordt een echte nieuwe lijn, \t wordt een tabblad, \" een dubbele aanhalingstekens wordt, en \uXXXX wordt het teken op dat codepunt Je hebt het nodig wanneer je aan de ontvangende kant bent - je hebt een tekenreekswaarde rechtstreeks uit een JSON-bestand, een logregel of een API-antwoord gekopieerd, en je wilt de originele tekst lezen zonder een scherm vol backslashes in de weg.
Een goede unescaper doet twee dingen die een naïeve find-and-replace niet doet. Ten eerste worden er een enkel paar omringende dubbele aanhalingstekens verwijderd als de hele waarde wordt vermeld, zodat u kunt plakken "line one\nline two" rechtstreeks uit een JSON-document en schone tekst terughalen Tweede, het valideert zoals het gaat: een ongeldige escape-reeks zoals \x, of een verdwaalde backslash helemaal aan het einde van de string, is een echte fout, en de Json ontsnapping / onontgonnen tool rapporteert zijn positie in plaats van te raden en stilletjes verkeerde uitvoer te produceren Een duidelijke & quot; ongeldige ontsnapping krijgen op positie 14" verslaat het verkrijgen van tekst die er bijna goed uitziet maar subtiel beschadigd is.
De belangrijkste eigenschap om te vertrouwen is dat ontsnappen en ontsnappen exacte inverses zijn Ontsnap aan elke tekst en ontvlucht vervolgens het resultaat en je krijgt precies terug waar je mee begon, karakter voor karakter Die retourgarantie maakt het veilig om de tool als een routinematige stap in een pijplijn te gebruiken in plaats van een risicovolle transformatie die je met de hand moet controleren.
Ontsnappen versus gerelateerde tekenreeksbewerkingen
JSON escaping behoort tot een familie van " maak deze tekst veilig voor die context" transformeert en helpt ze op het rechte pad te houden. Hier ziet u hoe het zich verhoudt tot de buren waarmee ontwikkelaars het vaakst verwarren.
| Operation | Beschermt tegen | toonbeeld | kwast |
|---|---|---|---|
| JSON ontsnappen | Een JSON-tekenreeks breken met aanhalingstekens, backslashes of controletekens | he said "hi" → he said \"hi\" |
Json ontsnapping / onontgonnen |
| HTML-entiteitscode | HTML breken of XSS inschakelen met <, >, & |
<b> → <b> |
HTML-entiteiten |
| URL-percentage-code | Een URL breken met spaties of gereserveerde tekens | a b → a%20b |
teneinde |
| JSON-formaat/valideren | Structurele fouten in een heel document | geminifieerd → mooi gedrukt | JSON-formatter |
| JSON → YAML | Een configuratie verplaatsen tussen serialisatieformaten | {"a":1} → a: 1 |
json naar yaml |
Het op te merken patroon is dat elke ontsnapping zich richt op a uiteenlopen container. HTML-entiteiten voorkomen dat tekst HTML breekt; procentcodering zorgt ervoor dat het een URL niet breekt; JSON-ontsnapping weerhoudt het ervan een JSON-tekenreeks te breken. Door de verkeerde te gebruiken - HTML-codering van iets waarvoor JSON moet ontsnappen - blijft het echte probleem onopgelost en wordt een nieuwe laag ruis toegevoegd. Omdat dit allemaal op tekst draait, wil je misschien niet aan een server van derden overhandigen, bewaar ik al deze tools aan de clientzijde, wat het argument is dat ik volledig heb gemaakt in de gegevensprivacygids voor online tools.
Wat zijn de veelgemaakte fouten bij het inbedden van tekst in JSON?
De meest voorkomende fout is degene die me een middag heeft gekost: tekst met meerdere regels en onontkoombare aanhalingstekens rechtstreeks in een JSON-veld plakken en ervan uitgaan dat, omdat beide delen geldig zijn, het geheel geldig is. Het is niet - de container heeft regels waaraan de inhoud moet voldoen.
Een goede tweede is dubbel ontsnappen. Als een touwtje al een keer is ontsnapt en je ontsnapt er weer aan, elke \n HALD \\n en je newlines veranderen in een letterlijke backslash-n die geen parser terug zal converteren Dit gebeurt meestal wanneer een waarde door twee systemen gaat die er elk behulpzaam aan ontsnappen Als je uitvoer verdachte runs heeft van \\ waar je enkele backslashes verwachtte, ben je waarschijnlijk dubbel ontsnapt, en als je een keer niet ontsnapt, zal het worden opgelost. De derde val is het vergeten van een Windows-pad als C:\Users\me zit vol met backslashes, die elk moeten worden \\ - een onontsnapt pad in JSON is een klassieke bron van & quot; waarom is mijn JSON invalid" verwarring.
De oplossing voor alle drie is hetzelfde: laat de tool de ontsnapping precies één keer uitvoeren, op de grens waar ruwe tekst JSON ontmoet, en lees de samenvatting van het aantal tekens die deze laat zien om de gezondheid te controleren of er iets is veranderd. Wanneer u met de hand moet verifiëren, ontsnap dan met "wrap offertes" ingeschakeld en plak het resultaat in de JSON-formatter - als het als een geldige string parseert, is je ontsnapping correct.
Een uitgewerkt voorbeeld: een HTML-fragment insluiten in JSON
Laat me door de exacte situatie lopen die dit begon, want het zien van de transformatie doet ooit de regel blijven hangen Zeg dat je dit fragment wilt verzenden als de body veld van een API-verzoek:
<p>Hi "there",</p>
<p>Visit https://example.com/path</p>
Drie dingen in die tekst zullen vechten met JSON De twee dubbele citaten rond there zullen ze allemaal proberen de string te beëindigen De nieuwe regel tussen de alinea's is een letterlijk controleteken dat JSON binnen een string verbiedt. En de </p> reeksen zijn onschadelijk in een gewoon JSON-bestand, maar gevaarlijk als deze JSON ooit in een HTML wordt afgedrukt <script> label. Plak het fragment in de Json ontsnapping / onontgonnen tool, schakel " tussen aanhalingstekens wikkelen," en je krijgt een enkele, geldige JSON-tekenreeks: de aanhalingstekens worden \", de nieuwe regel wordt \n, en met "escape forward slash" ingeschakeld worden de afsluitende tags <\/p>. Laat die hele geciteerde waarde rechtstreeks in uw body veld en het verzoek gaat door.
De achteruitrit is net zo routine Wanneer een teamgenoot je een loglijn stuurt met een JSON-escaped message veld vol met \n en \", plak het in de tool, schakel over naar Unescape en lees de originele meerregelige tekst terwijl de backslashes verdwenen zijn Omdat de twee bewerkingen exacte inverses zijn, kun je een payload verplaatsen om deze te bewerken en weer in zonder angst voor corruptie - de samenvatting van het aantal tekens bevestigt dat de transformatie is uitgevoerd, en elke verkeerd opgemaakte ontsnapping wordt gemarkeerd met zijn positie in plaats van de tekst stilletjes te verminken. Die retourveiligheid is wat het ontsnappen uit een nerveuze handmatige stap verandert in iets dat je in een workflow kunt indelen en vergeten.
Veelgestelde vragen
Wat betekent het om te ontsnappen aan een touwtje voor JSON? JSON-tekenreekswaarden kunnen geen onbewerkte dubbele aanhalingstekens, een onbewerkte backslash of onbewerkte besturingstekens zoals nieuwe regels en tabbladen bevatten. Escaping vervangt elk van deze door een backslash-reeks - & quot; wordt & quot;, een nieuwe regel wordt \n, een tabblad wordt \t - dus de tekst kan in een JSON-tekenreeks worden geplaatst zonder de omringende structuur te verbreken.
Hoe verschilt dit van een JSON-formatter? Een JSON-formatter drukt of verkleint een heel JSON-document en valideert de structuur ervan. Deze tool werkt één niveau lager, op de inhoud van een enkele tekenreeks: het maakt willekeurige tekst veilig om in een JSON-waarde in te sluiten, of decodeert een ontsnappingswaarde terug naar onbewerkte tekst. Gebruik de formatter voor documenten en deze tool voor afzonderlijke tekenreeksen.
Welke personages worden ontsnapt? De dubbele aanhalingstekens ("), de backslash (\), backspace (\b), form feed (\f), newline (\n), carriage return (\r) en tab (\t) worden altijd ontsnapt, samen met elk ander besturingsteken onder U+0020 als \uXXXX. Optioneel wordt de voorwaartse schuine streep /en wordt elk niet-ASCII-teken \uXXXX.
Moet ik ontsnappen aan de voorwaartse slash? Het is optioneel. De JSON-specificatie staat zowel / als / toe, dus gewoon /is geldig. De enige plaats /zaken bevindt zich in een HTML
