Separe a estrutura dos dados
Uma consulta de URL é frequentemente escrita após um ponto de interrogação como pares chave=valor separados por sinais de E comercial (&). Esses delimitadores têm significado estrutural. Se o próprio valor contiver um sinal de E comercial (&), ele deve ser representado dentro do valor, em vez de confundir com outro par. Um codificador de componentes prepara um pedaço de dados; um construtor de consultas pega chaves e valores e junta toda a estrutura. Estes são dois níveis diferentes de trabalho. Não passe uma consulta concluída através de um codificador de componentes ou seu ponto de interrogação, sinais de igual e ampersands se tornarão dados. Por outro lado, não cole valores não confiáveis brutos entre separadores e espere que o navegador adivinhe o limite pretendido.
Uma consulta trabalhada com chaves repetidas
Suponha que uma tela de busca precise de q igual a vermelho & azul e de dois valores tag, a e b. Entregue à ferramenta de JSON para query string um objeto com q como texto e tag como array. A serialização de formulário produz q=vermelho+%26+azul&tag=a&tag=b. Nessa convenção, o sinal de mais representa um espaço, enquanto %26 protege o ampersand dentro do texto pesquisado. Ao analisar a saída com a ferramenta inversa, q volta a ser vermelho & azul e tag se torna um array de dois textos. A repetição é intencional: tag=a&tag=b não equivale a um único valor separado por vírgula. Experimente mudar uma tag no conversor incorporado.
- Dados originais: q = vermelho & azul; tag = a, b
- Consulta: q=vermelho+%26+azul&tag=a&tag=b
- Análise: q é uma frase; tag tem dois valores
Por que um componente pode ter um aspecto diferente
O codificador de componentes de URL dedicado usa as regras de componentes para um valor. Um espaço pode aparecer como %20 lá, enquanto um serializador de consulta estilo URLSearchParams usa o sinal de mais (+) para representar um espaço. Ambas as ortografias podem ser válidas em seus respectivos contextos, mas não são necessariamente strings idênticas. Um sinal de mais literal em uma consulta de estilo de formulário deve ser escapado para que não se transforme em um espaço durante a análise. Codificar um sinal de porcentagem já codificado dá %25, o sinal familiar de codificação dupla acidental. Mantenha chaves e valores brutos até que o construtor de consultas os processe ou codifique exatamente um componente antes da montagem manual. Evite misturar ambas as estratégias nos mesmos dados.
Saiba o que a viagem de ida e volta preserva
O analisador de consulta MultiVerto transforma chaves repetidas em arrays. Todos os valores de consulta chegam como strings, mesmo que o construtor JSON tenha aceitado um número ou booleano antes da serialização. Ele não restaura um tipo numérico original ausente. Arrays vazios e objetos aninhados não têm uma representação direta neste formato chave/valor simples, então o construtor os rejeita. APIs diferentes também escolhem políticas diferentes para valores vazios, chaves duplicadas e ordenação. Uma viagem de ida e volta pode, portanto, preservar pares úteis sem preservar todos os detalhes de um objeto JSON mais rico. Verifique o contrato da API antes de decidir como arrays, campos ausentes e strings vazias devem aparecer.
Faça um caso de teste estável
Comece com o endpoint de destino e anote cada chave e valor bruto separadamente. Crie a consulta uma vez e inspecione a saída para caracteres reservados codificados. Analise-o para confirmar que os pares pretendidos sobreviveram, especialmente valores contendo ampersands, sinais de mais, sinais de porcentagem e texto não ASCII. Teste uma chave repetida se o servidor aceita arrays por chaves repetidas e confirme que o servidor interpreta-a da mesma forma. Nunca coloque segredos em uma string de consulta apenas porque os caracteres são codificados: URLs podem ser copiados, registrados e compartilhados. O MultiVerto calcula o exemplo localmente, mas o URL que você eventualmente publica ou envia tem suas próprias regras de visibilidade e retenção.