perdi uma hora uma vez para uma string de consulta Um webhook de terceiros estava enviando filter[status]=open&filter[assignee]=me, meu treinador estava lendo filter como uma string plana, e EU não conseguia descobrir por que cada solicitação veio sem filtro No momento em que colei a URL bruta em um analisador de string de consulta e vi a resolução para um objeto aninhado, o bug era óbvio: o remetente usava a notação de colchete e meu analisador não. Este guia cobre como EU uso o Analisador de strings de consulta em Toolz.dev, quais são realmente as partes complicadas das strings de consulta e por que a mesma chave codificada de duas maneiras diferentes pode quebrar silenciosamente uma integração.
tl;dr: Uma string de consulta é a parte de uma URL após o ponto de interrogação que carrega parâmetros como pares chave-valor Um analisador de string de consulta converte isso em JSON estruturado, decodificando porcentagem-codificação e manipulação de chaves repetidas e matrizes de colchetes, e pode construir uma string de consulta corretamente codificada de volta do JSON Analisador de strings de consulta faz as duas direções no seu navegador, para que você possa inspecionar um URL confuso ou montar um limpo sem sair da página.
O que é uma string de consulta?
Uma string de consulta é a seção de uma URL que começa após o primeiro ponto de interrogação e termina no fragmento, a parte após um hash Ele carrega parâmetros como key=value pares unidos por ampersandos, então ?q=json&page=2 passa dois parâmetros Servidores e código do cliente lêem aqueles para filtrar uma pesquisa, rastrear uma campanha, paginar uma lista ou transportar estado entre páginas As regras genéricas para o que é ou não legal nesse componente vêm de RFC 3986, o padrão URI e as regras específicas que os navegadores seguem para parâmetros de estilo de formulário vêm do whatwg standard de url.
A captura é que a RFC 3986 define a sintaxe do componente de consulta, mas não o seu significado Ele diz quais caracteres são permitidos e como eles devem ser codificados por porcentagem, mas não diz nada sobre como key=value os pares mapeiam para uma estrutura de dados Essa interpretação foi herdada do envio de formulários HTML, e diferentes plataformas a estenderam de maneiras incompatíveis É por isso que a mesma string de consulta pode significar coisas ligeiramente diferentes para um back-end PHP, um controlador Rails e um front-end JavaScript, e por que um analisador tem que tornar suas convenções explícitas.
Cada chave e valor em uma string de consulta é codificado em URL para que os caracteres reservados sobrevivam Um espaço se torna %20 ou um sinal de mais, um e comercial dentro de um valor se torna %26 portanto, não é confundido com um separador e uma barra se torna %2F. Parsing significa dividir os pares e, em seguida, decodificar cada lado, e construir significa codificar cada lado e unir os pares Obter a codificação errada em qualquer direção e valores silenciosamente corrompidos.
O que um analisador de strings de consulta realmente faz?
Um analisador pega uma URL ou uma string de consulta simples e a transforma em dados estruturados e legíveis Na maneira como ele retira tudo até e incluindo o ponto de interrogação, ignora o fragmento após o hash, divide os pares, decodifica cada chave e valor e decide como representar chaves repetidas e chaves entre colchetes A saída é um objeto JSON que você pode ler e copiar, além de uma tabela plana de cada par decodificado, de modo que duplicatas e valores vazios são óbvios.
No Toolz.dev a ferramenta é executada em duas direções No modo de análise você cola um URL completo ou apenas sua string de consulta e obtém o JSON e a tabela de parâmetros No modo de compilação você cola um objeto JSON e obtém uma string de consulta corretamente codificada, com uma escolha de como as matrizes são representadas Carregue a amostra e você pode assistir a um URL real com um fragmento, uma matriz de estilo repetido e um espaço codificado resolver em JSON limpo, em seguida, reconstruí-lo.
A razão para usar um analisador dedicado em vez de olhar para o URL é que as cadeias de consulta escondem sua estrutura Uma URL longa com caracteres codificados, chaves repetidas e notação de colchetes é quase impossível de ler corretamente digitalizando-a, e as partes que são mais difíceis de ler, a codificação e as duplicatas, são exatamente as partes que causam bugs Ver a tabela decodificada ao lado do JSON remove as suposições.
Como as chaves repetidas são tratadas?
A mesma chave pode aparecer legalmente mais de uma vez em uma string de consulta, como em tags=react&tags=laravel, e não há uma única maneira correta de interpretar isso, que é a raiz de muita confusão Diferentes sistemas resolvem duplicatas de forma diferente, então um analisador tem que deixar você escolher.
A convenção mais comum, e o padrão na ferramenta Toolz.dev, é coletar chaves repetidas em uma matriz, portanto tags=react&tags=laravel torna-se {"tags":["react","laravel"]}. Isso corresponde à forma como o navegador & #39;s próprio URLSearchParams.getAll expõe os valores e como a maioria dos back-ends modernos se comportam Mas alguns frameworks mantêm apenas a primeira ocorrência e alguns mantêm apenas a última, então a ferramenta oferece opções keep-first e keep-last também Quando você está depurando uma integração, combinar o comportamento do analisador & #39; s com o sistema que produziu ou consome a URL é o que torna o JSON significativo.
Essa ambiguidade não é acadêmica Um problema clássico de segurança e correção chamado poluição de parâmetros HTTP existe precisamente porque dois sistemas em um caminho de solicitação podem resolver id=1&id=2 diferentemente, alguém vendo 1 e o outro vendo 2. Ser capaz de ver, explicitamente, como um determinado analisador resolve duplicatas é a maneira mais rápida de raciocinar sobre essa classe de bug.
O que significa colchetes como tags [] ou filtro [cor]?
A notação de colchetes é uma convenção para codificar matrizes e objetos aninhados dentro de uma string de consulta plana, e é onde os analisadores discordam mais Um colchete vazio à direita marca uma matriz, portanto tags[]=react&tags[]=laravel constrói {"tags":["react","laravel"]}. Um colchete nomeado marca um objeto aninhado, portanto filter[color]=red&filter[size]=l constrói {"filter":{"color":"red","size":"l"}}. Os colchetes podem fazer ninho, então a[b][c]=1 constrói {"a":{"b":{"c":"1"}}}.
Essa sintaxe vem de como PHP e Ruby on Rails serializam dados de formulário e de muitas bibliotecas JavaScript, como qs siga-o Não faz parte de qualquer padrão de URL central, e é exatamente por isso que uma planície URLSearchParams no navegador não irá expandi-lo, fornecendo uma chave literal de tags[] em vez de uma matriz. O analisador Toolz.dev entende a convenção e a expande para a estrutura correspondente, permitindo desativar esse comportamento quando desejar as chaves literais.
Veja como as principais convenções se alinham, tanto na análise quanto na construção:
| Estilo matriz | Codificado como | Analisa para | Comum em |
|---|---|---|---|
| Chave repetida | tags=a&tags=b |
["a","b"] |
Navegadores, a maioria das back-ends |
| Suporte vazio | tags[]=a&tags[]=b |
["a","b"] |
PHP, trilhos, biblioteca qs |
| Colchete indexado | tags[0]=a&tags[1]=b |
["a","b"] |
biblioteca Qs, dados ordenados |
| Vírgula | tags=a,b |
uma corda para dividir | Algumas APIs, URLs compactas |
Quando você constrói uma string de consulta com a ferramenta, você escolhe qual delas emitir, para que a saída corresponda ao que o sistema receptor espera. Quando você analisa, a ferramenta detecta chaves repetidas e notação de colchetes para você, e os valores unidos por vírgulas permanecem como uma única string porque só você sabe se uma vírgula é um separador ou parte dos dados.
Por que os sinais de mais se transformam em espaços?
Na string de consulta de uma URL, um espaço literal é muitas vezes codificado como um sinal de mais, em vez de %20. Esta é uma regra herdada do application/x-www-form-urlencoded formato que os formulários HTML usam e o whatwg standard de url codifica-o: ao analisar dados codificados em formulário, a + está descodificado para um espaço Então q=json+parser deve analisar json parser, e a ferramenta Toolz.dev faz isso por padrão.
A subtileza é que esta regra se aplica à componente de consulta, não ao caminho A + em um segmento de caminho há uma vantagem literal. E ocasionalmente seus dados contêm genuinamente sinais positivos que devem ser preservados, como um número de telefone ou uma pesquisa C++. Para esses casos, a ferramenta possui um interruptor para desligar o plus-as-space, de modo que o plus sobrevive à viagem de ida e volta. Este é o tipo de detalhe que um uso geral codificador de url não decidirá por você, pois não sabe se está olhando para uma consulta ou caminho.
Acertar isso também é importante ao construir. Quando a ferramenta codifica um valor, ela codifica por cento os caracteres reservados e, por padrão, usa um sinal de mais para espaços no estilo codificado por formulário, portanto, a string que ela produz é aquela em que navegadores e back-ends decodificarão da maneira que você pretendia.
Como isso difere de um analisador de URL completo?
Um analisador de string de consulta e um analisador de URL completo se sobrepõem, mas respondem a perguntas diferentes e, usando o caminho certo, salva uma etapa Um analisador de URL quebra um link completo em seus componentes, o esquema, host, porta, caminho, consulta e fragmento, e é o que você deseja quando está depurando para onde uma solicitação está indo ou por que um redirecionamento ou uma verificação CORS se comporta de maneira estranha Um analisador de string de consulta se concentra apenas na consulta e a transforma em JSON estruturado e editável, incluindo matrizes e chaves aninhadas, e pode construir a consulta de volta.
o analisador de url no Toolz.dev é a ferramenta para anatomia: dê-lhe um link e ele mostra-lhe a distinção host versus origem, a porta padrão, e as peças do caminho O analisador de strings de consulta é a ferramenta para trabalhar com parâmetros: dê-lhe o mesmo link e ele dá-lhe os parâmetros como JSON você pode editar, e então reconstrói uma string de consulta de suas edições Na prática EU usá-los juntos, o analisador de URL para entender um link eo analisador de string de consulta para alterar seus parâmetros, e se EU estou montando um link de campanha EU alcance para o Construtor UTM em vez disso, que é um construtor de strings de consulta especializado para tags analíticas.
Quando é que EU realmente alcancei isto?
A resposta honesta é sempre que um URL está fazendo mais do que apontar para uma página Eu o uso para depurar webhooks e redirecionamentos OAuth, onde os parâmetros carregam toda a carga útil e um valor mal codificado quebra o fluxo Eu o uso para ler os parâmetros de rastreamento em um link de marketing para que EU possa ver exatamente o que uma campanha está passando Eu o uso para converter uma string de consulta que um colega colou em um bate-papo em JSON Eu posso soltar em um dispositivo de teste, e para fazer o inverso, transformando um pequeno objeto em uma string de consulta para uma solicitação manual rápida.
Um exemplo trabalhado torna a recompensa concreta Um provedor OAuth redireciona de volta para o seu aplicativo com algo como ?code=abc123&state=xyz789&scope=read%20write&error=. Colado no analisador, que se resolve em um objeto limpo: code e state como seus valores literais, scope decodificado para read write porque %20 é um espaço, e error como uma string vazia em vez de uma chave ausente, que informa que o provedor enviou o parâmetro, mas o deixou em branco. Lendo isso a olho nu a partir do URL bruto, você provavelmente perderia o espaço codificado scope e interpretou mal o vazio error, e ambos são exatamente os detalhes que decidem se o seu manipulador de retorno de chamada se ramifica corretamente. Ver a tabela decodificada remove a ambiguidade e, se você precisar reproduzir a solicitação, o modo de construção transforma seu objeto editado novamente em uma URL de retorno de chamada válida em uma única etapa.
Porque tanto desse trabalho envolve URLs que carregam tokens, valores assinados e identificadores de rastreamento, fazê-lo em uma ferramenta que é executada inteiramente em seu navegador importa Nada que você cole é transmitido, registrado ou armazenado, e a ferramenta continua trabalhando com a rede desligada, para que você possa inspecionar com segurança uma URL de retorno de chamada assinada da produção, em vez de uma cópia higienizada Eu faço o caso mais amplo para manter esse tipo de trabalho do lado do cliente no Privacidade de dados em ferramentas online guia, e este analisador fica ao lado dos outros utilitários de link e texto que descrevi no Kit de ferramentas para desenvolvedores web. Se parte do seu trabalho estiver transformando entradas confusas em slugs limpos e identificadores, o Slug Gerador é um companheiro natural para o lado de saída do trabalho de URL.
Perguntas frequentes
O que é uma string de consulta?
Uma string de consulta é a parte de uma URL após o ponto de interrogação que carrega parâmetros como pares chave-valor unidos por ampersands, como ?q=json& page=2. servidores e código do cliente lê-lo para filtrar resultados, campanhas de rastreamento, ou estado de passagem Cada chave e valor é URL-codificado para que espaços e caracteres reservados sobrevivam, e o fragmento após um hash não faz parte dele.
Como as chaves repetidas são tratadas ao analisar?
Por omissão uma chave que aparece mais do que uma vez é combinada numa matriz, por isso tags=react&tags=laravel parses to {"tags":["react", "laravel"]}.Você pode mudar para manter apenas o primeiro valor ou apenas o último valor em vez disso, porque diferentes back-ends resolvem duplicatas de forma diferente e você quer que o JSON corresponda ao sistema que você está direcionando.
O que significa colchetes como tags [] ou filtro [cor]?
A notação de colchetes codifica matrizes e objetos aninhados dentro de uma string de consulta plana. tags []=react& tags[]=laravel constrói uma matriz e filtre [color]=red& filter[size]=l constrói o objeto aninhado {"filter": {"color": "red", " size": " l"}}. É comum em PHP, Rails e bibliotecas de formulários, portanto, o analisador o expande na estrutura correspondente e você pode desativá-lo para manter as chaves literais.
Por que um sinal de mais se torna um espaço?
Na sequência de consulta de uma URL, um espaço literal é frequentemente codificado como um sinal de mais, uma regra herdada do envio de formulário HTML, de modo que o analisador converte + de volta em um espaço por padrão Se seus dados contiverem sinais de mais reais que devem ser mantidos, como C++ ou um número de telefone, desligue a opção de mais como espaço e o sinal de mais será preservado.
Posso construir uma string de consulta a partir do JSON?
Sim. Mude para o modo de construção e cole um objeto JSON de pares chave-valor. A ferramenta codifica cada chave e valor e os une a empersands, e você pode escolher como as matrizes são codificadas: chaves repetidas, colchetes vazios, colchetes indexados ou uma lista separada por vírgulas, para que a saída corresponda ao que o sistema receptor espera.
Qual é a diferença entre isso e um analisador de URL completo?
Um analisador de URL completo quebra uma URL inteira em esquema, host, porta, caminho, consulta e fragmento Um analisador de string de consulta se concentra apenas na consulta, transforma-a em JSON editável estruturado, incluindo matrizes e chaves aninhadas, e pode construir a consulta de volta Use o analisador de URL para inspecionar um link, e esta ferramenta para ler ou alterar seus parâmetros.
Ele lida com um URL completo ou apenas com a parte de consulta?
Ambos. se você colar um URL completo, o analisador deixa cair tudo até e incluindo o ponto de interrogação e ignora o fragmento após o hash, então você obtém apenas os parâmetros Se você colar uma string de consulta nua sem ponto de interrogação, ela é analisada como está, o que é útil quando você copiou apenas os parâmetros.
Meu URL é enviado para algum lugar?
No. Parsing, decodificação e codificação todos são executados como JavaScript em seu navegador, para que nada seja transmitido, registrado ou armazenado Você pode confirmá-lo assistindo a guia de rede enquanto você analisa um URL, ou desconectando-se da internet, porque a ferramenta continua funcionando offline uma vez que a página tenha carregado.
Inspecione ou monte parâmetros gratuitamente Analisador de strings de consulta. Ele analisa uma URL em JSON e constrói uma string de consulta, manipulando chaves repetidas, matrizes de colchetes e codificação, inteiramente em seu navegador.
