Escape JSON

Czym jest escapowanie ciągów JSON?

Escapowanie ciągów JSON to proces zamiany znaków specjalnych wewnątrz łańcucha tekstowego na sekwencje ucieczki, które parsery JSON mogą odczytać bez naruszenia struktury dokumentu. Specyfikacja JSON (ECMA-404 / RFC 8259) wymaga, aby określone znaki wewnątrz wartości tekstowych były poprzedzone ukośnikiem odwrotnym. Bez prawidłowego escapowania dosłowny cudzysłów lub znak nowej linii wewnątrz ciągu zakończyłby go przedwcześnie i spowodował błąd parsowania.

Każdy ciąg JSON jest ograniczony podwójnymi cudzysłowami. Gdy sam ciąg zawiera cudzysłów, ukośnik odwrotny lub znak kontrolny (U+0000 do U+001F), znak musi być zastąpiony sekwencją ucieczki. Na przykład dosłowna nowa linia staje się \n, tabulacja staje się \t, a cudzysłów staje się \". Każdy punkt kodowy Unicode może być również reprezentowany jako \uXXXX, gdzie XXXX to czterocyfrowa wartość szesnastkowa.

De-escapowanie (operacja odwrotna) konwertuje sekwencje z ukośnikiem odwrotnym z powrotem do oryginalnych znaków. Stosuj je, gdy otrzymujesz ładunek JSON, w którym wartości łańcuchowe są podwójnie escapowane, lub gdy chcesz wyodrębnić surowy tekst z wpisu dziennika JSON do wyświetlenia w interfejsie lub terminalu. Potoki agregacji logów trafiają na to stale: gdy wiadomość zakodowana jako JSON jest przechowywana jako wartość ciągu wewnątrz innego dokumentu JSON, każdy ukośnik odwrotny w wewnętrznym ciągu pojawia się podwojony.

Dlaczego warto używać narzędzia JSON escape?

Ręczne dodawanie lub usuwanie ukośników odwrotnych jest żmudne i podatne na błędy, szczególnie przy pracy z tekstem wieloliniowym, ścieżkami plików lub osadzonymi fragmentami kodu. Dedykowane narzędzie wychwytuje przypadki brzegowe, które ręczna edycja pomija.

Przypadki użycia JSON escape

Opis sekwencji ucieczki JSON

Specyfikacja JSON definiuje dokładnie dwa wymagane znaki ucieczki (cudzysłów i ukośnik odwrotny) oraz sześć krótkich sekwencji dla typowych znaków kontrolnych. Wszystkie pozostałe znaki kontrolne (U+0000 do U+001F) muszą używać formy \uXXXX. Znaki powyżej U+FFFF (np. emoji) mogą być reprezentowane jako para zastępcza UTF-16: \uD83D\uDE00.

Escapowanie JSON a kodowanie JSON

Programiści czasem mylą escapowanie ciągu z kodowaniem całego dokumentu JSON.

Przykłady kodu

Każdy popularny język ma wbudowane funkcje do tego celu. Przykłady w JavaScript, Python, Go i jq:

// JSON.stringify escapes a value and wraps it in quotes
JSON.stringify('Line 1\nLine 2')       // → '"Line 1\\nLine 2"'

// To get just the inner escaped string (no surrounding quotes):
const escaped = JSON.stringify('She said "hello"').slice(1, -1)
// → 'She said \\"hello\\"'

// Parsing reverses the escaping
JSON.parse('"tabs\\tand\\nnewlines"')  // → 'tabs\tand\nnewlines'

// Handling Unicode: emoji in JSON
JSON.stringify('Price: 5\u20ac')       // → '"Price: 5\u20ac"' (raw euro sign)

import json

# json.dumps escapes and quotes a string
json.dumps('Line 1\nLine 2')           # → '"Line 1\\nLine 2"'

# Ensure ASCII: replace non-ASCII with \uXXXX sequences
json.dumps('Caf\u00e9', ensure_ascii=True)   # → '"Caf\\u00e9"'

# Keep UTF-8 characters as-is (default in Python 3)
json.dumps('Caf\u00e9', ensure_ascii=False)  # → '"Caf\u00e9"'

# Unescape by round-tripping through json.loads
json.loads('"She said \\"hello\\""')      # → 'She said "hello"'

package main

import (
	"encoding/json"
	"fmt"
)

func main() {
	// json.Marshal escapes a Go string for JSON
	raw := "Line 1\nLine 2\tindented"
	b, _ := json.Marshal(raw)
	fmt.Println(string(b))
	// → "Line 1\nLine 2\tindented"

	// Unescape with json.Unmarshal
	var out string
	json.Unmarshal([]byte(`"She said \"hello\""`), &out)
	fmt.Println(out)
	// → She said "hello"
}

# Escape a raw string into a JSON-safe value
echo 'Line 1
Line 2	with tab' | jq -Rs '.'
# → "Line 1\nLine 2\twith tab\n"

# Unescape a JSON string back to raw text
echo '"She said \"hello\""' | jq -r '.'
# → She said "hello"

Często zadawane pytania