O bug que me fez construir esta ferramenta foi enlouquecedoramente pequeno Eu estava enchendo um modelo de e-mail HTML - algumas centenas de linhas com aspas, quebras de linha e a barra invertida ímpar - em um campo JSON para enviar para uma API, e a solicitação continuou voltando como um 400 O modelo estava bem O JSON estava bem por conta própria Mas no momento em que os dois se encontraram, uma citação dupla não escapada trezentos caracteres em silenciosamente fechou a string cedo, e tudo depois que ela se transformou em lixo o analisador não podia fazer sentido Eu tinha colado texto válido em um recipiente válido e produziu um documento inválido.
Esse é todo o problema que JSON escapa resolve, e vale a pena entender em vez de trabalhar em torno Este guia cobre o que escapar realmente faz, quais personagens devem ser escapados e por quê, como o desescape o inverte e como usar o livre json escape/unescape ferramenta para mover texto arbitrário dentro e fora de strings JSON sem uma única falha silenciosa Ele fica ao lado dos outros utilitários de dados sobre os quais escrevi no Guia definitivo para ferramentas JSON.
tl;dr: Uma string JSON não pode conter uma aspa dupla bruta, uma barra invertida bruta ou caracteres de controle brutos, como linhas novas e guias Escaping substitui cada um por uma sequência de barra invertida -
"torna-se\", uma nova linha se torna\n, uma aba se torna\t, e qualquer outra coisa abaixo de U+0020 se torna\uXXXX. Unescaping transforma essas sequências novamente nos personagens originais. O json escape/unescape ferramenta faz ambos em seu navegador, com opções para envolver o resultado em aspas, escapar não-ASCII como\uXXXX, ou escapar da barra para a frente.
O que significa escapar de uma string para JSON?
JSON tem uma gramática precisa e publicada - é definida por RFC 8259 e pelo padrão ECMA-404 - e as regras para o que pode aparecer dentro de uma string são rígidas Uma string JSON é uma série de caracteres envoltos em aspas duplas Porque a aspa dupla marca o início e o fim da string, uma aspa dupla interior o texto terminaria prematuramente Como a barra invertida inicia uma sequência de escape, uma barra invertida bruta seria mal interpretada como o início de uma. E como as strings JSON devem ser uma única linha lógica de texto, caracteres de controle literais - novas linhas, guias, retornos de carro - não podem permanecer dentro delas sem escapar.
Escapar é o processo de substituir cada um desses personagens problemáticos por uma sequência de barra invertida de dois caracteres que JSON entende Uma citação dupla se torna \". Uma barra invertida se torna \\. Uma nova linha se torna \n. O resultado é um texto que ar um pouco mais feio, mas agora é seguro cair entre duas aspas sem quebrar o documento circundante O significado é idêntico - uma leitura do analisador JSON \n produz novamente uma nova linha real - mas a representação agora é legal.
Isso é fundamentalmente diferente de formatar um documento JSON Um formatador organiza a estrutura de um objeto inteiro: indentação, ordenação de chaves, espaço em branco entre elementos Escaping opera um nível abaixo, no conteúdo de um único valor de string. Você alcança o formatador json quando você tiver um documento completo para imprimir ou validar, e para o json escape/unescape ferramenta quando você tem um pedaço de texto bruto que você precisa para caber dentro de um campo.
Quais personagens realmente precisam escapar?
A especificação JSON é refrescantemente específica aqui Dentro de uma string, exatamente dois caracteres ser necessário sempre escape, além de toda a gama de caracteres de controle.
As duas fugas obrigatórias de um único caractere são aspas duplas (\") e a barra invertida (\\).Além desses, JSON define escapes curtos para cinco caracteres de controle comuns: backspace (backspace)\b), formar ração (\f), nova linha (\n), retorno do transporte (\r) e aba horizontal (\t). Qualquer outro o caractere de controle - qualquer coisa com um ponto de código abaixo de U+0020 que não tenha um formato curto - deve ser escrito como um \u escape seguido por quatro dígitos hexadecimais, então um byte nulo se torna \u0000 e o separador de unidades e quot do & quot; torna-se \u001F.
Mais dois personagens são opcional para escapar, e é aqui que a confusão se arrasta. A barra direta pode ser escrita como \/, mas não precisa ser - uma planície / é JSON perfeitamente válido. E qualquer caractere acima do intervalo ASCII, como um acentuado é ou um emoji, pode ser escrito literalmente em um documento UTF-8 ou escapado como \uXXXX; ambos são legais. O json escape/unescape tool sempre lida com as fugas obrigatórias e oferece alternâncias para as duas opcionais para que você possa combinar o que seu sistema de destino espera.
Devo escapar da barra dianteira e dos caracteres não ASCII?
Essas duas fugas opcionais existem por motivos reais, mesmo que você raramente precise delas.
O escape de barra direta é importante em exatamente uma situação comum: quando JSON está incorporado em um HTML <script> tag. O analisador HTML browser' s procura a sequência literal </ para encontrar o final de um bloco de script, portanto, uma string contendo </script> no seu JSON pode fechar prematuramente a tag e quebrar a página Escrevendo a barra como <\/script> - ainda válido JSON, ainda a mesma string uma vez analisada - evita isso Fora dos scripts inline, você pode deixar barras em paz, e é por isso que a ferramenta deixa a barra de avanço sem escape por padrão.
Escapando de caracteres não ASCII como \uXXXX trata-se de portabilidade e não de correção. Se o seu JSON puder passar por um sistema que manipula bytes UTF-8 - um pipeline de registro antigo, um proxy mal configurado, um canal que assume ASCII - transformando cada caractere acima do intervalo ASCII em um ASCII puro \u escape garante que sobrevive intacta A saída é mais volumosa e menos legível por humanos, por isso está desligada por omissão, mas o & quot; Escape Unicode" toggle está lá no momento em que você precisa de transporte à prova de balas Um ponto de código como é torna-se \u00e9, e um analisador JSON reconstrói o personagem original na saída.
Como funciona a desescapagem e quando preciso dela?
Desescapar é o inverso exato: ele caminha através de uma string escapada e transforma cada sequência de barra invertida de volta no caractere bruto que representa. \n torna-se uma verdadeira nova linha, \t torna-se uma aba, \" torna-se uma citação dupla e \uXXXX torna-se o caractere nesse ponto de código Você precisa dele sempre que estiver na extremidade receptora - você copiou um valor de string diretamente de um arquivo JSON, uma linha de log ou uma resposta de API e deseja ler o texto original sem uma tela cheia de barras invertidas no caminho.
Um bom unescaper faz duas coisas que um ingênuo find-and-replace não faz Primeiro, ele retira um único par de aspas duplas circundantes se todo o valor for citado, para que você possa colar "line one\nline two" direto de um documento JSON e obtenha o texto limpo de volta Segundo, ele valida como vai: uma sequência de escape inválida como \x, ou uma barra invertida perdida bem no final da string, é um erro real, e o json escape/unescape a Ferramenta reporta a sua posição em vez de adivinhar e produzir uma saída silenciosamente errada Obtendo um & quot claro; escape inválido na posição 14 & quot; bate em obter texto que parece quase certo, mas é sutilmente corrompido.
A propriedade chave para confiar é que escapar e desescapar são inversos exatos Escape qualquer texto e, em seguida, desescape o resultado e você recebe de volta precisamente com o que você começou, personagem para personagem Essa garantia de ida e volta é o que torna seguro usar a ferramenta como uma etapa de rotina em um pipeline, em vez de uma transformação arriscada que você tem que verificar duas vezes à mão.
Escapagem versus operações de string relacionadas
O escape JSON faz parte de uma família de & quot; torne este texto seguro para esse contexto e quot; transforma e ajuda a mantê-los corretos. Veja como ele se compara aos vizinhos com os quais os desenvolvedores mais frequentemente o confundem.
| Operação | Protege contra | exemplo | ferramenta |
|---|---|---|---|
| JSON escapar | Quebrando uma string JSON com aspas, barras invertidas ou caracteres de controle | he said "hi" → he said \"hi\" |
json escape/unescape |
| Codificação de entidade HTML | Quebrando HTML ou habilitando XSS com <, >, & |
<b> → <b> |
entidades html |
| URL por cento-codificar | Quebrando uma URL com espaços ou caracteres reservados | a b → a%20b |
- |
| Formato/validar JSON | Erros estruturais em todo um documento | minificado → bastante impresso | formatador json |
| JSON → YAML | Movendo uma configuração entre formatos de serialização | {"a":1} → a: 1 |
json para yaml |
O padrão a ser notado é que cada fuga tem como alvo a diferente contêiner. Entidades HTML evitam que o texto quebre HTML; a codificação percentual evita que ele quebre uma URL; O escape JSON evita que ele quebre uma string JSON. Usar a string errada - codificar HTML algo que precisa de escape JSON - deixa o problema real sem solução e adiciona uma nova camada de ruído. Como tudo isso é executado em texto que você pode não querer entregar a um servidor de terceiros, mantenho cada uma dessas ferramentas do lado do cliente, que é o argumento que apresentei na íntegra no guia de privacidade de dados para ferramentas online.
Quais são os erros comuns ao incorporar texto no JSON?
O único erro mais comum é aquele que me custou uma tarde: colar texto de várias linhas com aspas não escapadas diretamente em um campo JSON e assumir que, como ambas as partes são válidas, o todo é válido Não é - o contêiner tem regras que o conteúdo deve obedecer.
Um segundo próximo é fuga dupla. Se uma string já escapou uma vez e você escapou dela novamente, cada \n torna-se \\n e suas novas linhas se transformam em uma barra invertida literal-n que nenhum analisador irá converter de volta Isso geralmente acontece quando um valor passa por dois sistemas que cada um escapar útil Se a sua saída tem corridas suspeitas de \\ onde você esperava barra invertida única, você provavelmente escapou duas vezes, e desescapar uma vez irá corrigi-lo A terceira armadilha é esquecer que um caminho do Windows como C:\Users\me está cheio de barras invertidas, cada uma das quais deve se tornar \\ - um caminho não escapado no JSON é uma fonte clássica do & quot; por que meu JSON invalid" confusão.
A correcção para todos os três é a mesma: deixe a ferramenta fazer o escape exactamente uma vez, no limite onde o texto bruto encontra JSON, e leia o resumo da contagem de caracteres que mostra para verificar a sanidade que algo mudou Quando precisar de verificar manualmente, escape com o & quot; envolva entre aspas & quot; activado e cole o resultado no formatador json - se for analisado como uma string válida, seu escape estará correto.
Um exemplo trabalhado: incorporar um snippet HTML em JSON
Deixe-me caminhar sobre a situação exata que começou isso, porque ver a transformação uma vez faz a regra ficar Diga que você quer enviar este fragmento como o body campo de uma solicitação de API:
<p>Hi "there",</p>
<p>Visit https://example.com/path</p>
Três coisas nesse texto vão lutar com JSON As duas citações duplas ao redor there cada um tentará terminar a string A nova linha entre os parágrafos é um caractere de controle literal que JSON proíbe dentro de uma string. E o </p> as sequências são inofensivas em um arquivo JSON simples, mas perigosas se este JSON for impresso dentro de um HTML <script> tag. Cole o fragmento no json escape/unescape ferramenta, ligue o & quot; envolva entre aspas, & quot; e você obtém uma única string JSON válida: as aspas se tornam \", a nova linha se torna \n& quot; escape para frente slash" habilitado as tags de fechamento se tornam <\/p>. Coloque todo o valor cotado diretamente no seu body campo e a solicitação passa.
A viagem reversa é igualmente rotineira. Quando um companheiro de equipe envia uma linha de registro com um JSON-escapado message campo cheio de \n e \", cole-o na ferramenta, mude para Desescapar e leia o texto original de várias linhas com as barras invertidas desaparecidas Como as duas operações são inversas exatas, você pode mover uma carga útil para editá-la e voltar sem medo de corrupção - o resumo da contagem de caracteres confirma a transformação executada, e qualquer fuga malformada é sinalizada com sua posição em vez de mutilar silenciosamente o texto Essa segurança de ida e volta é o que transforma escapar de um passo manual nervoso em algo que você pode conectar a um fluxo de trabalho e esquecer.
Perguntas frequentes
O que significa escapar de uma string para JSON? Os valores das cadeias de caracteres JSON não podem conter uma aspas duplas em bruto, uma barra invertida em bruto ou caracteres de controlo em bruto como as linhas novas e as guias O escaping substitui cada uma destas por uma sequência de barra invertida - o & quot; torna-se o & quot;, uma linha nova torna-se o \ n, uma guia torna-se o \ t - pelo que o texto pode ser colocado dentro de uma cadeia JSON sem quebrar a estrutura circundante.
Como isso é diferente de um formatador JSON? Um formatador JSON imprime ou minimiza um documento JSON inteiro e valida sua estrutura. Essa ferramenta trabalha um nível abaixo, no conteúdo de uma única string: torna o texto arbitrário seguro para incorporar dentro de um valor JSON ou decodifica um valor de escape para o texto bruto. Use o formatador para documentos e esta ferramenta para strings individuais.
Quais personagens são escapados? A aspa dupla ("), a barra invertida (\), o backspace (\b), o feed de formulário (\f), a linha nova (\n), o retorno do carro (\r) e a aba (\t) sempre escapam, junto com qualquer outro caractere de controle abaixo de U+0020 como \uXXXX. Opcionalmente, a barra direta se torna /e todo caractere não ASCII se torna \uXXXX.
Devo escapar do barramento para a frente? É opcional A especificação JSON permite tanto / quanto /, então simples / é válido O único lugar / importa está dentro de um HTML
