Criador de URL

Anatomia de uma URL, componente por componente

A gramática que define cada URL na web vive na RFC 3986 «Uniform Resource Identifier (URI): Generic Syntax» (Berners-Lee, Fielding, Masinter, janeiro de 2005). Os navegadores na verdade usam uma variante ligeiramente mais tolerante definida no WHATWG URL Living Standard. Ambos concordam nos componentes:

• Esquema: https, http, ftp, mailto, data, tel, sms, magnet, além de esquemas de aplicativos personalizados (myapp://). RFC 3986 exige minúsculas; WHATWG canoniza. O registro de esquemas URI da IANA tem a lista oficial de esquemas registrados.
• Autoridade: userinfo@host:port. A forma de credenciais incorporadas user:password@ está obsoleta por segurança: Chrome 64 (janeiro de 2018) bloqueia carregamentos de sub-recursos com credenciais na URL porque permitiam truques de phishing.
• Host: um nome de domínio ou literal IP. Nomes de domínio internacionalizados como президент.рф são convertidos para ASCII via Punycode (RFC 3492, março de 2003): esse exemplo se torna xn--d1abbgf6aiiy.xn--p1ai. Os navegadores fazem a conversão de forma transparente para exibição.
• Porta: incluída apenas quando não padrão para o esquema. Padrões: 80 (http), 443 (https), 21 (ftp), 22 (ssh), 25 (smtp), 5432 (postgres), 3306 (mysql), 6379 (redis).
• Caminho: segmentos separados por barras. Cada segmento codifica em porcentagem qualquer coisa fora do conjunto pchar definido na RFC 3986 §3.3. Os segmentos-ponto . e .. têm semântica de remoção (§5.2.4).
• Consulta: por convenção pares chave-valor separados por &, mas a RFC 3986 diz apenas «string opaca após ?». A convenção é formalizada no algoritmo application/x-www-form-urlencoded do WHATWG.
• Fragmento: tudo após #. Nunca enviado ao servidor. Usado por roteadores de aplicativo de página única, âncoras de link, e tokens de fluxo implícito OAuth.

Codificação porcentual: a armadilha + versus %20

RFC 3986 §2.3 define os caracteres não reservados que nunca precisam de codificação: A-Z a-z 0-9 - . _ ~. Todo o resto, quando aparece como dados dentro de um componente de URL, vira %XX onde XX é o valor hexadecimal do byte. Caracteres UTF-8 multi-byte se expandem para múltiplos tripletes de porcentagem: é (U+00E9, UTF-8 C3 A9) codifica como %C3%A9. A pegadinha clássica é o caractere espaço: em um caminho ou fragmento de URL regular, espaço codifica como %20; em strings de consulta codificadas em formulário (o algoritmo application/x-www-form-urlencoded compartilhado por formulários HTML e o serializador de string de consulta WHATWG), espaço codifica como +. Um servidor decodificando dados de formulário converte + de volta para espaço; um servidor tratando a consulta como um URI genérico não. Misturar as duas convenções corrompe silenciosamente os dados. O padrão seguro em JavaScript: use new URLSearchParams para consultas e encodeURIComponent para valores individuais; a conformidade com a spec é cuidada para você.

Onde você realmente precisa de um construtor de URL

• Links de marketing com tags UTM para Google Analytics (Urchin Tracking Module, no GA desde 2005): os cinco parâmetros canônicos são utm_source, utm_medium, utm_campaign, utm_content, utm_term, todos em minúsculas conforme as próprias diretrizes do Google.
• Solicitações de autorização OAuth 2.0 (RFC 6749, outubro de 2012): a spec exige response_type, client_id, redirect_uri, scope, state como parâmetros de consulta no endpoint de autorização.
• Deep links móveis: um esquema app:// que o SO roteia para seu aplicativo instalado em vez do navegador, ou um Android App Link / iOS Universal Link servido do seu domínio.
• Teste de clientes API: https://api.example.com/v2/users?expand=projects&since=2024-01-01. Digitar estes à mão falha consistentemente na etapa «espaço dentro de um valor».
• Buster de cache CDN: ?v=2026-05-12-1 anexado a URLs de ativos estáticos para que um deploy invalide a versão em cache. A string de consulta faz parte da chave de cache.
• Serviços de transformação de imagem (Cloudinary, imgix, Cloudflare Images): a transformação é codificada como parâmetros de consulta ou segmentos de caminho. Uma chamada típica se parece com ?w=800&q=85&fm=webp.
• Templates de email onde a página de destino lê parâmetros via JS, frequentemente combinando tags UTM com um token ou uid único para rastreamento por destinatário.

Erros comuns

• Esquecer de codificar & dentro de um valor. Um valor «gatos & cachorros» jogado ingenuamente em ?espécies=gatos & cachorros vira uma chave espécies com valor gatos mais uma chave vazia perdida. Sempre passe por encodeURIComponent.
• Codificação dupla. Chamar encodeURIComponent em uma string já codificada vira %20 em %2520. Fácil quando um valor passa por dois sistemas que cada um «codifica defensivamente».
• Incompatibilidade de barra final. RFC 3986 diz que https://example.com/api e https://example.com/api/ são recursos diferentes. A maioria das APIs REST as trata identicamente, mas algumas retornam redirecionamentos 308; escolha uma forma canônica e documente-a.
• Misturando + e %20. Strings de consulta codificadas em formulário usam + para espaço; codificação porcentual genérica usa %20. Um caminho com + literal sobrevive ao copia-cola mas falha quando um decodificador de formulário o lê.
• Credenciais incorporadas. https://user:pass@example.com está obsoleto e bloqueado para carregamentos de sub-recursos no Chrome 64+. Use o cabeçalho Authorization.
• Spoofing IDN. O cirílico «а» (U+0430) é visualmente idêntico ao latim «a». Os navegadores exibem Punycode quando um domínio mistura scripts, mas uma URL construída manualmente apontando para аpple.com (а cirílico) abre um site diferente de apple.com. Use Punycode (xn--...) para segurança, ou fique com ASCII.
• Adicionar // após esquemas que não o usam. mailto:, tel:, sms:, magnet: todos pulam o // e vão direto para o caminho. mailto:user@example.com está correto; mailto://... não está.

Mais perguntas frequentes

Qual é o tamanho máximo de uma URL?

RFC 3986 não define limite. Na prática: os navegadores limitam a cerca de 2 000 caracteres para a barra de endereço (Internet Explorer 11 era 2 083; Chrome e Firefox toleram mais mas truncam a exibição); a maioria dos CDNs e proxies limitam a 4 096 ou 8 192; servidores como Apache e Nginx por padrão a 8 192 bytes para a linha de solicitação. Se você precisa de mais de 2 000 caracteres, mude para corpo POST.

Posso incluir o mesmo parâmetro de consulta várias vezes?

Sim. ?tag=red&tag=blue&tag=green é válido. Como o servidor o interpreta depende do framework: Express / Node.js parsa para req.query.tag = ['red', 'blue', 'green']; PHP precisa da convenção de colchetes ?tag[]=red&tag[]=blue; Rails parsa para um array se você usar os colchetes tag[]. O método URLSearchParams.getAll('tag') sempre retorna todos os valores como um array independentemente do estilo de colchetes.

Os parâmetros de consulta afetam SEO?

Os parâmetros de rastreamento (UTM, fbclid, gclid) geralmente não afetam os rankings de busca orgânica. O risco é a indexação de conteúdo duplicado: uma URL com tag e sua versão limpa parecem duas páginas diferentes para um crawler. A correção é uma tag <link rel="canonical" href="clean-url"> apontando cada variante etiquetada para a mesma URL canônica.

O que é um Template URI, e devo usar um?

RFC 6570 (março de 2012) define Templates URI: uma sintaxe para URLs parametrizadas com placeholders. São usados em specs OpenAPI / Swagger, JSON Hyper-Schema, e algumas APIs HATEOAS. Para construção de URL do dia a dia, concatenação simples de strings através deste construtor é mais simples; Templates URI brilham ao documentar uma superfície de API e gerar SDKs cliente.

Algo é enviado a um servidor?

Não. Cada componente que você digita, a codificação e a URL final são construídos no JavaScript do seu navegador. Nenhuma chamada de rede é feita para montar a URL. Abra a aba Rede no DevTools e experimente a ferramenta: você verá zero solicitações de saída durante a construção.