Codificar Parametros de Consulta URL: Codificador

O Resultado Codificado

A entrada search query=hello world&category=café & resumo&redirect=https://example.com/path?id=42 e codificada como:

search%20query%3Dhello%20world%26category%3Dcafe%20%26%20resumo%26redirect%3Dhttps%3A%2F%2Fexample.com%2Fpath%3Fid%3D42

Cada caractere exceto os não reservados (A-Z a-z 0-9 - _ . ~) foi substituido por sua forma codificada percentualmente. Os sinais de =, caracteres &, as letras acentuadas é a URL completa no parametro de redirecionamento estão todos codificados com seguranca.

Codificação Percentual (RFC 3986)

A codificação percentual e definida no RFC 3986. A regra é simples: qualquer byte que não seja um caractere não reservado e codificado como um sinal de porcentagem seguido de dois dígitos hexadecimais maiúsculos representando o valor desse byte.

Caracteres não reservados que nunca precisam de codificação:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o p q r s t u v w x y z
0 1 2 3 4 5 6 7 8 9 - _ . ~

Todo o resto (espaços, pontuação, não ASCII, caracteres de controle) deve ser codificado quando aparecer em uma posição onde o analisador URL o interpretaria erroneamente.

Por que Caracteres Especiais Quebram URLs

Uma URL tem sintaxe definida. Caracteres como ?, &, =, #, / e : tem papeis específicos na estrutura da URL:

• ? separa o caminho da string de consulta
• & separa parametros de consulta uns dos outros
• = separa uma chave de parametro do seu valor
• # inicia o identificador de fragmento
• / separa segmentos de caminho
• : separa o esquema do resto

Se um valor de parametro de consulta contiver qualquer um desses caracteres sem codificação, o analisador URL os le como marcadores estruturais é o valor do parametro e truncado ou mal interpretado.

encodeURI vs encodeURIComponent

encodeURI é para codificar uma URL completa. Ela deixa intactos todos os caracteres que são significativos na estrutura URL:

encodeURI("https://example.com/search?q=ola mundo")
// "https://example.com/search?q=ola%20mundo"
// Nota: ? e = NÃO são codificados

encodeURIComponent é para codificar um valor que sera incorporado dentro de um componente URL (um valor de parametro de consulta, um segmento de caminho ou um fragmento). Ela codifica tudo que pode ser confundido com estrutura URL:

encodeURIComponent("ola mundo&tchau=mundo")
// "ola%20mundo%26tchau%3Dmundo"
// Nota: & e = SÃO codificados

Para construir strings de consulta, sempre use encodeURIComponent tanto em chaves quanto em valores:

const params = {
  q: "café & resumo",
  redirect: "https://example.com/path?id=42"
};

const queryString = Object.entries(params)
  .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
  .join("&");

Ou use URLSearchParams, que lida com codificação automaticamente:

const params = new URLSearchParams({
  q: "café & resumo",
  redirect: "https://example.com/path?id=42"
});
params.toString();

O Debaté + vs %20 para Espacos

Duas especificações codificam espaços de forma diferente:

• RFC 3986 (URI): Espaco -> %20
• Codificação de formularios HTML (application/x-www-form-urlencoded): Espaco -> +

Ambas são amplamente aceitas por servidores web. Em Python, a diferença e explicita:

from urllib.parse import quote, quote_plus

quote("ola mundo")       # "ola%20mundo"  (RFC 3986)
quote_plus("ola mundo")  # "ola+mundo"    (codificação de formulario)

Para desenvolvimento de API, prefira %20. Para manipulação de formularios HTML, espere + e use o decodificador apropriado.

Codificando Caracteres Não ASCII

Caracteres não ASCII passam por duas etapas:

1. Codificar o caractere como bytes UTF-8.
2. Codificar percentualmente cada byte.

A letra e (U+00E9) é um ponto de código, mas dois bytes UTF-8: 0xC3 e 0xA9. A forma codificada percentualmente e %C3%A9.

O emoji 😀 (U+1F600) e quatro bytes UTF-8 (0xF0 0x9F 0x98 0x80), codificando para %F0%9F%98%80.

Você pode verificar no console do navegador:

encodeURIComponent("e")    // "%C3%A9"
encodeURIComponent("😀")  // "%F0%9F%98%80"

UTF-8 é o padrão universal para codificação percentual de caracteres não ASCII.

Erros Comuns

Codificar a URL completa em vez de apenas valores de parametro

Se você passar https://example.com/path?q=ola para encodeURIComponent, os dois pontos, barras e ponto de interrogação serão codificados, produzindo uma string quebrada.

Esquecer de codificar chaves de parametro

Chaves também podem conter caracteres especiais se vierem de entrada do usuário. Codifique tanto chaves quanto valores.

Dupla codificação

Se você receber uma string codificada URL e codifica-la novamente, todo % se torna %25. O resultado decodificado contera sequencias %XX literais em vez dos caracteres pretendidos.

Assumir que o servidor lidara com entrada malformada

Alguns servidores são lenientes e decodificam sequencias % que aparecem em entrada não codificada. Outros são rigidos. Não confie na leniencia do servidor. Codifique corretamente no cliente.