Codificação de URL de Caracteres Especiais: Uma Referência para Desenvolvedores
Uma referência completa para a codificação de URL de caracteres especiais, incluindo espaços, e comerciais, unicode e muito mais.
Caracteres Especiais em URLs
As URLs possuem uma sintaxe rígida definida pela RFC 3986. Muitos caracteres têm significados especiais ou não são permitidos em determinadas partes de uma URL. Entender como codificar corretamente esses caracteres é essencial para construir aplicações web e APIs confiáveis.
O Caractere de Espaço
O caractere de espaço é o mais comumente codificado. No entanto, ele pode ser codificado de duas maneiras, dependendo do contexto:
%20- Percent-encoding da RFC 3986, usado em caminhos de URL e na maioria dos contextos+- Usado no formatoapplication/x-www-form-urlencoded(envios de formulários HTML)
Ao construir URLs de forma programática, prefira %20 por questão de consistência. Ao montar dados de formulário, a notação + é o padrão.
Análise Aprofundada dos Caracteres Reservados
O E Comercial (&)
O e comercial separa os parâmetros de consulta. Quando um e comercial aparece no valor de um parâmetro, ele deve ser codificado como %26 para evitar que seja interpretado como um separador. Em contextos HTML, ele também deve ser codificado como entidade na forma &.
O Ponto de Interrogação (?)
O ponto de interrogação separa o caminho da query string. Se um ponto de interrogação aparecer no valor de um parâmetro, ele deve ser codificado como %3F. Observe que encodeURI() NÃO codifica pontos de interrogação, enquanto encodeURIComponent() codifica.
A Cerquilha (#)
O símbolo de cerquilha inicia o identificador de fragmento. Em URLs, qualquer # no valor de um parâmetro de consulta deve ser codificado como %23, ou o navegador interpretará tudo o que vier depois dele como um identificador de fragmento e não o enviará ao servidor.
A Barra (/)
As barras separam os segmentos do caminho. Quando uma barra aparece no valor de um segmento de caminho (como um nome de arquivo que contém uma barra), ela deve ser codificada como %2F. Observe que alguns servidores podem decodificar %2F e ainda assim tratá-la como um separador de caminho.
Caracteres Unicode
Os caracteres não-ASCII são codificados convertendo-os primeiro para sua sequência de bytes UTF-8 e, em seguida, aplicando percent-encoding a cada byte. Veja alguns exemplos:
- Latin e com acento agudo (e) → UTF-8: 0xC3 0xA9 →
%C3%A9 - Caractere chinês (zhong) → UTF-8: 0xE4 0xB8 0xAD →
%E4%B8%AD - Emoji (globo) → UTF-8: 0xF0 0x9F 0x8C 0x8D →
%F0%9F%8C%8D
Codificação em Diferentes Componentes da URL
| Componente | Deve Codificar | Exemplo |
|---|---|---|
| Segmento de caminho | Espaços, ?, # e não-ASCII | /path/my%20file |
| Chave de consulta | =, &, #, +, espaços | my%20key=value |
| Valor de consulta | &, #, +, espaços, = | key=hello%20world |
| Fragmento | Espaços e não-ASCII | #section%20one |
Armadilhas Comuns
- Esquecer de codificar
#em valores de consulta (o restante da URL é descartado silenciosamente) - Codificar duas vezes strings já codificadas (resultando em
%2520em vez de%20) - Usar
encodeURI()em vez deencodeURIComponent()para valores de parâmetros - Não codificar
+em valores de consulta (ele acaba sendo decodificado como um espaço) - Presumir que todos os servidores tratam
%2Fda mesma forma em caminhos