Codificação de porcentagem

Codificação de porcentagem (também chamada de codificação de URL) é o mecanismo que as URLs usam para representar caracteres que não são legais na gramática de URL, ou que têm significados reservados. Definida na RFC 3986 §2.

O esquema: cada byte a escapar é escrito como % seguido de dois dígitos hexadecimais representando o valor do byte. Espaço vira %20. Ponto de interrogação vira %3F. Barra vira %2F. Sinal de libra vira %23.

Para caracteres não-ASCII (umlauts, acentos, CJK, emoji), o caractere é primeiro codificado em UTF-8 para uma sequência de bytes, e então cada byte é codificado em porcentagem. O único caractere “é” (U+00E9) vira os bytes 0xC3 0xA9 em UTF-8, codificado em porcentagem como %C3%A9.

Três classes de caracteres vale conhecer:

• Não reservados — A-Z, a-z, 0-9 e -_.~. Nunca escapados.
• Reservados — caracteres com significado sintático (:/?#[]@!$'()*+,;=). Escapados quando aparecem em dados que não devem ser analisados como sintaxe de URL.
• Outros — todo o resto (espaços, não-ASCII, caracteres de controle). Sempre escapados.

Codifique ou decodifique qualquer string em nosso codificador de URL, que lida com UTF-8 corretamente (algumas implementações legadas tratam strings como ISO-8859-1 e produzem saída diferente para a mesma entrada).

A nota do espaço-como-mais: no caminho e fragmento de uma URL, um espaço codifica como %20. Mas na query string de um corpo application/x-www-form-urlencoded, espaços codificam como + — uma convenção específica de formulário anterior à especificação moderna de URL. O encodeURIComponent() do JavaScript sempre emite %20; o antigo escape() (obsoleto) emitia +. Para envios de formulário e a maioria das bibliotecas de URL, ambas as representações decodificam corretamente para um espaço, mas misturá-las em uma URL construída manualmente quebra verificações de igualdade de string. O conselho moderno: use as APIs de URL padrão (WHATWG URLSearchParams em navegadores, url.URL no Node) e deixe a implementação escolher a codificação certa para o contexto.

Codificação dupla — o bug de produção mais comum: se um valor passa por dois codificadores sem um decodificador intermediário, o % original da primeira passagem vira %25, e o usuário vê uma bagunça como %2520 em vez de %20. A causa raiz é quase sempre uma camada do sistema que assume que sua entrada é texto simples quando já está codificada em URL. A correção é estabelecer um limite claro: a entrada é texto simples até o construtor de URL, codificada em porcentagem apenas na forma de URL, decodificada de volta para texto simples no momento em que sai do contexto de URL. Relacionado: UTF-8, ASCII. Referência: RFC 3986 §2.1 — Codificação de Porcentagem.

Exemplo prático

Codifique a consulta de pesquisa café & thé em uma query string de URL. Passo um — UTF-8 para cada caractere: c a f é <espaço> & <espaço> t h é vira os bytes 63 61 66 C3 A9 20 26 20 74 68 C3 A9. Passo dois — aplique as regras de codificação de porcentagem: caracteres não reservados (c a f t h) permanecem; sequências UTF-8 multibyte e caracteres reservados (&) são escapados. Resultado: caf%C3%A9%20%26%20th%C3%A9. URL completa: https://example.com/search?q=caf%C3%A9%20%26%20th%C3%A9. No lado receptor, o servidor decodifica revertendo ambas as etapas: substitui cada %XX pelo seu valor de byte para obter os bytes UTF-8, depois decodifica UTF-8 para recuperar café & thé. Se o servidor tratar os bytes como Latin-1 em vez de UTF-8, “café” chegará como “café” — o clássico mojibake.

Quando e por que isso importa

Cada URL construída por concatenação de strings é um bug potencial de injeção ou roteamento. Um nome de arquivo fornecido pelo usuário como ../../../etc/passwd embutido bruto em uma URL vira uma tentativa de path traversal; codificado em porcentagem como ..%2F..%2F..%2Fetc%2Fpasswd é seguro como um único segmento, mas pode decodificar na camada errada e reintroduzir o traversal. Consultas de pesquisa com & ou # nelas são silenciosamente truncadas se não forem codificadas. Frameworks HTTP modernos (Express, FastAPI, ASP.NET) lidam com isso automaticamente quando você usa seus construtores de parâmetros de consulta; os bugs se concentram em URLs de redirecionamento construídas manualmente, IDs de correlação de log e geradores de URL assinada onde os desenvolvedores concatenam strings. O hábito defensivo: nunca use + para concatenação de strings ao construir uma URL — sempre passe por URLSearchParams ou o equivalente do seu framework. Referência: WHATWG URL Standard — Bytes codificados em porcentagem.