Por que as URLs precisam de codificação
Uma URL só pode conter um conjunto limitado de caracteres ASCII, e vários deles têm uma função. ? inicia a query string, & separa parâmetros, = separa o nome do valor, # inicia o fragmento e / separa os segmentos do caminho. Se um termo de busca ou um nome de arquivo tiver um desses caracteres, o navegador ou o servidor o lê como estrutura, e não como dado.
A codificação por porcentagem resolve isso escrevendo o caractere problemático como % seguido de dois dígitos hexadecimais. Um espaço vira %20, & vira %26, / vira %2F. Caracteres fora do ASCII são primeiro convertidos em bytes UTF-8, e cada byte é codificado separadamente, então é vira %C3%A9 e um único emoji se transforma em quatro grupos %XX.
Situações em que você precisa disso:
- Montar um link com um termo de busca, uma URL de redirecionamento ou um endereço de e-mail como parâmetro.
- Colocar uma URL dentro de outra URL, por exemplo um valor
returnToouredirect_urinum fluxo de login. - Depurar webhooks e links de analytics que chegam como uma sopa ilegível de
%. - Ler logs de servidor, em que os caminhos requisitados são registrados na forma codificada.
Modo componente versus modo URL completa
A caixa Codificar URL completa (manter :/?&=) escolhe entre duas regras diferentes, e escolher a errada é o erro mais comum.
Padrão: codificar um componente
Com a caixa desmarcada, tudo é codificado, menos letras, dígitos e - _ . ! ~ * ' ( ). Esta é a escolha certa para um único valor que vai depois do = numa query string ou dentro de um segmento do caminho. O texto rock & roll/live vira rock%20%26%20roll%2Flive, que pode ficar tranquilamente em ?q= sem quebrar a lista de parâmetros.
URL completa
Com a caixa marcada, os caracteres que dão estrutura à URL são mantidos: : / ? # & = + , ; @ $ e os listados acima. Espaços, letras fora do ASCII e alguns outros continuam sendo codificados. Use quando você tem um endereço completo que é quase válido, por exemplo https://example.com/files/annual report.pdf, e só precisa corrigir o espaço.
O modo URL completa não consegue diferenciar um & estrutural de um que faz parte de um valor. Em https://shop.example/?q=salt & pepper, o & fica como está, e o servidor vê um parâmetro quebrado. Nesse caso, codifique só o valor no modo componente e cole-o na URL.
Espaços, sinais de mais e codificação dupla
Existem duas convenções para espaços. A codificação de caminhos e de URLs em geral usa %20; o envio de formulários HTML (application/x-www-form-urlencoded) usa +. Este codificador sempre produz %20, que todo servidor entende nos dois lugares.
O decodificador converte + em espaço antes de decodificar, porque é isso que significa em query strings de formulário. O efeito colateral: um sinal de mais literal que nunca foi codificado, como C++ num caminho, é decodificado como espaços. Se o texto original tinha um sinal de mais de verdade, ele deveria ter sido enviado como %2B, e essa forma é decodificada corretamente.
A codificação dupla é a outra armadilha clássica. O próprio sinal % é codificado como %25, então passar uma string já codificada pelo codificador de novo transforma %20 em %2520. Se você vir %25 seguido de dois dígitos hexadecimais num link que não funciona, decodifique-o uma vez e confira o resultado.
Quando a decodificação falha
"String codificada inválida" aparece quando um % não é seguido de dois dígitos hexadecimais, ou quando os bytes não formam UTF-8 válido. Causas típicas:
- Um link truncado, cortado no meio de uma sequência
%C3%A9. - Um sinal de porcentagem literal, como em
50% off, que nunca foi codificado. - Texto codificado há muito tempo numa página de código legada de um byte, como Windows-1251 ou Latin-1, em que
éé%E9em vez de%C3%A9.
Nos dois primeiros casos, corrija a parte quebrada à mão. Para páginas de código legadas, não há correção automática confiável, já que o mesmo byte significa letras diferentes em páginas de código diferentes.
Codificações relacionadas
A codificação por porcentagem não é a mesma coisa que Base64, que transforma bytes arbitrários numa string compacta, nem que entidades HTML como &, que servem para texto dentro de HTML. Para endereços legíveis criados a partir de títulos, um gerador de slug para URL produz resultados mais limpos do que a codificação: My Trip to Kraków vira my-trip-to-krakow em vez de My%20Trip%20to%20Krak%C3%B3w.
A codificação e a decodificação rodam no seu navegador, então tokens ou parâmetros privados dentro da URL não são enviados a lugar nenhum.