Guia de Codificação URL

Codificação URL — formalmente percent-encoding — é o mecanismo que a web usa para transportar caracteres especiais dentro de URLs com segurança. Toda vez que um usuário digita uma busca com espaços, toda vez que uma API recebe um query string com ampersand, toda vez que um redirect preserva um nome de arquivo não-ASCII, é o percent-encoding fazendo isso funcionar. Este guia cobre as regras, as duas APIs de JavaScript e os erros que vão te morder.

Reservados vs não-reservados

A RFC 3986 divide os caracteres em dois grupos. Não-reservados — A–Z, a–z, 0–9 e - _ . ~ — são sempre seguros. Reservados — : / ? # [ ] @ ! $ & ' ( ) * + , ; = — têm significado estrutural (separar esquema de caminho, chave de valor, componente de componente) e devem ser codificados quando aparecem como dado em vez de estrutura. Todo o resto (espaços, Unicode, bytes binários) deve sempre ser codificado.

A regra de codificação

Cada byte que precisa ser escapado vira um sinal de porcentagem seguido de dois dígitos hexadecimais. Um espaço é %20, um ampersand é %26, um travessão são três bytes UTF-8 e portanto três sequências: %E2%80%94. Decodificadores revertem byte a byte.

encodeURI vs encodeURIComponent

JavaScript traz duas funções embutidas que confundem todo mundo pelo menos uma vez. encodeURI(str) assume que str é uma URL completa e deixa reservados em paz (barras, dois-pontos, interrogações sobrevivem). encodeURIComponent(str) assume que str é um único componente — um segmento de caminho ou valor — e escapa todo reservado agressivamente. Regra prática: ao compor um valor de query string para ?chave=valor, sempre encodeURIComponent. Para uma URL completa em que só quer limpar o que não é URL, encodeURI.

Erros comuns

• Dupla codificação — codificar algo já codificado. %20 vira %2520, o decodificador vê um %20 literal e a URL perde o espaço.
• Função errada na parte errada — usar encodeURIComponent em uma URL inteira destrói o separador de esquema.
• Esquecer os espaços em form-data — POSTs HTML com application/x-www-form-urlencoded codificam espaços como +, não como %20. Para todo o resto, use %20.
• Supor não-UTF-8 — codificação URL moderna é sempre UTF-8 primeiro, depois percent-encoding. Sistemas legados com Latin-1 ou Shift_JIS parecem iguais mas produzem lixo em não-ASCII.

Quando escolher cada

Use encodeURIComponent toda vez que compuser um valor de query dinamicamente. Use encodeURI quando tiver uma URL fornecida pelo usuário (talvez com Unicode no caminho) e quiser torná-la segura sem quebrar sua estrutura. Decodifique com decodeURIComponent a menos que esteja deliberadamente preservando reservados — caso em que provavelmente não deveria tê-los codificado.