Codificação de URL explicada: codificação percentual, encodeURI vs encodeURIComponent e o bug% 2520
Todo desenvolvedor que construiu uma URL com entrada do usuário atingiu o seguinte: um termo de pesquisa com um espaço ou um E comercial quebra o link e, de repente, metade da consulta está faltando no servidor. A correção é a codificação de URL, também chamada de codificação percentual, mas vem com duas funções que são fáceis de confundir e um bug que produz o desconcertante% 2520 em seus links. Este guia esclarece tudo.
Por que os URLs precisam de codificação
Os URLs só podem conter um conjunto limitado de caracteres, definido por um padrão chamado RFC 3986. Esse conjunto é basicamente caracteres não reservados, letras, dígitos e alguns símbolos como hífen e sublinhado, além de um punhado de caracteres reservados que possuem significado estrutural especial, como? para iniciar uma consulta, & para separar parâmetros, = para emparelhar uma chave com um valor, / para segmentos de caminho e # para um fragmento. Qualquer coisa fora desse conjunto, espaços, letras acentuadas, emoji ou um símbolo reservado usado como dados em vez de estrutura, deve ser codificado ou o URL será quebrado.
A codificação percentual faz isso substituindo um caractere inseguro por um sinal de porcentagem seguido por seu valor de byte hexadecimal de dois dígitos. Um espaço se torna% 20. Um E comercial se torna %26. Uma arroba se torna% 40. Na outra extremidade, o servidor os decodifica de volta aos caracteres originais. Todo o sistema existe para que texto arbitrário possa circular dentro da estrutura rígida de uma URL sem ser confundido com parte dessa estrutura.
O problema central: dados versus estrutura
Aqui está a situação que causa a maioria dos bugs. Imagine uma busca pelo texto literal “gatos e cachorros”. Se você colocar isso diretamente em uma string de consulta como q=cats & Dogs, o & será lido como um separador de parâmetro, o servidor verá um parâmetro q=cats e um segundo parâmetro sem sentido, Dogs, e sua pesquisa será interrompida. O espaço também causa problemas. O e comercial precisa se tornar %26 e o espaço %20 para que o servidor entenda que eles fazem parte do valor, não da estrutura da URL. Codificação é como você diz "este caractere é um dado, não um delimitador".
encodeURI vs encodeURIComponent
JavaScript oferece duas funções de codificação, e escolher a errada é um dos erros de URL mais comuns. A diferença é o que eles consideram “seguro” e deixam de lado.
encodeURIComponent codifica tudo reservado, incluindo / ? & = # e mais. Destina-se a codificar um único valor que você está inserindo em uma URL, um valor de parâmetro de consulta, um termo de pesquisa, um alvo de redirecionamento. Use-o para as peças. encodeURI, por outro lado, deixa deliberadamente os caracteres da estrutura da URL (/ ? & =) em paz, porque seu objetivo é codificar uma URL inteira já montada, mantendo-a funcional. Use-o para tudo, raramente.
A regra geral: se você estiver codificando um valor que está dentro de uma URL, use encodeURIComponent. Se você estiver codificando uma URL completa e quiser apenas corrigir caracteres ilegais perdidos sem quebrar sua estrutura, use encodeURI. Em caso de dúvida, você quase sempre deseja encodeURIComponent, porque quase sempre está codificando um valor.
O bug %2520: codificação dupla
Este confunde a todos na primeira vez. Você vê %2520 em uma URL onde esperava %20 e o link está quebrado. Aqui está o que aconteceu: uma string que já estava codificada foi codificada uma segunda vez. A primeira codificação transformou um espaço em% 20. A segunda codificação codificou o próprio sinal de porcentagem, % se torna %25, transformando %20 em %2520. Agora o servidor o decodifica uma vez para% 20 (literalmente o texto "% 20") em vez de um espaço, e tudo o que está abaixo está errado.
A causa quase sempre é codificar um valor que já foi codificado, por exemplo, construir uma URL a partir de uma string que já veio codificada em URL e, em seguida, executá-la novamente no codificador. A regra para evitá-lo: codifique apenas texto bruto e não codificado. Nunca codifique um URL ou valor que já esteja codificado. Se você não tiver certeza se uma string já está codificada, decodifique-a primeiro e depois codifique-a exatamente uma vez.
A ambigüidade do sinal de mais
Mais uma armadilha. Em uma string de consulta, um sinal de mais (+) às vezes é interpretado como um espaço, um legado da antiga codificação de formulário HTML, application/x-www-form-urlencoded. Mas em um caminho de URL, + é uma vantagem literal. Essa inconsistência significa que um + em seus dados pode ser lido como um espaço em um lugar e um sinal de mais em outro. A medida segura é sempre codificar um espaço como% 20, o que é inequívoco em todos os lugares, em vez de depender de +. Se você vir espaços se transformando em vantagens ou vice-versa, essa ambigüidade geralmente é a culpada.
A lição prática
Codifique os valores que você coloca em URLs, use encodeURIComponent para esses valores, codifique apenas texto bruto para evitar o bug de codificação dupla %2520 e prefira %20 em vez de + para espaços. Quando você precisa criar ou inspecionar um URL manualmente, um codificador e decodificador rápido permite ver exatamente o que uma string se torna e detectar esses problemas antes que eles sejam enviados.