Guia Completo de Análise e Codificação URL: Da Estrutura ao Tratamento Seguro

Estrutura Completa da URL

https://user:pass@example.com:8080/path/to/page?name=value&age=25#section
  │       │     │    │          │  │   │            │                │
  scheme  user  pass  host      port path           query            fragment

Componente	Exemplo	Descrição
scheme	`https`	Protocolo
userinfo	`user:pass`	Informações de autenticação (raramente usado)
host	`example.com`	Domínio ou IP
port	`8080`	Número da porta (padrão 80/443)
path	`/path/to/page`	Caminho
query	`?name=value&age=25`	Parâmetros de consulta
fragment	`#section`	Âncora (não enviada ao servidor)

Análise com a API URL

Análise básica

const url = new URL('https://example.com:8080/path?q=test#section');

url.protocol  // "https:"
url.hostname  // "example.com"
url.port      // "8080"
url.pathname  // "/path"
url.search    // "?q=test"
url.hash      // "#section"
url.origin    // "https://example.com:8080"
url.href      // URL completa

Análise de parâmetros de consulta

const url = new URL('https://example.com/api?name=Alice&age=25&tags=js&tags=css');

// URLSearchParams
url.searchParams.get('name')     // "Alice"
url.searchParams.get('age')      // "25"
url.searchParams.getAll('tags')  // ["js", "css"]
url.searchParams.has('name')     // true
url.searchParams.delete('age')

// Iterar
for (const [key, value] of url.searchParams) {
  console.log(`${key} = ${value}`);
}

Modificar URL

const url = new URL('https://example.com/page');

url.pathname = '/new-page';
url.searchParams.set('sort', 'desc');
url.searchParams.append('filter', 'active');
url.hash = '#top';

console.log(url.toString());
// "https://example.com/new-page?sort=desc&filter=active#top"

Regras de Codificação URL

Por que a codificação é necessária?

URLs só permitem caracteres ASCII, outros caracteres devem ser codificados:

Original: https://example.com/search?q=你好 世界
Codificado: https://example.com/search?q=%E4%BD%A0%E5%A5%BD%20%E4%B8%96%E7%95%8C

encodeURI vs encodeURIComponent

Função	Escopo de codificação	Uso
`encodeURI`	Preserva caracteres estruturais da URL (`:/?#[]@!$&'()*+,;=`)	Codificar URL completa
`encodeURIComponent`	Codifica todos os caracteres não ASCII + caracteres reservados	Codificar valores de parâmetros de consulta

const url = 'https://example.com/path?name=你好&redirect=/home';

// encodeURI: preserva a estrutura da URL
encodeURI(url);
// "https://example.com/path?name=%E4%BD%A0%E5%A5%BD&redirect=/home"

// encodeURIComponent: codifica todos os caracteres especiais
encodeURIComponent(url);
// "https%3A%2F%2Fexample.com%2Fpath%3Fname%3D%E4%BD%A0%E5%A5%BD%26redirect%3D%2Fhome"

// ✅ Uso correto: valores de parâmetros com encodeURIComponent
const name = '你好 世界';
const redirect = '/home';
const fullUrl = `https://example.com/path?name=${encodeURIComponent(name)}&redirect=${encodeURIComponent(redirect)}`;

Tabela de codificação comum

Caractere	Codificação	Descrição
Espaço	`%20`	Não usar `+` na URL
`+`	`%2B`	Em parâmetros de consulta `+` é decodificado como espaço
`&`	`%26`	Separador de parâmetros de consulta
`=`	`%3D`	Separador chave-valor
`#`	`%23`	Identificador de âncora
`%`	`%25`	O próprio prefixo de codificação
Chinês	`%E4%BD%A0`	Codificação UTF-8 de três bytes

Usar o ToolsKu para Codificar/Decodificar URL

Abra a ferramenta de Codificação/Decodificação URL
Cole a URL ou texto no campo de entrada
Clique em "Codificar" ou "Decodificar"
Consulte o resultado

Tratamento Seguro de URL

1. Prevenir injeção de URL

