O pedido pull tinha 240 linhas alteradas e EU tinha tocado exatamente dois valores Esse foi o momento em que EU levei a sério sobre a classificação de chaves JSON Um companheiro de equipe tinha executado um arquivo de configuração através de um formatador que reordenou suas chaves, EU tinha editado dois desses valores à mão, e o diff resultante era uma parede ilegível de vermelho e verde onde 238 das linhas eram chaves que tinham simplesmente se movido Meu revisor, compreensivelmente, pediu-me para refazê-lo As mudanças reais eram invisíveis dentro do ruído.
Eu executo [Toolz.dev] (/e também construo projetos Laravel e WordPress, o que significa que moro lá dentro package.json, composer.json, tsconfig.json, catálogos de tradução, e uma centena de outros arquivos JSON que se comprometem com o controle de versão Um arquivo JSON com ordem de chave imprevisível é um imposto pequeno e recorrente em cada um desses Classificar chaves em uma ordem alfabética estável é a correção, e é uma daquelas mudanças que parece cosmética até a primeira vez que salva você uma revisão de código desperdiçada Este guia cobre quando classificar chaves JSON, quando não o faz, e como fazê-lo sem quebrar nada.
tl;dr: Um classificador JSON reordena um object' s chaves em ordem alfabética e re-serializa o resultado A ordem das chaves não altera o que JSON significa, porque os objetos não são ordenados pelo padrão JSON, mas uma ordem consistente torna os arquivos legíveis e produz diffs de controle de versão limpos que mostram apenas valores alterados Classificar recursivamente para alcançar objetos aninhados, manter a ordem da matriz por padrão porque as matrizes são ordenadas e escolher saída ascendente ou descendente, bonita ou minificada A json classificador é executado inteiramente no seu navegador.
O que é um classificador JSON?
Um classificador JSON pega um objeto JSON e reorganiza suas chaves em ordem alfabética, em seguida, escreve o objeto de volta para fora Os valores são intocados Apenas a sequência em que as chaves aparecem muda, e isso é seguro porque RFC 8259 define um objeto como uma coleção não ordenada: as chaves de reordenação não podem alterar o que o documento significa Então {"name":"toolz","author":"Liton"} torna-se {"author":"Liton","name":"toolz"}. Por padrão, a classificação é recursiva, o que significa que as chaves dentro de cada objeto aninhado também são classificadas, até o nível mais profundo.
Essa é toda a operação, e sua simplicidade é o ponto Você não está transformando dados, validando um esquema, ou convertendo um formato Você está impondo uma ordem previsível em algo que tinha um arbitrário Todo outro benefício, legibilidade, comparabilidade, diffs limpos, flui a partir dessa única ordenação previsível.
A classificação de chaves muda o que significa meu JSON?
Não, e este é o fato que torna a classificação segura No padrão JSON, ECMA-404, um objeto é definido como uma coleção não ordenada de pares de nomes e valores A especificação é explícita de que a ordem desses pares não é significativa Qualquer analisador conforme lê {"a":1,"b":2} e {"b":2,"a":1} como exatamente os mesmos dados Quando o seu programa faz config.timeout ou data["name"], ele olha a chave pelo nome; nunca se importa onde no objeto essa chave foi escrita.
Há uma ressalva que vale a pena afirmar claramente, porque alguém sempre pergunta Um número minúsculo de sistemas abusam de objetos JSON como se fossem encomendados, contando com a ordem de inserção para exibição ou processamento Isso é um uso indevido do formato em vez de uma propriedade dele, mas se você estiver alimentando um sistema que você não controla, teste antes de cometer um arquivo classificado em um pipeline que você não pode inspecionar Para a esmagadora maioria do JSON do mundo real, arquivos de configuração, cargas úteis de API, arquivos de bloqueio, catálogos de tradução, chaves de classificação é uma mudança puramente de apresentação com efeito zero no significado.
As matrizes são o caso oposto, e a distinção importa Uma matriz JSON é ordenada por definição, e sua ordem frequentemente carrega significado: uma sequência de passos, uma lista classificada, um conjunto de coordenadas onde a posição um é longitude e a posição dois é latitude Reordenar uma matriz pode mudar silenciosamente o que os dados dizem É por isso que esta ferramenta preserva a ordem da matriz por padrão e só classifica matrizes quando você explicitamente pede, e mesmo assim apenas para matrizes cujos elementos são todas as strings ou todos os números.
Por que eu classificaria as chaves JSON?
O motivo do título é diffs limpos, e é aquele que mudou a forma como EU trabalho As ferramentas de controle de versão comparam arquivos linha por linha Quando dois arquivos que representam os mesmos dados escrevem suas chaves em ordens diferentes, o diff está cheio de chaves que se moveram em vez de valores que mudaram Adote uma regra de que todo arquivo JSON é escrito com chaves classificadas, e o problema desaparece: duas versões do arquivo diferem apenas onde um valor realmente difere, então um revisor vê a mudança real imediatamente É exatamente por isso que muitos linters e formatadores oferecem uma opção de chaves de classificação, e por que ferramentas como jq envie uma bandeira de chaves de classificação.
A segunda razão é a legibilidade humana Quando você está digitalizando um arquivo de configuração grande procurando uma configuração específica, a ordem alfabética diz onde procurar Você não lê o arquivo inteiro; você pula para aproximadamente onde a chave deve estar, da maneira que faria em um dicionário Em um arquivo com oitenta teclas, que é a diferença entre uma pesquisa de dois segundos e uma verificação completa.
A terceira razão é a comparabilidade entre arquivos Se o seu projeto tem dez arquivos JSON que devem todos compartilhar uma estrutura comum, classificá-los todos da mesma forma torna trivial para olho se um está faltando uma chave ou tem um extra Divergências alinhar ao lado um do outro em vez de se esconder em posições diferentes.
A quarta razão é a canonização Alguns fluxos de trabalho precisam de uma representação estável e determinística de um valor JSON, por exemplo, para hash, cache ou comparar duas cargas úteis para igualdade, independentemente de como foram serializadas Classificar chaves é um passo em direção a uma forma canônica, embora um JSON canônico completo também normalize o espaço em branco e a formatação de números.
Como faço para usar o Classificador JSON?
Cole seu JSON na caixa de entrada do json classificador, ou carregue a amostra para ver a forma da saída A entrada deve ser JSON válida Se não for, a ferramenta relata o erro de análise com sua posição para que você possa corrigir uma vírgula perdida ou um colchete não fechado antes de classificar.
Em seguida, escolha como o sort é executado Escolha ascendente, que é de A a Z, ou descendente para Z a A. Decida se deseja dobrar o case, que está ativado por padrão para que Name, name, e NAME sente-se juntos em vez de serem separados porque letras maiúsculas ordenam antes das minúsculas em ordem bruta de caracteres Escolha se deseja descer em objetos aninhados, o que você quase sempre deseja, ou classificar apenas o nível superior Se você quiser matrizes de strings ou números ordenados também, ligue a classificação de array; matrizes mistas e matrizes de objetos são sempre deixadas como estão.
Finalmente, escolha o seu estilo de saídaPretty-print com recuo de dois espaços, quatro espaços ou tabulação para um arquivo legível que você irá confirmar, ou minify para uma única linha para a menor carga útil para armazenamento ou transporte Execute o sort, em seguida, copie o resultado ou baixe-o A contagem de chaves informa quantas chaves foram reordenadas, o que é uma verificação rápida de sanidade que a ferramenta viu a estrutura que você esperava.
Ascendente, descendente, recursivo: quais configurações EU quero?
Na maioria das vezes os padrões são o que você quer: ascendente, recursivo, case-insensitive, bonito-impresso com dois espaços Isso produz o arquivo legível, diff-friendly que motiva a classificação em primeiro lugar As outras configurações existem para situações específicas, ea tabela abaixo é como EU decido.
| Configuração | Padrão | Quando mudar isso |
|---|---|---|
| Ordem | Ascendente (A a Z) | Descer é raro; útil quando você deseja as chaves mais recentes ou de maior prioridade, nomeadas para classificar por último, no topo |
| Recursivo | Em | Desligue apenas quando quiser reordenar seções de nível superior, mas preserve a ordem ajustada manualmente dentro de cada uma |
| Ignorar caso | Em | Desligue quando precisar de uma ordem estrita de ponto de código, por exemplo, para corresponder a outra ferramenta que classifica a caixa com sensibilidade |
| Classificar matrizes | Desligado | Ative matrizes que sejam conjuntos genuinamente não ordenados, como uma lista de tags ou valores permitidos |
| Impressão bonita | Em | Desligue para minificar para transporte ou armazenamento |
A única configuração de uso indevido de pessoas é a classificação de array. Ligue-o somente quando tiver certeza de que um array representa um conjunto não ordenado. Uma lista de tags, um conjunto de extensões de arquivo permitidas ou um conjunto de sinalizadores de recursos é segura para classificar. Uma lista de etapas do pipeline, uma tabela de rotas ou qualquer coisa onde a posição implique sequência não é. Quando em dúvida, deixe os arrays em paz, porque a ferramenta & #39; O padrão de preservar a ordem nunca pode corromper seus dados, ao mesmo tempo que classificar o array errado silenciosamente pode.
Como isso se encaixa com outras ferramentas JSON?
A classificação geralmente é uma etapa em uma pequena cadeia Quando o JSON chega minificado e ilegível a partir de uma API, EU o executo através do formatador json primeiro para recuá-lo e validá-lo, em seguida, classifique as chaves para torná-lo digitalizável Quando estou preparando uma carga útil para transporte após a classificação, o Minificador JSON retira-o para uma única linha e, como as chaves já estão classificadas, duas cargas úteis minificadas que representam os mesmos dados são idênticas byte por byte, o que é útil para cache e comparação.
Para trabalho estrutural em vez de apresentação, o Achatamento JSON transforma objetos aninhados em teclas pontilhadas e vice-versa, que combinam naturalmente com a classificação quando você está discutindo a configuração em variáveis de ambiente. E quando você precisa dos dados em outro formato inteiramente, o Conversor JSON para YAML é a próxima parada; classificar as chaves antes da conversão fornece um arquivo YAML com uma ordem de campo previsível e legível também. Se você quiser uma visão geral de como elas se encaixam, apresentei minha configuração completa no Guia do kit de ferramentas para desenvolvedores web, e a mecânica mais profunda de formatação ao vivo no Guia do formatador JSON.
Um exemplo real: domesticar um pacote.json diff
Deixe-me passar pela situação exata que iniciou este artigo, porque mostra por que as escolhas de cenário são importantes. Eu tive um package.json onde o dependencies block tinha sido escrito em ordem de instalação, aproximadamente a ordem em que os pacotes tinham sido adicionados ao longo de dois anos Um novo membro da equipe correu seu editor & #39; s format-on-save, que classificou as chaves de dependência, e comprometeu-o ao lado de uma mudança genuína: batendo um pacote da versão 4 para a versão 5.
O diff foi um desastre Toda dependência abaixo da batida parecia ter se movido, porque a classificação havia mudado suas posições, então o revisor viu trinta linhas alteradas para o que era uma atualização de uma linha A correção não era discutir sobre qual editor estava certo A correção era classificar o arquivo uma vez, cometer esse tipo como sua própria mudança separada com uma mensagem como & quot; classificar o pacote.json keys, & quot; e então fazer a versão saltar em cima da ordem agora estável Depois disso, cada mudança de dependência futura produziu um diff limpo de uma ou duas linhas, porque o arquivo já estava na ordem em que todas as ferramentas do & #39; queriam colocá-lo.
Esse é o padrão que EU sigo agora para qualquer JSON que viva no controle de versão Classifique uma vez em um commit dedicado, então mantenha-o classificado O json classificador com seus padrões, ascendente e recursivo, produz exatamente a ordem que Prettier' s sort option e jq --sort-keys produce, então o arquivo permanece estável, não importa qual ferramenta um companheiro de equipe execute. A única coisa que verifico primeiro são arrays: package.json não tem arrays significativos com os quais se preocupar, mas um arquivo com uma matriz ordenada como uma lista de etapas de construção precisa de classificação de array deixada de lado, que é o padrão, para que a sequência sobreviva.
Quais ferramentas e formatos classificam as chaves JSON?
Classificar chaves JSON é uma necessidade comum o suficiente para que apareça em todo o ecossistema, o que é um bom sinal de que a prática é sólida, em vez de uma peculiaridade pessoal. O processador da linha de comando jq tem um --sort-keys bandeira, muitas vezes escrita -S, que classifica as chaves de cada objeto em sua saída O formatador de código Prettier pode classificar chaves em JSON através de sua configuração Muitos linters oferecem uma regra de sort-keys que sinaliza objetos não classificados no código-fonte Bibliotecas padrão de linguagem expõem a mesma capacidade, por exemplo Python' s json.dumps aceita a sort_keys=True argumento que produz saída canônica e classificada.
O que um classificador baseado em navegador adiciona é o caso rápido e sem configuração Quando você tem um blob de JSON de uma resposta de API, uma linha de log ou uma mensagem Slack, e você só quer lê-lo em uma ordem sã agora, abrir uma página e colar é mais rápido do que conectar um formatador ou cair em um shell É a mesma razão pela qual um formatador de colar e ir existe ao lado de plugins de editor: a ferramenta atende à necessidade ad-hoc que o pipeline configurado não cobre.
Meu JSON é privado?
Sim. O JSON é analisado, classificado e re-serializado inteiramente em seu navegador usando JavaScript Nada é carregado em um servidor, registrado ou armazenado em qualquer lugar Isso não é um detalhe menor para JSON especificamente, porque JSON é onde os segredos vivem: respostas API carregando tokens, arquivos de configuração com cadeias de conexão, cargas contendo registros de clientes Colar qualquer um desses em uma ferramenta que envia para um servidor é um risco real, e é exatamente o risco que esta ferramenta é construída para evitar.
Você pode verificar a reivindicação da mesma forma que EU faria Abrir a guia de rede em seu navegador' s ferramentas de desenvolvedor e assisti-lo enquanto você classificar; nenhum pedido sai da página Ou desconectar da internet e continuar a classificação, porque uma vez que a página carregada, a ferramenta funciona sem conexão em tudo O processamento do lado do cliente é o padrão para tudo o que EU construir, e se você se preocupa com o argumento mais amplo para ele, o Guia de privacidade de dados faz o caso na íntegra.
Perguntas frequentes
O que significa classificar as chaves JSON?
A ordenação das chaves JSON reordena os pares nome-valor de um objecto por ordem alfabética sem alterar quaisquer valores O objecto {"name": " toolz", " author": " Liton"} torna-se {" author": " Liton", "name": " toolz"}. Apenas a ordem das chaves muda, pelo que os dados que o documento representa permanecem exactamente iguais.
A classificação de chaves muda o que significa meu JSON?
não . No padrão JSON, ECMA-404, um objeto é um conjunto não ordenado de pares de valor-nome, portanto, reordenar suas chaves não altera seu significado. Qualquer analisador em conformidade lê as versões ordenadas e não classificadas como os mesmos dados. A ordem importa apenas para a legibilidade humana e para a produção de diferenças estáveis.
Os objetos aninhados também são classificados?
Sim, por padrão. A classificação recursiva está ativada, portanto, as chaves de cada objeto dentro do documento são classificadas em todos os níveis de aninhamento. Você pode desativar a recursão para classificar apenas as teclas de nível superior e deixar objetos aninhados em sua ordem original.
O classificador reordena as matrizes?
Não por padrão. As matrizes são ordenadas por definição, e reordená-las pode alterar o significado, portanto, a ferramenta preserva a ordem do array. Existe uma opção para classificar arrays cujos elementos são todos os strings ou todos os números quando você deseja que eles sejam ordenados; arrays que misturam tipos ou objetos contêm sempre como estão.
Por que eu classificaria as chaves JSON?
O motivo mais comum é o Difs estável: quando cada arquivo escreve suas chaves na mesma ordem alfabética, os diffs de controle de versão destacam apenas os valores que mudaram em vez de as chaves que se moveram. A classificação também torna os arquivos de configuração grandes e as respostas da API muito mais fáceis de digitalizar e comparar por olho.
Como funciona a classificação insensível a maiúsculas e minúsculas?
Com a classificação insensível a maiúsculas e minúsculas, as chaves são comparadas como se fossem minúsculas, portanto, nome, nome e nome são agrupados próximos um do outro em vez de serem separadas porque letras maiúsculas classificam antes das minúsculas na ordem de caractere bruto. Desligue-o para classificar estritamente por ponto de código do personagem.
Posso minimizar o JSON classificado?
Sim. Escolha Saída Minificada para obter o JSON classificado em uma única linha sem espaço em branco extra, que é a forma mais pequena de armazenamento ou transporte. Para um arquivo legível, escolha uma saída bonita com recuo de dois espaços, quatro espaços ou tabulação.
Meu JSON foi carregado em algum lugar?
não . O JSON é analisado e classificado por JavaScript em seu navegador e nunca é transmitido, registrado ou armazenado. Você pode verificar isso observando a guia da rede durante a classificação ou offline, a ferramenta continua funcionando sem conexão.
Escrito por Liton, construtor de [Toolz.dev] (/. Eu construo ferramentas de desenvolvedor baseadas em navegador e escrevo sobre como trabalhar com JSON, Laravel e a web.
