Guía de Codificación URL

La codificación URL — formalmente percent-encoding — es el mecanismo que la web usa para transportar caracteres especiales dentro de URLs. Cada vez que un usuario introduce una búsqueda con espacios, cada vez que una API recibe un query con un ampersand, cada vez que una redirección preserva un nombre de archivo no-ASCII, el percent-encoding es lo que hace que funcione. Esta guía cubre las reglas, las dos APIs de JavaScript y los errores que te morderán.

Reservados vs no reservados

El RFC 3986 divide los caracteres en dos grupos. Los no reservados — A–Z, a–z, 0–9 y - _ . ~ — siempre son seguros. Los reservados — : / ? # [ ] @ ! $ & ' ( ) * + , ; = — tienen significado estructural (separar esquema de ruta, clave de valor, componente de componente) y deben codificarse cuando aparecen como dato en vez de estructura. Todo lo demás (espacios, Unicode, bytes binarios) siempre debe codificarse.

La regla de codificación

Cada byte que hay que escapar se convierte en un signo de porcentaje seguido de dos dígitos hexadecimales. Un espacio es %20, un ampersand es %26, un guion largo son tres bytes UTF-8 y por tanto tres secuencias: %E2%80%94. Los decodificadores revierten el proceso byte a byte.

encodeURI vs encodeURIComponent

JavaScript incluye dos funciones que confunden a todos al menos una vez. encodeURI(str) asume que str es una URL completa y respeta los reservados (barras, dos puntos, interrogantes sobreviven). encodeURIComponent(str) asume que str es un único componente — un segmento de ruta o un valor — y escapa agresivamente todo reservado. Regla práctica: si construyes un valor de query para ?clave=valor, usa siempre encodeURIComponent. Si tienes una URL completa y sólo quieres limpiar lo que no sea URL, usa encodeURI.

Errores comunes

• Doble codificación — codificar algo ya codificado. %20 se convierte en %2520, el decodificador ve un %20 literal y la URL pierde el espacio.
• Función equivocada en la parte equivocada — usar encodeURIComponent sobre una URL entera destroza el separador del esquema.
• Olvidar los espacios en form-data — los POST HTML con application/x-www-form-urlencoded codifican los espacios como +, no como %20. Para todo lo demás, usa %20.
• Suponer que no es UTF-8 — la codificación URL moderna es siempre UTF-8 primero y después percent-encoding. Sistemas heredados que usaron Latin-1 o Shift_JIS parecen iguales pero generan basura en no-ASCII.

Cuándo usar cada una

Usa encodeURIComponent cada vez que compones un valor de query dinámicamente. Usa encodeURI cuando tengas una URL introducida por el usuario (quizás con Unicode en la ruta) y quieras hacerla segura sin romper su estructura. Decodifica con decodeURIComponent salvo que quieras preservar reservados — en cuyo caso probablemente no deberías haberlos codificado.