URL Encode e Decode

Por que existe percent-encoding

URLs só admitem um conjunto restrito de caracteres, definido lá atrás na RFC 3986. Letras, dígitos e alguns símbolos passam direto; o resto precisa ser representado como % seguido do valor hexadecimal do byte. Espaço vira %20, arroba vira %40, cedilha em UTF-8 vira %C3%A7.

Não é preciosismo: alguns caracteres têm função estrutural dentro da URL. ? inicia a query string, & separa parâmetros, = liga chave e valor, # começa o fragmento. Um valor que contenha qualquer um deles sem codificação quebra a interpretação da URL inteira.

Componente ou URL inteira: a escolha que causa bug

Esta distinção é a origem da maior parte dos problemas com URL encoding, e corresponde exatamente às duas funções do JavaScript.

Componente (encodeURIComponent) codifica tudo que não é seguro, incluindo /, ?, & e =. É o que você usa para o valor de um parâmetro — porque ali esses caracteres são conteúdo, não estrutura.

URL inteira (encodeURI) preserva os caracteres estruturais, porque assume que você está codificando um endereço completo, onde eles têm papel sintático.

Usar o modo errado quebra de dois jeitos opostos: codificar a URL inteira como componente destrói a estrutura e o navegador não a entende; codificar um valor como URL deixa passar & e =, e o servidor divide o parâmetro no meio. O segundo caso é a raiz de vulnerabilidades de injeção de parâmetro.

O espaço e o sinal de mais

Espaço tem duas representações possíveis, e a confusão entre elas é clássica. Em percent-encoding, espaço é %20. Em formulários HTML enviados como application/x-www-form-urlencoded, espaço vira +.

A consequência é que um + literal precisa ser codificado como %2B em query string, ou vai ser lido como espaço do outro lado. É por isso que números de telefone internacionais colados numa URL frequentemente perdem o sinal de mais. Nossa decodificação trata + como espaço, que é o comportamento esperado em query string.

Acentos e o encoding dos bytes

Percent-encoding codifica bytes, não caracteres — então o encoding do texto importa antes da codificação. "ção" em UTF-8 são cinco bytes e vira %C3%A7%C3%A3o. Em Latin-1 seriam três bytes e o resultado seria diferente e incompatível.

UTF-8 é o padrão da web e o que usamos aqui. Se você vê acentos corrompidos depois de decodificar, quase sempre a origem codificou em outro encoding, e o problema não está na decodificação.

Codificar duas vezes

Um erro sutil e difícil de achar: codificar algo que já estava codificado. O % do primeiro passe é ele próprio um caractere que precisa de codificação, então %20 vira %2520.

Isso costuma acontecer quando uma URL passa por várias camadas — front-end, gateway, serviço — e cada uma codifica "por segurança". O sintoma é literal: aparecem %25 no meio do texto. Se você vir isso, decodifique duas vezes e descubra qual camada está codificando a mais.