Como Codificar URLs - Guia Completo | DevTools.at

O Que é Codificação URL?

Codificação URL é o processo de converter caracteres em um formato que pode ser transmitido com segurança através de URLs. URLs têm limitações estritas sobre quais caracteres podem aparecer nelas—apenas caracteres ASCII não reservados (a-z, A-Z, 0-9, e alguns símbolos como - _ . ~) são seguros de usar diretamente. Qualquer outro caractere deve ser codificado. A razão para estas restrições está em como URLs funcionam. Certos caracteres têm significados especiais em URLs: ? marca o início de parâmetros de consulta, & separa múltiplos parâmetros, = separa nomes de parâmetros de valores, # marca fragmentos, : separa esquemas de hosts, / separa componentes de caminho. Se você quiser usar estes caracteres como dados reais (não como seus significados especiais), deve codificá-los. A codificação de porcentagem funciona substituindo caracteres especiais por % seguido de dois dígitos hexadecimais representando o valor de byte ASCII do caractere. Espaços tornam-se %20 (20 é o hex para 32, o código ASCII de espaço). Dois pontos tornam-se %3A, e comercial torna-se %26, sinais de igual tornam-se %3D, e assim por diante. Este formato %XX garante que a URL contenha apenas caracteres seguros. Caracteres não-ASCII (como acentos, emoji, caracteres chineses) devem primeiro ser codificados como UTF-8, então cada byte é codificado por porcentagem. O caractere é "São" torna-se "S%C3%A3o" porque ã codifica em UTF-8 como bytes C3 A3, cada um então codificado por porcentagem. Isto permite que URLs transportem qualquer caractere Unicode de forma confiável. Diferentes partes de uma URL têm diferentes regras de codificação. Componentes de caminho, parâmetros de consulta, identificadores de fragmento e informações de autenticação cada um têm conjuntos ligeiramente diferentes de caracteres permitidos. Uma URL adequadamente codificada respeita estas distinções, embora na prática codificar tudo exceto caracteres totalmente seguros (a-z, A-Z, 0-9, - _ . ~) funciona universalmente. Entender codificação URL é essencial para desenvolvimento web. URLs malformadas causam requisições com falha, vulnerabilidades de segurança e comportamento imprevisível de aplicação. Aplicar codificação URL corretamente garante que seus dados sobrevivam à transmissão intactos através de navegadores, servidores e proxies.

Quando Codificar URLs

Saber quando aplicar codificação URL é tão importante quanto saber como. Codificar demais ou de menos ambos causam problemas. Aqui estão as diretrizes essenciais para quando codificar. Sempre codifique valores de parâmetro de consulta. Quando você está construindo strings de consulta para APIs ou formulários, qualquer valor fornecido por usuário ou conteúdo dinâmico deve ser codificado. Se um usuário pesquisa "sapatos & meias", a consulta deve tornar-se ?search=sapatos%20%26%20meias não ?search=sapatos & meias (que seria interpretado como dois parâmetros separados). Entradas de usuário são especialmente perigosas porque podem conter qualquer caractere. Codifique segmentos de caminho contendo caracteres especiais. Se você está construindo URLs dinamicamente e um nome de arquivo ou ID contém espaços, símbolos ou caracteres não-ASCII, codifique-o. /files/meu documento.pdf deve tornar-se /files/meu%20documento.pdf. No entanto, não codifique as barras que separam segmentos de caminho—elas são parte da estrutura da URL. Não codifique duas vezes. Um erro comum é codificar dados que já estão codificados. Se você tem "hello%20world" e codifica novamente, torna-se "hello%2520world" (o % torna-se %25). Quando decodificado uma vez, você obtém "hello%20world" ao invés de "hello world". Frameworks web modernos frequentemente codificam automaticamente—saiba o que suas ferramentas fazem. Não codifique URLs completas. Se você tem uma URL completa como "https://example.com/path?query=value", não a codifique por porcentagem como um todo. Codifique apenas os componentes individuais conforme necessário. Codificar toda a URL transformaria : em %3A e / em %2F, quebrando a estrutura da URL completamente. Use funções específicas de componente quando disponíveis. JavaScript tem encodeURIComponent() para valores de parâmetro e encodeURI() para URLs completas. encodeURIComponent() codifica tudo exceto a-z, A-Z, 0-9, - _ . ~ * ! ' ( ). encodeURI() preserva :/?#[]@!$&'()*+,;= já que estes têm significados especiais em URLs. Use encodeURIComponent() para valores de parâmetro individual, encodeURI() para URLs completas que você está construindo. Codifique antes de concatenar em URLs. Pegue valores dinâmicos, codifique-os, então junte-os em strings de URL. Não construa a URL primeiro e então tente codificá-la—você perderá a distinção entre delimitadores estruturais e dados. Padrão incorreto: codificar("/path/" + userInput). Padrão correto: "/path/" + codificar(userInput). Frameworks web modernos e bibliotecas HTTP frequentemente lidam com codificação automaticamente. Ao usar fetch(), axios, ou construtores de URL, eles tipicamente codificam parâmetros para você. Ainda entenda os princípios para casos onde você precisa lidar com URLs manualmente ou depurar problemas.

