Der Bug, der mich dazu brachte, dieses Tool zu bauen, war wahnsinnig kleinIch stopfte eine HTML-E-Mail-Vorlage - ein paar hundert Zeilen mit Anführungszeichen, Zeilenumbrüchen und dem einen oder anderen Backslash - in ein JSON-Feld, um sie an eine API zu senden, und die Anfrage kam immer wieder als 400. Die Vorlage war in Ordnung Das JSON war von selbst in Ordnung Aber in dem Moment, als sich die beiden trafen, schloss ein unausgelaufenes Doppelzitat mit dreihundert Zeichen stillschweigend die Zeichenfolge vorzeitig, und alles, nachdem es sich in Müll verwandelt hatte, konnte der Parser keinen Sinn ergeben Ich hatte gültigen Text in einen gültigen Container eingefügt und ein ungültiges Dokument erstellt.
Das ist das ganze Problem, das JSON beim Entkommen löst, und es lohnt sich, es zu verstehen, anstatt herumzuarbeiten. Dieser Leitfaden behandelt, was das Entkommen tatsächlich bewirkt, welche Charaktere entkommen müssen und warum, wie das Entweichen es umkehrt und wie man das Freie nutzt JSON-Flucht / Unentkommen Werkzeug, um beliebigen Text in und aus JSON-Strings zu verschieben, ohne dass ein einziger stiller Fehler vorliegt Es steht neben den anderen Datendienstprogrammen, über die ich in der geschrieben habe Ultimative Anleitung zu JSON-Toolsdrohen
tl; dr: Eine JSON-Zeichenfolge kann kein rohes Doppelzitat, keinen rohen Backslash oder rohe Steuerzeichen wie Zeilenumbrüche und Registerkarten enthalten. Escaping ersetzt jedes durch eine Backslash-Sequenz -
"wird\"Eine neue Zeile wird\nEine Registerkarte wird\tund alles andere unter U+0020 wird\uXXXX. Unescaping verwandelt diese Sequenzen wieder in die Originalcharaktere. Die JSON-Flucht / Unentkommen Tool erledigt beides in Ihrem Browser, mit Optionen, um das Ergebnis in Anführungszeichen zu wickeln, und entgeht Nicht-ASCII als\uXXXX, oder dem vorderen Schrägstrich entkommen.
Was bedeutet es, einer Zeichenfolge für JSON zu entkommen?
JSON hat eine präzise, veröffentlichte Grammatik - sie ist definiert durch RFC 8259 Und nach dem ECMA-404-Standard - und die Regeln für das, was innerhalb einer Zeichenkette erscheinen darf, sind streng Eine JSON-Zeichenfolge ist eine Reihe von Zeichen, die in doppelte Anführungszeichen gewickelt sind Weil das doppelte Anführungszeichen den Anfang und das Ende der Zeichenfolge markiert, ein doppeltes Anführungszeichen Innenseite Der Text würde ihn vorzeitig beenden Weil der Backslash eine Escape-Sequenz beginnt, würde ein roher Backslash als Beginn eines solchen falsch verstanden werden Und weil JSON-Strings eine einzige logische Textzeile sein sollen, dürfen wörtliche Steuerzeichen - Zeilenumbrüche, Tabs, Wagenrückläufe - nicht unausgeflogen darin sitzen.
Escaping ist der Prozess, jeden dieser problematischen Charaktere durch eine zweistellige Backslash-Sequenz zu ersetzen, die JSON versteht. Ein doppeltes Zitat wird \". Ein Backslash wird \\. Eine Newline wird \n. Das Ergebnis ist Text, der Aussehen Etwas hässlicher aber kann nun sicher zwischen zwei Anführungszeichen fallen, ohne das umgebende Dokument zu zerbrechen Die Bedeutung ist identisch - ein JSON-Parser mit der Lesart \n Wieder eine echte Newline produziert - aber die Darstellung ist nun legal.
Das unterscheidet sich grundlegend von der Formatierung eines JSON-Dokuments Ein Formatierer ordnet die Struktur eines ganzen Objekts an: Einrückung, Tastenreihenfolge, Leerraum zwischen Elementen Escaping operiert eine Ebene nach unten, auf der Inhalt eines einzelnen Zeichenfolgenwerts. Sie greifen nach der JSON-Formater Wenn Sie ein ganzes Dokument hübsch drucken oder validieren müssen, und für die JSON-Flucht / Unentkommen Werkzeug, wenn Sie einen Klumpen Rohtext haben, müssen Sie in ein Feld passen.
Welche Charaktere müssen eigentlich fliehen?
Erfrischend spezifisch ist hier die JSON-SpezifikationInnerhalb einer Zeichenkette genau zwei Zeichen müssen Immer entwischt werden, dazu kommt die gesamte Bandbreite der Steuerzeichen.
Die beiden obligatorischen Einzelzeichen-Ausweichmöglichkeiten sind das Doppelzitat (\") und der Backslash (\\). JSON definiert darüber hinaus kurze Escapes für fünf gemeinsame Steuerzeichen: Backspace (\b), Formfuttermittel (\f), Newline (\n), Wagenrücklauf (\r) und horizontale Lasche (\t). Irgendein sonst Steuerzeichen - alles, was einen Codepunkt unterhalb von U+0020 hat, der keine Kurzform hat - muss als geschrieben werden \u Escape gefolgt von vier Hexadezimalstellen, so dass ein Nullbyte wird \u0000 und das " Einheitentrennzeichen" wird \u001Fdrohen
Zwei weitere Charaktere sind Optional Flucht zu bringen, und hier schleicht sich Verwirrung ein Der Vorwärtsschlitz kann geschrieben werden als \/„, aber es muss nicht - eine Ebene sein / Ist vollkommen gültige JSON. Und jedes Zeichen oberhalb des ASCII-Bereichs, wie ein Akzent é oder ein Emoji, kann wörtlich in ein UTF-8-Dokument geschrieben oder als entkommen werden \uXXXX; beides ist legal Die JSON-Flucht / Unentkommen Das Tool kümmert sich immer um die obligatorischen Escapes und bietet Ihnen Umschalter für die beiden optionalen, sodass Sie alles erreichen können, was Ihr Zielsystem erwartet.
Soll ich dem Vorwärts-Schrägstrich und Nicht-ASCII-Zeichen entkommen?
Diese beiden optionalen Fluchten gibt es aus echten Gründen, auch wenn man sie selten braucht.
Der Forward-Slash-Escape ist in genau einer häufigen Situation wichtig: wenn JSON in einen HTML-Code eingebettet ist <script> Tag. Der Browser' s HTML-Parser sucht nach der wörtlichen Sequenz </ Ende eines Skriptblocks zu finden, so enthält eine Zeichenfolge </script> In Ihrem JSON kann das Tag vorzeitig geschlossen und die Seite unterbrochen werden Schreiben des Schrägstrichs als <\/script> - noch gültiger JSON, immer noch der gleiche String einmal geparst - vermeidet das Außerhalb von Inline-Skripten kann man Schrägstriche in Ruhe lassen, weshalb das Tool den Vorwärts-Schrägstrich standardmäßig unausgeflogen lässt.
Entfliehende Nicht-ASCII-Zeichen als \uXXXX Es geht eher um Portabilität als um Korrektheit Wenn Ihr JSON ein System passieren könnte, das UTF-8-Bytes verstümmelt - eine alte Protokollierungspipeline, einen falsch konfigurierten Proxy, einen Kanal, der ASCII annimmt - und jedes Zeichen über dem ASCII-Bereich in ein reines ASCII verwandelt \u Escape garantiert, dass es intakt überlebt Die Ausgabe ist sperriger und weniger für Menschen lesbar, also standardmäßig aus, aber der & quot; Escape Unicode" Kippschalter ist für den Moment da, in dem Sie einen kugelsicheren Transport benötigen Ein Codepunkt wie é wird \u00e9, und ein JSON-Parser rekonstruiert auf dem Weg nach draußen das Originalzeichen.
Wie funktioniert das Entfliehen und wann brauche ich es?
Entweichen ist das genaue Gegenteil: Es geht durch eine entgangene Zeichenfolge und verwandelt jede Backslash-Sequenz wieder in das rohe Zeichen, das sie darstellt. \n Echte Newline wird, wird \t Tab wird, \" Doppelzitat wird, und \uXXXX Zeichen an jenem Codepunkt wird, Sie brauchen es immer dann, wenn Sie auf der Empfängerseite sind - Sie haben einen Zeichenfolgenwert direkt aus einer JSON-Datei, einer Protokollzeile oder einer API-Antwort kopiert, und Sie möchten den Originaltext ohne einen Bildschirm voller Backslashes im Weg lesen.
Ein guter Unescaper macht zwei Dinge, die ein naives Finden und Ersetzen nicht tut. Erstens wird ein einzelnes Paar umgebender Doppelzitate entfernt, wenn der gesamte Wert angegeben wird, sodass Sie einfügen können "line one\nline two" Direkt aus einem JSON-Dokument und sauberen Text zurückbekommen Zweitens, es Validiert Wie es so schön heißt: eine ungültige Escape-Sequenz wie \x, oder ein verirrter Backslash ganz am Ende der Zeichenfolge, ist ein echter Fehler, und die JSON-Flucht / Unentkommen Werkzeug meldet seine Position, anstatt zu raten und eine lautlos falsche Ausgabe zu erzeugen Erhalten eines klaren & quot; ungültigen Escape an Position 14" schlägt, Text zu bekommen, der fast richtig aussieht, aber subtil beschädigt ist.
Die Schlüsseleigenschaft, der man vertrauen kann, ist, dass Flucht und Entfliehen exakte Umkehrungen sind Entfliehen Sie jedem Text und entweichen Sie dann dem Ergebnis und Sie erhalten genau das zurück, womit Sie begonnen haben, Charakter für Charakter Diese Rundreise-Garantie macht es sicher, das Werkzeug als Routineschritt in einer Pipeline und nicht als riskante Transformation zu verwenden, die Sie von Hand noch einmal überprüfen müssen.
Escape versus verwandte String-Operationen
JSON Escaping gehört zu einer Familie von " Machen Sie diesen Text für diesen Kontext sicher. & quot; transformiert sich und hilft, sie gerade zu halten. So wird es im Vergleich zu den Nachbarn, mit denen Entwickler es am häufigsten verwechseln, dargestellt.
| Operation | Schützt vor | Beispiel | Werkzeug |
|---|---|---|---|
| JSON Flucht | Brechen einer JSON-Zeichenfolge mit Anführungszeichen, Backslashes oder Kontrollzeichen | he said "hi" → he said \"hi\" |
JSON-Flucht / Unentkommen |
| HTML-Entitätskodierung | HTML brechen oder XSS aktivieren mit <, >, & |
<b> → <b> |
HTML-Entitäten |
| URL-Prozentcode | Brechen einer URL mit Leerzeichen oder reservierten Zeichen | a b → a%20b |
- |
| JSON-Format/Validierung | Strukturfehler im gesamten Dokument | Minifiziert → hübsch bedruckt | JSON-Formater |
| JSON → YAML | Verschieben einer Konfiguration zwischen Serialisierungsformaten | {"a":1} → a: 1 |
json zu Yaml |
Das zu beachtende Muster ist, dass jede Flucht ein Ziel hat verschieden Container. HTML-Entitäten verhindern, dass Text HTML kaputt macht; Prozentkodierung verhindert, dass eine URL beschädigt wird; JSON-Escaping verhindert, dass eine JSON-Zeichenfolge unterbrochen wird. Wenn Sie die falsche Zeichenfolge verwenden - HTML-Kodierung etwas, das JSON-Escaping erfordert - bleibt das eigentliche Problem ungelöst und fügt eine neue Rauschebene hinzu. Da dies alles auf Text läuft, den Sie möglicherweise nicht an einen Server eines Drittanbieters übergeben möchten, behalte ich jedes dieser Tools auf der Clientseite, was das Argument ist, das ich in der vollständigen Fassung vorgebracht habe Datenschutzleitfaden für Online-Toolsdrohen
Was sind die häufigen Fehler beim Einbetten von Text in JSON?
Der häufigste Fehler ist der, der mich einen Nachmittag gekostet hat: Mehrzeiliger Text mit nicht entweichenden Zitaten direkt in ein JSON-Feld einfügen und davon ausgehen, dass, weil beide Teile gültig sind, das Ganze gültig ist Es ist nicht - der Container hat Regeln, denen der Inhalt gehorchen muss.
Eine knappe Sekunde ist Doppelflügler. Wenn eine Schnur bereits einmal entkommen wurde und Sie ihr wieder entkommen, wird jede \n wird \\n Und Ihre Zeilenumbrüche verwandeln sich in einen wörtlichen Backslash-n, den kein Parser zurückkonvertiert Dies geschieht normalerweise, wenn ein Wert zwei Systeme durchläuft, die ihm jeweils hilfreich entkommen Wenn Ihre Ausgabe verdächtige Ausläufe von \\ Wo Sie einzelne Rückschläge erwartet haben, haben Sie wahrscheinlich doppelt geflohen, und einmal zu entkommen wird es beheben Die dritte Falle ist das Vergessen, dass ein Windows-Pfad wie C:\Users\me voller Backslashes ist, die jeweils werden müssen \\ - ein unausgeflüchteter Pfad in JSON ist eine klassische Quelle für & quot; warum ist mein JSON ungültig" Verwirrung.
Der Fix für alle drei ist derselbe: Lassen Sie das Tool das Escaping genau einmal durchführen, an der Grenze, an der Rohtext auf JSON trifft, und lesen Sie die Zeichenanzahl-Zusammenfassung, die es der Vernunft zeigt - überprüfen Sie, ob sich etwas geändert hat Wenn Sie eine Handüberprüfung durchführen müssen, entkommen Sie mit & quot; in quotes" aktiviert und fügen Sie das Ergebnis in das ein JSON-Formater - wenn es als gültige Zeichenfolge analysiert wird, ist Ihr Escaping korrekt.
Ein funktionierendes Beispiel: Einbetten eines HTML-Schnipsels in JSON
Lassen Sie mich durch die genaue Situation gehen, die dies begonnen hat, denn die Transformation einmal zu sehen, macht die Regel hängen Angenommen, Sie möchten dieses Fragment als senden body Feld einer API-Anfrage:
<p>Hi "there",</p>
<p>Visit https://example.com/path</p>
Drei Dinge in diesem Text werden mit JSON kämpfen. Die beiden doppelten Zitate herum there Wird jeder versuchen, die Zeichenfolge zu beenden Die neue Zeile zwischen den Absätzen ist ein wörtliches Kontrollzeichen, das JSON innerhalb einer Zeichenfolge verbietet Und die </p> Sequenzen sind in einer einfachen JSON-Datei harmlos, aber gefährlich, wenn dieses JSON jemals in einem HTML-Code gedruckt wird <script> Tag. Fügen Sie das Fragment in die JSON-Flucht / Unentkommen Werkzeug, schalten Sie & quot; in Anführungszeichen ein, & quot; und Sie erhalten eine einzelne, gültige JSON-Zeichenfolge: die Anführungszeichen werden \"Die Newline wird \n& mit & quot; flucht vor slash" aktiviert werden die schließenden Tags werden <\/p>. Lassen Sie den gesamten angegebenen Wert direkt in Ihren body Feld und die Anfrage geht durch.
Genauso routiniert ist die Rückfahrt, wenn ein Teamkollege dir eine Log-Line mit einem JSON-geflüchteten schickt message Feld voll von \n und \"„Fügen Sie es in das Tool ein, wechseln Sie zu Unescape und lesen Sie den ursprünglichen mehrzeiligen Text mit weggefallenen Backslashes. Da es sich bei den beiden Vorgängen um exakte Inversen handelt, können Sie eine Nutzlast herausbewegen, um sie zu bearbeiten und wieder hineinzuziehen, ohne Angst vor Korruption haben zu müssen - die Zusammenfassung der Zeichenanzahl bestätigt, dass die Transformation ausgeführt wurde, und jede fehlerhafte Flucht wird mit ihrer Position gekennzeichnet, anstatt den Text stillschweigend zu verstümmeln. Diese Hin- und Rückfahrt-Sicherheit verwandelt das Entkommen aus einem nervösen manuellen Schritt in etwas, das Sie in einen Arbeitsablauf überweisen und vergessen können.
Häufig gestellte Fragen
Was bedeutet es, einer Zeichenfolge für JSON zu entkommen? JSON-String-Werte können kein rohes Doppelzitat, keinen rohen Backslash oder rohe Steuerzeichen wie Zeilenumbrüche und Registerkarten enthalten. Escaping ersetzt jedes davon durch eine Backslash-Sequenz - & quot; wird zu ", eine neue Zeile wird zu \ n, eine Registerkarte wird zu \ t - sodass der Text in eine JSON-Zeichenfolge eingefügt werden kann, ohne die umgebende Struktur zu durchbrechen.
Wie unterscheidet sich das von einem JSON-Formater? Ein JSON-Formater druckt oder minimiert ein ganzes JSON-Dokument und validiert seine Struktur. Dieses Tool arbeitet eine Ebene tiefer am Inhalt einer einzelnen Zeichenfolge: Es macht beliebige Texte sicher, die in einen JSON-Wert eingebettet oder einen Escaped-Wert zurück in Rohtext dekodiert werden. Verwenden Sie den Formatierer für Dokumente und dieses Werkzeug für einzelne Zeichenfolgen.
Welche Charaktere werden entkommen? Das doppelte Zitat ("), der Backslash (\), Backspace (\b), Form Feed (\f), Newline (\n), Carriage Return (\r) und Tab (\t) werden immer maskiert, zusammen mit jedem anderen Steuerzeichen unter U+0020 als \uXXXX. Optional wird der Vorwärts-Schrägstrich zu / und jedes Nicht-ASCII-Zeichen wird zu \uXXXX.
Soll ich dem Vorwärtsschlitz entkommen? Es ist optional Die JSON-Spezifikation erlaubt sowohl / als auch /, also ist einfach / gültig. Der eine Ort / zählt ist innerhalb eines HTML
