Codificador URL

A URL foi inventada por Tim Berners-Lee em 1991, junto com o HTML e o HTTP, como parte do projeto que se tornaria a World Wide Web. O formato que vemos hoje — aquele `https://exemplo.com/pagina?parametro=valor&outro=123` — foi formalizado no RFC 1738 em 1994 e refinado até o RFC 3986 em 2005. Existe um problema intrínseco no design original: a URL precisa ser transmitida como texto ASCII puro, mas o mundo fala centenas de idiomas com acentos, caracteres especiais e scripts completamente diferentes do alfabeto latino. A solução foi o percent-encoding: qualquer byte que não seja um caractere ASCII seguro é representado como `%` seguido de dois dígitos hexadecimais. A letra `ã` em UTF-8, por exemplo, ocupa dois bytes — 0xC3 e 0xA3 — e vira `%C3%A3`.

A parte que quase todo desenvolvedor aprende da forma difícil é a diferença entre `encodeURIComponent` e `encodeURI`. A função `encodeURI` preserva os caracteres estruturalmente significativos numa URL — `/`, `?`, `#`, `&`, `=` — porque foi feita para codificar uma URL completa. Já `encodeURIComponent` codifica tudo isso também, porque foi feita para codificar um valor dentro da URL, onde `/`, `?` e `&` não podem aparecer sem codificação. Quando você monta uma query string manualmente com concatenação de string, qualquer valor contendo `&`, `=`, `+` ou `#` vai silenciosamente quebrar o parsing no servidor. Isso acontece muito mais do que deveria, especialmente com nomes que contêm apóstrofo, espaços ou — a campeã dos bugs de encoding — o `@` em endereços de e-mail passados como parâmetro.

Um cuidado importante ao trabalhar com encoding de URL é o double encoding — codificar algo que já está codificado. Se você recebe uma URL que já contém `%20` e passa por `encodeURIComponent`, o `%` vira `%25` e o resultado final é `%2520`, que o servidor interpreta como a string literal `%20` em vez de um espaço. Outro ponto que confunde é a diferença entre `%20` e `+` para representar espaços: formulários HTML usam `+` no formato `application/x-www-form-urlencoded`, mas o RFC 3986 especifica `%20`. A maioria dos servidores aceita os dois, mas em contextos como assinaturas de API — AWS, por exemplo — a diferença é crítica e pode gerar erros de autenticação notoriamente difíceis de depurar.

URLs were invented by Tim Berners-Lee in 1991 alongside HTML and HTTP as part of the project that would become the World Wide Web. The format we use today — that `https://example.com/page?param=value&other=123` structure — was formalized in RFC 1738 in 1994 and refined through RFC 3986 in 2005. There is an inherent tension in the original design: URLs must be transmitted as pure ASCII text, yet the world communicates in hundreds of languages with accents, special characters, and scripts entirely different from the Latin alphabet. The solution was percent-encoding: any byte that is not a safe ASCII character is represented as `%` followed by two hexadecimal digits. The letter `ã` in UTF-8, for instance, occupies two bytes — 0xC3 and 0xA3 — and becomes `%C3%A3`.

The part almost every developer learns the hard way is the difference between `encodeURIComponent` and `encodeURI`. The `encodeURI` function preserves structurally significant URL characters — `/`, `?`, `#`, `&`, `=` — because it was designed to encode a complete URL. `encodeURIComponent`, on the other hand, encodes those characters too, because it was designed to encode a value inside a URL, where `/`, `?`, and `&` cannot appear unescaped. When you manually build a query string by string concatenation, any value containing `&`, `=`, `+`, or `#` will silently corrupt server-side parsing. This happens far more often than it should, especially with names containing apostrophes, spaces, or the undisputed champion of encoding bugs — the `@` in email addresses passed as query parameters.

A critical pitfall when working with URL encoding is double encoding — encoding something that is already encoded. If you receive a URL that already contains `%20` and feed it through `encodeURIComponent`, the `%` becomes `%25` and the result is `%2520`, which the server will interpret as the literal string `%20` rather than a space. Another common source of confusion is the difference between `%20` and `+` for spaces: HTML forms encode spaces as `+` in `application/x-www-form-urlencoded`, but RFC 3986 specifies `%20`. Most servers accept both, but in contexts like API request signing — AWS being the prime example — the distinction is critical and can produce authentication errors that are notoriously hard to diagnose.

Las URL fueron inventadas por Tim Berners-Lee en 1991, junto con HTML y HTTP, como parte del proyecto que se convertiría en la World Wide Web. El formato que usamos hoy — ese `https://ejemplo.com/pagina?parametro=valor&otro=123` — fue formalizado en el RFC 1738 en 1994 y refinado hasta el RFC 3986 en 2005. Existe una tensión intrínseca en el diseño original: las URL deben transmitirse como texto ASCII puro, pero el mundo se comunica en cientos de idiomas con acentos, caracteres especiales y alfabetos completamente distintos al latino. La solución fue el percent-encoding: cualquier byte que no sea un carácter ASCII seguro se representa como `%` seguido de dos dígitos hexadecimales. La letra `ã` en UTF-8, por ejemplo, ocupa dos bytes — 0xC3 y 0xA3 — y se convierte en `%C3%A3`.

La parte que casi todo desarrollador aprende a la mala es la diferencia entre `encodeURIComponent` y `encodeURI`. La función `encodeURI` preserva los caracteres estructuralmente significativos de una URL — `/`, `?`, `#`, `&`, `=` — porque fue diseñada para codificar una URL completa. `encodeURIComponent`, en cambio, también codifica esos caracteres, porque fue diseñada para codificar un valor dentro de la URL, donde `/`, `?` y `&` no pueden aparecer sin escapar. Cuando construyes una query string manualmente concatenando texto, cualquier valor que contenga `&`, `=`, `+` o `#` romperá silenciosamente el parseo en el servidor. Esto ocurre con mucha más frecuencia de lo que debería, especialmente con nombres que contienen apóstrofes, espacios o — la campeona indiscutible de los bugs de encoding — la `@` en direcciones de correo pasadas como parámetro.

Un riesgo importante al trabajar con codificación de URL es el double encoding — codificar algo que ya está codificado. Si recibes una URL que ya contiene `%20` y la pasas por `encodeURIComponent`, el `%` se convierte en `%25` y el resultado final es `%2520`, que el servidor interpretará como la cadena literal `%20` en vez de un espacio. Otro punto que genera confusión es la diferencia entre `%20` y `+` para representar espacios: los formularios HTML usan `+` en el formato `application/x-www-form-urlencoded`, pero el RFC 3986 especifica `%20`. La mayoría de los servidores acepta ambos, pero en contextos como la firma de peticiones a APIs — AWS, por ejemplo — la diferencia es crítica y puede generar errores de autenticación notoriamente difíciles de depurar.