Armadilhas Comuns

Codificação URL parece direta mas tem várias armadilhas que pegam até desenvolvedores experientes. Evitar estas armadilhas comuns previne bugs sutis e vulnerabilidades de segurança. Codificação dupla é extremamente comum. Acontece quando você codifica dados que já estão codificados. Frameworks web frequentemente codificam automaticamente parâmetros de consulta. Se você codifica manualmente antes de passá-los, eles são codificados duas vezes. "hello world" → "hello%20world" (correto) → "hello%2520world" (codificado duas vezes). Sempre verifique se suas ferramentas codificam automaticamente antes de codificar manualmente. Codificar caracteres de delimitador de URL quebra URLs. Se você codificar uma URL completa com encodeURIComponent(), os dois pontos em https: tornam-se %3A, as barras tornam-se %2F, e você obtém https%3A%2F%2Fexample.com—completamente inútil. Use encodeURI() para URLs completas ou, melhor ainda, codifique apenas os componentes de valor. Esquecer de decodificar no lado do servidor causa problemas. Se você codifica no cliente mas não decodifica no servidor, você processa dados codificados como se fossem dados reais. Geralmente frameworks web decodificam automaticamente parâmetros de consulta, mas decodificação manual pode ser necessária para processamento de caminho ou cabeçalhos. Caracteres especiais em nomes de parâmetro são frequentemente esquecidos. A maioria dos desenvolvedores lembra de codificar valores de parâmetro mas esquece que nomes de parâmetro podem precisar de codificação também. Se você tem uma chave como "user.name", deve codificá-la: user%2Ename=John. Na prática, evite caracteres especiais em nomes de parâmetro inteiramente. Codificar + vs %20 para espaços causa confusão. Na codificação de formulário HTML (application/x-www-form-urlencoded), espaços são codificados como + ao invés de %20. Em parâmetros de consulta URL, espaços devem ser %20. encodeURIComponent() usa %20. Alguns sistemas aceitam ambos, outros não. Para compatibilidade máxima, use %20. Caracteres internacionais requerem cuidado extra. URLs tecnicamente suportam apenas ASCII. Caracteres não-ASCII devem ser UTF-8 codificados então codificados por porcentagem. A maioria dos navegadores modernos lidam com isto automaticamente, mas sistemas mais antigos podem falhar. Para compatibilidade máxima, use apenas ASCII em URLs ou teste minuciosamente com caracteres internacionais. Dependência excessiva em codificação para segurança é perigoso. Enquanto codificação adequada previne injeção de URL, não substitui validação de entrada adequada, sanitização e outras práticas de segurança. Codificar entrada maliciosa não a torna segura—apenas a torna transmissível. Sempre valide e sanitize entrada além de codificá-la. Não entender quando frameworks codificam automaticamente leva a sobre-codificação ou sub-codificação. Bibliotecas HTTP modernas, construtores de URL e frameworks web frequentemente lidam com codificação automaticamente. Leia a documentação. Teste com caracteres especiais. Entenda o que é automático vs. manual no seu stack.

Codificação URL: Guia Completo

O Que é Codificação URL?

Quando Codificar URLs

Armadilhas Comuns

Testar a Ferramenta

Saiba Mais

O Que é Codificação URL?

Codificação URL vs Codificação HTML

Perguntas Frequentes