Query strings e parâmetros

Tudo após o primeiro ? em uma URL http(s) inicia o componente de query — string interpretada como pares no estilo application/x-www-form-urlencoded pela maioria de browsers e frameworks de servidor, mesmo quando o formulário não é HTML literal.

https://api.example.com/items?tag=book&sort=price_asc&page=2

O parse costuma revelar três chaves: tag, sort, page.

Sintaxe de pares

• Pares são separados por & (; aparece em tráfego selvagem, mas é desencorajado sem suporte explícito).
• Dentro do par, o primeiro = separa nome de valor:
  • flag → valor string vazia em muitos parsers
  • q= → valor vazio
  • q=ruby+gems → sinais de mais literais podem virar espaços sob regras de formulário (veja a lição sobre +).

?q=hello&empty=&flag

Repetir chaves é permitido pelo formato de fio:

?tag=a&tag=b

A interpretação (manter último vs coletar array) depende do framework — nunca assuma cegamente.

Codificar valores antes de concatenar

Se um valor contém &, =, # ou texto não ASCII, codifique o componente antes de juntar:

const base = "https://example.com/search";
const params = new URLSearchParams({ q: "fish & chips", city: "São Paulo" });
const url = `${base}?${params.toString()}`;

Usar URL mantém delimitadores sanos:

const url = new URL("https://example.com/search");
url.searchParams.set("q", "100% completion");
console.log(url.toString());

Armadilhas de parsing

split('&') manual falha quando & extra aparece dentro de valores já decodificados:

// Parece ok até o decode revelar & extra
decodeURIComponent('a=b%26c=d')

Prefira URL (searchParams), bibliotecas de servidor ou parsers que iteram bytes com estado correto, em vez de splits ingênuos após decode parcial.

URLs relativas e contexto HTML

Âncoras <a href="..."> resolvem URLs relativas contra a base do documento:

<a href="?page=2">Próxima</a>

Isso surpreende se você esperava path absoluto — entenda ordem de resolução (esquema → host → path → regras de query).

Ordenação e normalização

Algumas URLs assinadas ou caches tratam ordem de parâmetros como significativa. Ao gerar strings canônicas para assinatura, defina se ordena chaves e como percent-encode — assinatura estilo AWS e string-to-sign do OAuth 1.0 são exemplos clássicos de canonização estrita além do comportamento casual do browser.

Dominar query strings é sobretudo limites de componente e camada de codificação certa em cada nível da stack.

Monte e inspecione pares no modo query do Codificador / Decodificador URL antes de depurar redirects ou callbacks OAuth.