Analisar query string de URL em objeto chave-valor

Este analisador transforma uma URL absoluta completa ou uma query string bruta em um objeto estruturado de chaves e valores. Ele decodifica escapes percentuais e sinais de adição usados por formulários, preserva valores vazios e reúne parâmetros repetidos em listas na ordem original. Escapes malformados e UTF-8 inválido geram um erro claro, sem substituição silenciosa de caracteres.

Escolha a forma de entrada adequada à sua origem

Você pode enviar uma URL absoluta completa, como <code>https://example.com/search? Em uma URL absoluta, somente o componente de consulta é analisado; esquema, autoridade, caminho e fragmento não viram campos. Uma URL sem consulta retorna um objeto de parâmetros vazio.

A entrada bruta é tratada integralmente como dados de consulta depois da remoção de um ponto de interrogação inicial opcional. Cada sinal &amp; inicia um novo par, enquanto o primeiro sinal de igual separa o nome do valor. Um nome sem sinal de igual é preservado com valor vazio, assim como uma atribuição explicitamente vazia.

Segmentos vazios entre sinais &amp; consecutivos são ignorados. O resultado também informa a quantidade de chaves distintas e de pares analisados, permitindo que você identifique campos repetidos sem precisar recontar o objeto.

Entenda a decodificação e as chaves repetidas

Nomes e valores são decodificados separadamente segundo as convenções normalmente aplicadas a formulários em consultas de URL. Um sinal de adição vira espaço, enquanto sequências <code>%HH</code> são interpretadas como bytes UTF-8. Assim, <code>city=San+Jos%C3%A9</code> produz texto Unicode legível, e um separador codificado como <code>%26</code> permanece dentro de um único valor em vez de iniciar outro campo.

A decodificação ocorre exatamente uma vez: <code>%2520</code> vira <code>%20</code>, não um espaço. Quando uma chave aparece uma vez, o valor é uma string. Se a mesma chave decodificada aparecer novamente, o valor vira uma lista que contém todas as ocorrências na ordem de origem.

Essa regra representa grupos de caixas de seleção, filtros, tags e outros controles de seleção múltipla sem descartar informações nem inventar propriedades numeradas. A repetição é determinada após a decodificação; portanto, grafias codificadas equivalentes do mesmo nome são agrupadas. Valores vazios repetidos também são preservados.

O analisador não infere booleanos, números ou datas e não interpreta a notação com colchetes como objetos aninhados. Todos os valores escalares continuam como strings para que o código seguinte aplique conscientemente sua própria conversão específica.

Interrompa dados corrompidos antes que entrem no fluxo

Analisadores permissivos podem manter um sinal de porcentagem isolado, aceitar um escape de apenas um dígito ou inserir um caractere substituto quando os bytes escapados não formam UTF-8 válido. Esses comportamentos fazem identificadores danificados parecerem utilizáveis e criam diferenças difíceis de explicar entre navegador, servidor e uma rotina de verificação de assinatura. Esta capacidade confere se cada sinal de porcentagem é seguido por exatamente dois dígitos hexadecimais e depois verifica se cada sequência de bytes decodificada representa UTF-8 válido.

Se qualquer condição falhar, a solicitação retorna um erro de entrada inválida, não um objeto parcial. O analisador é puro e determinístico: não acessa a rede, não segue redirecionamentos, não consulta o relógio, não usa aleatoriedade e não guarda estado entre chamadas. Trate as strings retornadas como dados, não como HTML, código, caminhos de arquivo ou expressões de banco de dados confiáveis; decodificar recupera caracteres, mas não torna seguro o uso posterior.

No navegador, a mesma lógica permite examinar rapidamente links copiados sem contatar o destino.