Codificador/Decodificador URL

A codificação URL (também chamada de codificação porcentual) é um mecanismo para converter caracteres em um formato que pode ser transmitido com segurança em uma URL. Como as URLs só podem conter certos caracteres do conjunto ASCII, outros caracteres (como acentos, espaços e símbolos especiais) devem ser codificados no formato %XX, onde XX é o valor hexadecimal do caractere. Por exemplo: um espaço é codificado como %20, e o caractere ç é codificado como %C3%A7. A codificação URL transforma caracteres em uma forma segura para transmissão dentro de URLs. Espaços, texto não ASCII, caracteres reservados e símbolos podem ser percent-encoded conforme o contexto. O ponto principal é distinguir URL completa, segmento de caminho, parâmetro de query, corpo de formulário ou fragmento, pois cada posição tem regras diferentes. Codificação dupla ou ausente pode quebrar links, requisições de API, assinaturas, redirecionamentos e parâmetros de busca.

A codificação URL (codificação percentual) é definida pela RFC 3986 §2.1 e transforma caracteres no formato %XX, onde XX é a representação hexadecimal maiúscula de dois dígitos do valor do byte em UTF-8. A RFC define duas classes de caracteres: caracteres não reservados (A-Z a-z 0-9 - _ . ~) que nunca são codificados, e caracteres reservados (gen-delims : / ? # [ ] @ e sub-delims ! $ & ' ( ) * + , ; =) cuja codificação depende do contexto — eles carregam significado estrutural em alguns componentes de URL, mas são dados literais em outros. O JavaScript fornece duas funções nativas com escopos diferentes. encodeURIComponent() codifica todo caractere exceto A-Z a-z 0-9 - _ . ! ~ * ' ( ) — esta é a escolha correta para codificar valores individuais de parâmetros de consulta, segmentos de caminho e identificadores de fragmento. encodeURI() preserva adicionalmente os caracteres estruturais : / ? # [ ] @ ! $ & ' ( ) * + , ; = e é projetada para codificar URIs completas mantendo sua estrutura sintática intacta. A distinção crítica é que encodeURIComponent() codifica / e &, o que quebraria uma URL se aplicado à string inteira, enquanto encodeURI() os preserva. O tratamento de espaços é a armadilha de interoperabilidade mais comum. A RFC 3986 especifica %20 como a codificação percentual canônica para o caractere de espaço (U+0020). Entretanto, o tipo MIME application/x-www-form-urlencoded (usado por envios de formulário HTML desde o HTML 4.01) codifica espaços como +. Os dois não são intercambiáveis: um servidor esperando %20 interpretará + literalmente, e um servidor esperando + tratará %20 como um sinal de porcentagem literal seguido de 20. A ferramenta usa encodeURIComponent() que produz %20, compatível com a RFC 3986. Usuários decodificando payloads x-www-form-urlencoded (de corpos POST ou strings de consulta analisadas por middleware legado) devem estar cientes dessa diferença. O tratamento de caracteres multibyte é automático, mas vale a pena entender: a string de entrada é primeiro codificada em bytes UTF-8, depois cada byte é individualmente percent-encodado. Um caractere CJK como '你' (U+4F60) ocupa 3 bytes UTF-8 (E4 BD A0), produzindo %E4%BD%A0. Se o servidor analisar com um charset diferente como GBK, o mesmo caractere é codificado como %C4%E3 (2 bytes), e o resultado decodificado será ilegível a menos que ambas as partes concordem com UTF-8. A codificação dupla é outro bug comum: %2520 significa um sinal de porcentagem literal (%25) seguido de 20, indicando que a entrada já estava percent-encodada e foi codificada uma segunda vez. O modo de decodificação captura sequências malformadas (%XX incompleto) e exibe o erro em vez de produzir silenciosamente lixo.

• encodeURIComponent vs encodeURI: encodeURIComponent codifica / ? & # e é correto para valores de consulta, segmentos de caminho e fragmentos; encodeURI preserva esses caracteres estruturais e é correto para URLs completas — usar a função errada é o bug de codificação URL mais comum.
• Conjuntos de caracteres reservados da RFC 3986: gen-delims (: / ? # [ ] @) carregam sintaxe de URL; sub-delims (! $ & ' ( ) * + , ; =) podem ser delimitadores ou dados dependendo do componente da URL — o contexto determina se um caractere reservado é percent-encodado.
• Codificação de espaço: A forma canônica da RFC 3986 é %20 (produzida por encodeURIComponent); application/x-www-form-urlencoded usa + (padrão de formulário HTML) — os dois são semanticamente incompatíveis e misturá-los quebra analisadores do lado do servidor.
• Codificação multibyte UTF-8: '你' (U+4F60) → bytes UTF-8 E4 BD A0 → %E4%BD%A0 (3 octetos percent-encodados); o mesmo caractere em GBK → %C4%E3 (2 octetos) — concordância de charset entre cliente e servidor é obrigatória para texto não ASCII.
• Detecção de codificação dupla: %2520 decodifica primeiro para %20 e depois para espaço — a saída do modo de decodificação revela esse padrão; sequências malformadas como %ZZ ou %2 (incompleto) são capturadas e reportadas como erros.
• IRI (RFC 3987): Identificadores de Recursos Internacionalizados permitem caracteres Unicode diretamente em URLs; navegadores exibem a forma decodificada na barra de endereço, mas transmitem a forma UTF-8 percent-encodada na rede — o modo de codificação da ferramenta mostra o que realmente passa pelo HTTP.
• Tratamento de erros de decodeURIComponent: Passar uma string com uma sequência percentual incompleta (% seguido de menos de 2 dígitos hexadecimais) lança um URIError — a ferramenta envolve a chamada em try/catch e exibe a mensagem de erro em vez de retornar silenciosamente uma string vazia.