A tarefa que me ensinou a respeitar o achatamento parecia aborrecida no bilhete: o & quot; exportar o objecto de definições para uma folha de cálculo para que o cliente o possa editar." As configurações eram um blob JSON profundamente aninhado a partir de uma configuração Laravel, com três e quatro níveis de profundidade em alguns lugares, com matrizes de sinalizadores de características misturados em Uma folha de cálculo tem colunas, não árvores Eu precisava de cada valor folha como uma única chave plana que o cliente podia ver em uma linha, editar e voltar à mão, e depois precisava reconstruir a estrutura aninhada exata a partir de suas edições sem perder um único índice de matriz Essa viagem de ida e volta, aninhada para plana e plana de volta para aninhada, é o que um flattener JSON faz, e obtê-lo sem perdas é todo o jogo The Toolz Achatamento JSON é a ferramenta que construí para esse trabalho, e este guia explica como funciona e onde salva você.
tl;dr: Um flattener JSON converte um objeto aninhado em um objeto de nível único cujas chaves são o caminho para cada valor
{"user":{"city":"Austin"}}torna-se{"user.city":"Austin"}. Matrizes achatadas com seu índice no caminho (roles.0). Unflatten inverte-lo, reconstruindo os objetos aninhados e matrizes a partir dessas teclas pontilhadas A ferramenta Toolz faz ambas as direções sem perdas, preserva objetos vazios e matrizes, suporta ponto ou bracket array notação e um delimitador personalizado, e executa inteiramente cliente-lado sem upload e sem inscrição.
Eu construo SaaS no Laravel e React e envio plugins WordPress, então o aninhado JSON está em toda parte nos meus dias: arquivos de configuração, cargas úteis de API, catálogos de mensagens i18 n, armazenamentos de bandeira de recursos Os sistemas que consomem essas cargas úteis, no entanto, freqüentemente querem teclas planas O achatamento é o adaptador entre uma forma que é natural para dados estruturados e uma forma que é natural para planilhas, variáveis de ambiente e armazenamentos de chaves pontilhadas É uma pequena operação que desbloqueia silenciosamente muitas tarefas que de outra forma seriam irritantes.
O que é um flattener JSON?
Um flattener JSON converte um objeto JSON aninhado em um objeto de nível único onde cada chave é o caminho completo da raiz para um valor folha A sintaxe do caminho também não é arbitrária: RFC 6901 define JSON Pointer, a maneira padrão de endereçar um valor dentro de um documento O aninhado {"user":{"name":"Ada","address":{"city":"Austin"}}} torna-se o apartamento {"user.name":"Ada","user.address.city":"Austin"}. Nada sobre os valores muda; apenas seu endereçamento faz Cada folha, por mais profunda que seja, recebe uma chave que explica como alcançá-la.
As matrizes são tratadas da mesma maneira, com o índice da matriz se tornando um segmento de caminho: {"roles":["admin","editor"]} achata para {"roles.0":"admin","roles.1":"editor"}. O índice na chave é o que permite que a operação reversa reconstrua a matriz na ordem correta Essa operação reversa, não achatada, pega um objeto plano de chaves pontilhadas e reconstrói os objetos e matrizes aninhados, decidindo em cada etapa se um segmento de caminho nomeia uma propriedade de objeto ou um índice de matriz Quando achatados e não achatados usam o mesmo delimitador e notação de matriz, eles são inversos exatos, e que a viagem de ida e volta sem perdas é a propriedade que torna a ferramenta confiável para o trabalho real, em vez de uma conveniência unidirecional.
Por que eu achataria JSON em primeiro lugar?
Porque muitos sistemas falam apenas pares chave-valor planos, e um caminho pontilhado é a maneira padrão de transportar a estrutura aninhada através deles sem perdê-la O exemplo mais claro é uma planilha Uma planilha é uma grade de colunas, e não há coluna para o & quot; a cidade dentro do endereço dentro do usuário." Apague o objeto e user.address.city torna-se um cabeçalho de coluna única sob o qual o valor pode viver, que é exatamente o que meu ticket de exportação de configurações precisava.
A mesma forma aparece em muitos outros lugares Variáveis de ambiente e .env os arquivos são planos, e as ferramentas que mapeiam a configuração para eles usam caminhos pontilhados ou sublinhados As bibliotecas de internacionalização teclam suas strings com caminhos pontilhados como checkout.button.label. Plataformas de bandeira de recursos, esquemas de eventos analíticos e muitos pipelines de registro desejam um nível de chaves, geralmente para que possam indexar ou consultar cada campo de forma independente Em todos os casos, o aninhamento é real e significativo, e o achatamento o preserva no caminho em vez de descartá-lo Quando a representação plana tiver servido ao seu propósito, o unflatten reconstrói o objeto original Se você também estiver se movendo entre JSON e planilhas especificamente, o Conversor CSV para JSON é o companheiro natural da perna tabular daquela viagem.
Como as matrizes são tratadas ao achatar?
As matrizes são a parte que as pessoas mais frequentemente erram, por isso vale a pena ser preciso Um elemento de matriz é achatado usando seu índice numérico como um segmento de caminho, que preserva a ordem e permite que a matriz seja reconstruída exatamente A ferramenta Toolz oferece duas notações para esse índice, e elas codificam as mesmas informações com sintaxe diferente.
| Entrada | Notação ponto | Notação de suporte |
|---|---|---|
{"roles":["admin","editor"]} |
roles.0, roles.1 |
roles[0], roles[1] |
{"items":[{"id":1}]} |
items.0.id |
items[0].id |
{"matrix":[[1,2]]} |
matrix.0.0 |
matrix[0][0] |
A notação de pontos escreve roles.00, que é compacto e corresponde a quantos sistemas config e i18 n chaveiam os seus valores Grava a notação de suporte roles[0], que espelha a sintaxe de acesso JavaScript e o estilo de caminho que algumas linguagens de consulta usam Nenhum dos dois é mais correto; você escolhe aquele que o sistema do outro lado espera O importante é a consistência: qualquer que seja a notação com a qual você achate, use a mesma para não achatar, porque é assim que a ferramenta sabe que um segmento numérico significa & quot; array index" em vez de & quot; uma chave de objeto que por acaso é um número." O padrão do flattener Toolz para notação de pontos e permite alternar para colchetes com um clique.
Como uso o flattener JSON?
O fluxo tem duas direções e um par de opções Comece escolhendo achatar ou não achatar com o alternador na parte superior Flatten pega o JSON aninhado e produz chaves pontilhadas; unflatten pega chaves pontilhadas e reconstrói a estrutura aninhada Load Sample preenche um exemplo trabalhado para qualquer direção em que você esteja, para que você possa ver a forma tanto da entrada quanto da saída antes de colar seus próprios dados.
Cole seu JSON na caixa de entrada Para achatar, que é um objeto aninhado; para não achatar, é um objeto plano cujas chaves são caminhos pontilhados A entrada tem que ser JSON válido, e se não for, a ferramenta relata a mensagem parser' s e a posição do problema em vez de entregar-lhe uma saída em branco, de modo que uma vírgula de arrasto perdida é rápida para encontrar Defina o estilo chave: o delimitador padrão para um ponto e pode ser alterado quando suas chaves já contêm pontos, e a notação de matriz alternar entre roles.0 e roles[0]. Mantenha essas duas configurações idênticas em um flatten e sua correspondência não achatada para que a viagem de ida e volta se alinhe Clique no botão de ação, verifique a contagem de teclas que confirma quantas folhas foram produzidas e copie a saída ou baixe-a como um .json arquivo. A coisa toda corre no instante em que você clica, no seu navegador, sem nada enviado para qualquer lugar.
O achatamento não tem perdas e quais são os casos extremos?
Para a ferramenta Toolz, sim, com um caso de borda que vale a pena conhecer Escalares, null, booleanos, e números sobrevivem intocados A parte sutil são recipientes vazios: um objeto vazio {} ou uma matriz vazia [] é preservado como um valor folha em vez de silenciosamente descartado, então uma configuração que depende de uma lista vazia ainda faz viagens de ida e volta para exatamente o que era Muitos achatadores ingênuos perdem recipientes vazios, o que muda silenciosamente o significado de um documento, então esta é uma escolha deliberada.
A única limitação genuína são as chaves que já contêm o delimitador. Se seus dados tiverem uma chave de objeto com um ponto literal, como {"a.b":1}, e você achata com um delimitador de pontos, o caminho se torna ambíguo: não achatado não pode dizer se a.b era uma chave ou aninhada a então b. A correção é mudar o delimitador para um caractere que não aparece em suas teclas, como uma barra ou um tubo, e usar esse mesmo delimitador para ambas as direções É a mesma classe de problema de escape que você vê quando Os delimitadores CSV colidem com os dados, e a mesma solução se aplica: escolha um separador que seus valores não contenham Fora desse caso, um achatamento seguido por um não achatado com configurações correspondentes reproduz exatamente o documento original, matrizes e contêineres vazios incluídos.
Qual é a diferença entre achatamento e conversão para outro formato?
O achatamento não é uma conversão de formato; é uma reestruturação dentro do JSON A saída de um achatamento ainda é JSON, apenas com um único nível de teclas pontilhadas em vez de aninhamento Isso é diferente dos conversores que transformam o JSON em uma serialização genuinamente diferente, e saber qual você precisa salva um passo.
Se você deseja os mesmos dados expressos como YAML para um arquivo de configuração, o Conversor JSON para YAML é a ferramenta, porque altera a sintaxe em vez da forma Se você quiser uma interface TypeScript descrevendo a estrutura para que seu front-end saiba o que está manipulando, o Conversor JSON para TypeScript infere isso de uma amostra Se você deseja um contrato formal para validação, o Gerador esquema JSON deriva um Esquema JSON de um exemplo O achatamento fica ao lado destes em vez de substituí-los: você achata quando um sistema downstream quer um nível de chaves, e você converte quando um sistema quer uma linguagem diferente Eu frequentemente faço as duas coisas em sequência, achatando uma carga útil para editá-la como colunas e então, separadamente, gerando tipos para a versão aninhada que EU entrego ao React Para imprimir ou validar o JSON em qualquer ponto dessa cadeia, o formatador json é o utilitário que mantenho aberto na próxima guia.
Como o unflatten decide entre uma matriz e um objeto?
Este é o mecanismo que faz a viagem de ida e volta funcionar, e entendê-lo explica tanto a ferramenta & #39; s padrões e sua uma borda afiada Quando unflatten lê uma chave como user.roles.0, ele divide-o nos segmentos user, roles, e 0, então caminha-los construindo estrutura como ele vai Em cada passo que olha para o próximo segmento para decidir que tipo de recipiente para criar Se o próximo segmento é um inteiro não negativo, ele faz uma matriz; se é qualquer outra coisa, ele faz um objeto Então roles.0 diz à ferramenta que roles deve ser um array cujo primeiro elemento é o valor, enquanto address.city diz isso address deve ser um objeto com a city propriedade.
Essa única regra, o & quot; segmento inteiro significa índice de matriz, & quot; é por isso que um achatado e um não achatado com configurações correspondentes reproduzem matrizes exatamente É também a razão pela qual a notação de matriz que você escolhe tem que ser consistente Na notação de pontos o índice de matriz e uma chave de objeto são ambos apenas texto entre pontos, então a ferramenta depende inteiramente do teste inteiro Na notação de colchete o [0] a sintaxe torna a intenção explícita antes mesmo de a divisão acontecer Qualquer um funciona, mas misturá-los, achatar com colchetes e não achatar com pontos, quebra o sinal do qual a ferramenta depende.
Aqui está a aresta afiada que segue a regra: um objeto cujas chaves são genuinamente as cordas "0", "1", "2" é indistinguível, uma vez achatado, de um array Ambos produzem as chaves 0, 1, 2, e unflatten irá reconstruí-los como uma matriz porque esse é o caso esmagadoramente comum Se você realmente precisa de um objeto com teclas de string numéricas para sobreviver à viagem de ida e volta, essa é a única situação em que achatar e não achatar não lhe devolverá o tipo exato, e é melhor manter esse objeto aninhado ou usar um esquema de teclas não numéricas Em anos de fazer isso EU acertei esse caso exatamente duas vezes, ambas as vezes em dados que foram indiscutivelmente modelados de forma errada para começar, então o padrão é o comércio certo para quase todos É o mesmo tipo de decisão pragmática por trás de manter números com zeros à esquerda como strings no Conversor CSV para JSON: a ferramenta otimiza o que os dados quase sempre significam e documenta a rara exceção em vez de tornar o caminho comum estranho.
Meu JSON é seguro para colar nesta ferramenta?
Sim, e é arquitetural ao invés de uma promessa Analisando, achatando, desachatando, e serializando tudo executado como JavaScript dentro de sua própria guia do navegador Não há upload, nenhum servidor ida e volta, e nada é registrado ou armazenado Abra o seu navegador' s guia de rede e clique no botão de ação: nenhum pedido sai Uma vez que a página carregou você pode se desconectar da internet e ele continua funcionando, porque nunca houve um servidor no loop para começar.
Isso importa mais do que pode parecer, porque as cargas JSON são exatamente o tipo de coisa que carrega segredos: tokens API em uma configuração, dados pessoais em uma resposta API, identificadores internos em um blob de configurações Um flattener que carregou seu objeto em um servidor transformaria uma carga privada em outra pessoa & #39; s linha de log. O processamento do lado do cliente remove o risco inteiramente, e é por isso que é o padrão em todas as ferramentas no Toolz.dev Se você quiser o raciocínio completo, EU o coloquei no guia de privacidade de dados para ferramentas online, e o kit mais amplo que uso para esse tipo de trabalho está no meu Guia do kit de ferramentas para desenvolvedores web.
Perguntas frequentes
O que significa achatar o JSON?
O achatamento JSON converte um objeto aninhado em um objeto de nível único cujas chaves são o caminho para cada valor O aninhado {"user":{"city":"Austin"}} torna-se o apartamento {"user.city":"Austin"}. Cada valor de folha recebe uma chave pontilhada, e nenhum aninhamento permanece na saída Unflatten inverte o processo e reconstrói a estrutura aninhada.
Como as matrizes são tratadas ao achatar?
Os elementos da matriz são achatados usando seu índice como segmento de caminho. {"roles":["admin","editor"]} torna-se {"roles.0":"admin","roles.1":"editor"} em notação de ponto, ou {"roles[0]":"admin","roles[1]":"editor"} na notação de colchetes O índice preserva a ordem para que a matriz possa ser reconstruída exatamente quando você não achatar.
Posso desinflar as chaves pontilhadas de volta ao JSON aninhado? Sim. Mude para o modo não achatado e cole um objeto plano cujas chaves são caminhos pontilhados A ferramenta reconstrói os objetos e arrays aninhados, decidindo matriz versus objeto se cada segmento de caminho é um índice inteiro. Flatten e unflatten são inversos exatos quando o delimitador e a notação de array correspondem.
Qual é a diferença entre a notação de matriz de pontos e colchetes?
Ambos codificam o mesmo índice de array; apenas a sintaxe difere. Grava a notação de ponto items.0.id0, que é compacto e comum nas teclas config e i18 n. A notação de suporte escreve items[0].id, que corresponde à sintaxe de acesso JavaScript e algumas linguagens de consulta Escolha o que seu sistema de destino espera e use o mesmo para ambas as direções.
O achatamento perde algum dado? Não. Escalares, nulos, booleanos e até mesmo objetos vazios e matrizes vazias são preservados como valores folha, portanto, desachatar o resultado reproduz o documento original. A única coisa a observar são as teclas que já contêm seu delimitador, por isso o separador é configurável.
Porque achataria o JSON? O achatamento adapta dados aninhados a sistemas que esperam um nível de chaves: colunas de planilhas, variáveis de ambiente, chaves de tradução pontilhadas, armazenamentos de sinalizadores de recursos e muitos pipelines de análise e registro O caminho pontilhado transporta a estrutura original através de um formato plano para que nada seja perdido.
O que acontece se uma chave já contiver um ponto? Um ponto literal dentro de uma chave é ambíguo com o separador de caminho, então a viagem de ida e volta pode dividi-lo no lugar errado Altere o delimitador para um caractere que não aparece em suas teclas, como uma barra ou um tubo, e use esse mesmo delimitador tanto para achatar quanto para não achatar.
Meu JSON foi carregado em algum lugar? Não. Análise e transformação são executadas como JavaScript no seu navegador. Nada é transmitido, registrado ou armazenado. Você pode confirmar isso observando a guia de rede enquanto achata ou ficando offline, já que a ferramenta continua funcionando sem conexão.