// ❌ Perigoso: concatenar diretamente a entrada do usuário
const url = `/api/users/${userId}`;

// ✅ Seguro: validar + codificar
function buildUserUrl(userId) {
  if (!/^\d+$/.test(userId)) {
    throw new Error('Invalid user ID');
  }
  return `/api/users/${encodeURIComponent(userId)}`;
}

2. Prevenir redirecionamento aberto

// ❌ Perigoso: o usuário pode especificar qualquer URL de redirecionamento
app.get('/login', (req, res) => {
  res.redirect(req.query.redirect);
});

// ✅ Seguro: validação com lista branca
function safeRedirect(url, allowedHosts) {
  try {
    const parsed = new URL(url, 'https://example.com');
    if (allowedHosts.includes(parsed.hostname)) {
      return url;
    }
  } catch {
    // URL inválida
  }
  return '/'; // Redirecionar para a página inicial
}

3. Prevenir XSS via URL

// ❌ Perigoso: protocolo javascript:
const url = 'javascript:alert(document.cookie)';

// ✅ Seguro: permitir apenas protocolos http/https
function sanitizeUrl(url) {
  try {
    const parsed = new URL(url);
    if (['http:', 'https:'].includes(parsed.protocol)) {
      return url;
    }
  } catch {
    // URL inválida
  }
  return 'about:blank';
}

API URLPattern (Novo Padrão)

// Correspondência de rotas
const pattern = new URLPattern({ pathname: '/api/users/:id' });

const result = pattern.exec('https://example.com/api/users/123');
if (result) {
  console.log(result.pathname.groups.id); // "123"
}

// Padrão mais complexo
const apiPattern = new URLPattern({
  protocol: 'https',
  hostname: ':env.example.com',
  pathname: '/api/:version/:resource/:id?',
});

const match = apiPattern.exec('https://prod.example.com/api/v2/users/456');
match.hostname.groups.env      // "prod"
match.pathname.groups.version  // "v2"
match.pathname.groups.resource // "users"
match.pathname.groups.id       // "456"

Melhores Práticas para Construir Parâmetros de Consulta

Usar URLSearchParams

// ✅ Recomendado: usar URLSearchParams
const params = new URLSearchParams({
  q: '搜索关键词',
  sort: 'desc',
  page: '1',
  limit: '20',
});

params.append('tags', 'javascript');
params.append('tags', 'css');

const url = `https://api.example.com/search?${params}`;
// "https://api.example.com/search?q=...&sort=desc&page=1&limit=20&tags=javascript&tags=css"

Convenções comuns para parâmetros de array

Convenção	Exemplo	Framework do servidor
Chaves repetidas	`?tags=js&tags=css`	Express, Koa
Sufixo com colchetes	`?tags[]=js&tags[]=css`	PHP, Rails
Subscrito	`?tags[0]=js&tags[1]=css`	PHP
Separados por vírgula	`?tags=js,css`	Personalizado

Perguntas Frequentes

Por que o espaço na URL às vezes é `%20` e às vezes `+`?

No caminho da URL: espaço = %20 (padrão)
Nos parâmetros de consulta: espaço = + ou %20 (+ é a convenção de application/x-www-form-urlencoded)
Recomendação: usar %20 uniformemente, evitar ambiguidade

As URLs têm um limite máximo de comprimento?

Cenário	Limite
Barra de URL do Chrome	2MB
Barra de URL do Firefox	Sem limite
Barra de URL do IE	2083 caracteres
Requisição HTTP GET	O servidor decide (geralmente 8KB)
Limite seguro	2048 caracteres (compatível com todos os navegadores)

Parâmetros que excedam 2048 caracteres devem usar requisições POST.

Resumo

A URL é a pedra angular da Web; compreender sua estrutura, regras de codificação e tratamento seguro é uma habilidade fundamental para cada desenvolvedor. Pontos-chave: codificar valores de parâmetros com encodeURIComponent, verificar protocolos para prevenir XSS, validar com lista branca para prevenir redirecionamento aberto. A ferramenta de Codificação/Decodificação URL do ToolsKu ajuda você a lidar rapidamente com problemas de codificação URL.