O Guia Completo de Codificação de URL

O que é a Codificação de URL?

A codificação de URL, também conhecida como percent-encoding, é um mecanismo para codificar informações em um Uniform Resource Identifier (URI) sob determinadas circunstâncias. Embora seja conhecida como codificação de URL, ela também é usada de forma mais ampla dentro do conjunto principal de Uniform Resource Identifier (URI), que inclui tanto o Uniform Resource Locator (URL) quanto o Uniform Resource Name (URN).

A codificação é necessária porque as URLs só podem ser enviadas pela Internet usando o conjunto de caracteres ASCII. Como as URLs frequentemente contêm caracteres fora do conjunto ASCII, a URL precisa ser convertida em um formato ASCII válido. A codificação de URL substitui caracteres ASCII inseguros por um % seguido de dois dígitos hexadecimais.

Como Funciona a Percent-Encoding?

O mecanismo de percent-encoding funciona convertendo cada caractere que precisa ser codificado em um ou mais bytes. Cada byte é então representado por um sinal de porcentagem seguido de dois dígitos hexadecimais. Os dígitos hexadecimais representam o valor em bytes do caractere na codificação especificada (normalmente UTF-8).

Por exemplo, o caractere de espaço (valor ASCII 32, hex 20) torna-se %20. O e comercial & (valor ASCII 38, hex 26) torna-se %26. Caracteres não-ASCII, como e com acento agudo, são primeiro codificados em sua sequência de bytes UTF-8 e, em seguida, cada byte é submetido à percent-encoding.

Caracteres Reservados vs. Não Reservados

A RFC 3986 define duas categorias de caracteres para URIs: reservados e não reservados. Os caracteres não reservados incluem letras maiúsculas e minúsculas (A-Z, a-z), dígitos (0-9), hifens (-), pontos (.), sublinhados (_) e tis (~). Esses caracteres podem ser incluídos em um URI sem codificação.

Os caracteres reservados têm significados especiais na sintaxe de URL. Entre eles estão: :, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ; e =. Quando esses caracteres são usados em um componente de URI fora de sua finalidade reservada, eles devem passar por percent-encoding.

Codificação de URL em Diferentes Linguagens

JavaScript

O JavaScript fornece dois pares de funções para codificação de URL: encodeURI() / decodeURI() para codificar URIs completos e encodeURIComponent() / decodeURIComponent() para codificar componentes individuais de URI. A principal diferença é que encodeURI() preserva os caracteres reservados que têm significado especial em URIs (como /, ?, #), enquanto encodeURIComponent() codifica todos os caracteres não alfanuméricos.

Python

O módulo urllib.parse do Python fornece quote() e unquote() para codificação/decodificação básica, além de urlencode() para codificar dicionários em query strings. A função quote() aceita um parâmetro opcional safe para especificar caracteres que não devem ser codificados.

PHP

O PHP oferece urlencode(), que codifica espaços como + (seguindo o formato application/x-www-form-urlencoded), e rawurlencode(), que codifica espaços como %20 (seguindo a RFC 3986). Para decodificação, use urldecode() e rawurldecode(), respectivamente.

Melhores Práticas

• Sempre codifique a entrada do usuário antes de incluí-la em URLs
• Use encodeURIComponent() para codificar valores de parâmetros de query em JavaScript
• Use encodeURI() apenas ao codificar um URI completo
• Seja consistente com sua abordagem de codificação em toda a aplicação
• Sempre decodifique as URLs no lado do servidor antes de processá-las
• Teste sua codificação com caracteres especiais, incluindo Unicode
• Não codifique URLs duas vezes -- sempre verifique se uma string já está codificada