Melhores práticas de formatação JSON: legível, válido e eficiente
Resposta rápida
Use recuo de 2 espaços para JSON legível por humanos, sem vírgulas finais, chaves entre aspas duplas e ordem de chaves consistente (em ordem alfabética ou com significado de domínio). Minifique JSON para transporte de produção e impressão bonita para desenvolvimento. Use nosso formatador JSON gratuito para alternar entre os dois instantaneamente.
Introdução
As opções de formatação JSON afetam a legibilidade, o tamanho do arquivo e a velocidade de depuração. Embora a sintaxe JSON seja estritamente definida pela RFC 8259, como você recua, ordena chaves e lida com espaços em branco é uma questão de convenção. Este guia explica as práticas recomendadas amplamente adotadas para que seu JSON seja consistente entre as equipes, fácil de depurar e eficiente durante a transmissão.
Passo a passo
-
Escolha uma largura de recuo
2 espaços é a convenção mais comum (Prettier, ESLint, Google JSON Style Guide). 4 espaços são aceitáveis para configurações profundamente aninhadas. As guias não são recomendadas porque a renderização varia entre os editores. Escolha um e aplique-o em todo o projeto.
-
Ordene as chaves de forma consistente
Classifique as chaves em ordem alfabética para obter saída determinística (útil para armazenamento em cache e diferenças) ou agrupe por significado de domínio (id primeiro, depois atributos e depois relacionamentos). Evite a ordem aleatória das chaves - isso torna as diferenças barulhentas e interrompe os testes de instantâneo.
-
Minificar para transporte de produção
JSON minimizado remove todos os espaços em branco não essenciais, reduzindo o tamanho da carga útil em 10 a 0%. Sirva JSON minificado de APIs em produção e mantenha JSON bem impresso apenas para desenvolvimento local e depuração.
-
Valide antes de enviar
Sempre execute JSON através de um validador antes de enviar para um API ou gravar em um arquivo de configuração. Uma única vírgula final ou chave sem aspas fará com que JSON.parse() jogue e quebre o consumidor.
-
Use um formatador para alternar modos
Cole seu JSON no formatador JSON para embelezar para leitura ou reduzir para transporte. A ferramenta valida a sintaxe e relata a localização exata de qualquer erro, economizando tempo de depuração.
Exemplos
Bem impresso (recuo de 2 espaços)
Entrada: {"id":1,"name":"Alice","active":true}
Saída: {
"id": 1,
"name": "Alice",
"active": true
}
Minimizado para produção
Entrada: {
"id": 1,
"name": "Alice"
}
Saída: {"id":1,"name":"Alice"}
Chaves ordenadas alfabeticamente
Entrada: {"zebra":1,"apple":2,"mango":3}
Saída: {"apple":2,"mango":3,"zebra":1}
Problemas comuns
- Vírgulas finais: {"a":1,} é inválido JSON. A maioria dos formatadores os remove, mas analisadores estritos como JSON.parse() rejeitarão a entrada.
- Aspas simples e chaves sem aspas: {'a':1} e {a:1} são JavaScript válidos, mas JSON inválido. Sempre use aspas duplas para chaves e valores de string.
- Comentários em JSON: o padrão JSON não permite comentários // ou /* */. Use JSONC, JSON5 ou um arquivo de esquema separado se precisar de documentação embutida.
- Recuo misto: misturar tabulações e espaços quebra as ferramentas de comparação e pode causar erros de lint de "recuo inconsistente". Normalize com um formatador antes de confirmar.
Dicas
- Configure seu editor para formatar JSON ao salvar com recuo de 2 espaços — isso evita debates de estilo na revisão de código.
- Para respostas API, defina Content-Type: application/json; charset=utf-8 e servir JSON minificado com compactação gzip/Brotli para máxima eficiência.
- Use ordenação de chaves determinísticas (por exemplo, alfabética) quando JSON é hash ou comparado em testes de instantâneo – a ordem aleatória causa falhas falso-positivas.
- Ao depurar uma carga útil JSON grande, imprima-a primeiro e, em seguida, use regex ou jq para extrair a subárvore relevante em vez de digitalizá-la a olho nu.