encodeURIComponent vs encodeURI: cuándo usar cada una

Las dos funciones de codificación de URL en JavaScript

JavaScript ofrece dos funciones integradas para codificar URLs: encodeURI() y encodeURIComponent(). Aunque puedan parecer similares, usar la incorrecta puede provocar URLs rotas, vulnerabilidades de seguridad o corrupción de datos. Entender la diferencia es fundamental para cualquier desarrollador web.

encodeURI(): para URIs completas

encodeURI() está diseñada para codificar una URI completa. Codifica todos los caracteres excepto los que tienen un significado especial dentro de la estructura de una URI. En concreto, NO codifica:

• Caracteres reservados: ; , / ? : @ & = + $ #
• Caracteres no reservados: letras, dígitos, - _ . ! ~ * ' ( )

// encodeURI preserva la estructura de la URI
encodeURI('https://example.com/path?q=hello world&lang=en')
// "https://example.com/path?q=hello%20world&lang=en"
// Nota: :, /, ?, =, & NO se codifican

encodeURIComponent(): para componentes de una URI

encodeURIComponent() está diseñada para codificar un único componente de una URI (como el valor de un parámetro de consulta). Codifica TODOS los caracteres excepto:

• Caracteres no reservados: letras, dígitos, - _ . ! ~ * ' ( )

// encodeURIComponent codifica todo excepto los caracteres no reservados
encodeURIComponent('hello world & goodbye')
// "hello%20world%20%26%20goodbye"
// Nota: & SÍ se codifica porque es un carácter reservado

// Uso para el valor de un parámetro de consulta
const url = 'https://example.com/search?q=' +
  encodeURIComponent('cats & dogs');
// "https://example.com/search?q=cats%20%26%20dogs"

Errores comunes

Error 1: usar encodeURI para valores de consulta

Si usas encodeURI() para codificar el valor de un parámetro de consulta que contiene un ampersand, el ampersand no se codificará y se interpretará como separador de parámetros, rompiendo así tu URL.

// INCORRECTO: el ampersand en el valor rompe la URL
const badUrl = 'https://api.example.com/search?q=' +
  encodeURI('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20&%20Jerry"
// El servidor interpreta: q="Tom " y un parámetro " Jerry" sin valor

// CORRECTO: usa encodeURIComponent
const goodUrl = 'https://api.example.com/search?q=' +
  encodeURIComponent('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20%26%20Jerry"
// El servidor interpreta correctamente: q="Tom & Jerry"

Error 2: usar encodeURIComponent para URLs completas

Si usas encodeURIComponent() sobre una URL entera, codificará los dos puntos, las barras, los signos de interrogación y demás caracteres estructurales, dejando la URL completamente inservible.

Cuándo usar cada una: la regla sencilla

• Usa encodeURI() cuando tengas una URI completa que pueda contener espacios o caracteres no ASCII, pero cuya estructura sea válida.
• Usa encodeURIComponent() cuando estés codificando un único fragmento de datos que se colocará dentro de una URI (valores de parámetros de consulta, segmentos de ruta, etc.).

La alternativa con URLSearchParams

El JavaScript moderno ofrece la API URLSearchParams, que gestiona la codificación de forma automática. A menudo es el mejor enfoque para construir cadenas de consulta:

const params = new URLSearchParams({
  q: 'Tom & Jerry',
  category: 'cartoons & animation',
  page: '1'
});

const url = 'https://example.com/search?' + params.toString();
// "https://example.com/search?q=Tom+%26+Jerry&category=cartoons+%26+animation&page=1"

// O usa la API URL
const url2 = new URL('https://example.com/search');
url2.searchParams.set('q', 'Tom & Jerry');
console.log(url2.toString());