A API URLPattern: Correspondência de URLs da Forma Moderna

Se você já escreveu uma expressão regular para extrair um ID de usuário de um caminho de URL, você conhece a dor. O padrão começa simples, depois cresce e se torna uma bagunça ilegível de caracteres de escape e grupos de captura. Quando os requisitos mudam, você está depurando regex em vez de construir funcionalidades.

A API URLPattern oferece uma abordagem melhor. É um padrão WHATWG para correspondência moderna de URLs que funciona nativamente em navegadores, permitindo que você faça correspondência e análise de URLs com padrões legíveis em vez de regex crípticas. Este artigo aborda o que a URLPattern resolve, seus conceitos centrais e quando desenvolvedores frontend devem recorrer a ela.

Qual Problema a URLPattern Resolve?

Antes da URLPattern, desenvolvedores tinham duas opções principais para análise de URLs web: escrever expressões regulares personalizadas ou usar bibliotecas de roteamento.

Expressões regulares funcionam, mas criam dores de cabeça de manutenção. Um padrão como /^\/users\/([a-zA-Z0-9]+)\/?$/ requer análise mental toda vez que você o revisita. Grupos de captura são posicionais e anônimos—se você adiciona um novo segmento, o código existente quebra.

Bibliotecas de roteamento resolvem o problema de legibilidade, mas adicionam peso ao bundle e introduzem sintaxe específica de framework. Sua lógica de correspondência de URL fica vinculada a uma ferramenta específica.

URLPattern fornece um meio-termo padronizado. Usa uma sintaxe intuitiva emprestada de convenções populares de roteamento:

const pattern = new URLPattern({ pathname: '/users/:id' })

O segmento :id é um grupo nomeado. Sem caracteres de escape. Sem grupos de captura numerados. O padrão se lê como a estrutura de URL que ele corresponde.

Conceitos Centrais da API URLPattern

Padrões Abrangem URLs Completas ou Componentes Individuais

URLPattern pode fazer correspondência com URLs completas ou componentes específicos. Uma URL se divide em oito partes: protocol, username, password, hostname, port, pathname, search e hash.

Você pode definir padrões para qualquer combinação:

const pattern = new URLPattern({
  hostname: '*.example.com',
  pathname: '/api/:version/*'
})

Isso corresponde a qualquer subdomínio de example.com com um caminho de API. Componentes que você não especifica assumem curingas por padrão, correspondendo a qualquer coisa.

Testando vs. Extraindo Grupos Estruturados

URLPattern oferece dois métodos principais com propósitos distintos.

O método test() retorna um booleano—esta URL corresponde ao padrão?

pattern.test('https://api.example.com/api/v2/users') // true

O método exec() retorna resultados de correspondência detalhados, incluindo grupos capturados:

const result = pattern.exec('https://api.example.com/api/v2/users')
console.log(result.pathname.groups.version) // 'v2'

Grupos nomeados se tornam propriedades de objeto. Não é mais necessário acessar result[1] e torcer para que o índice esteja correto.

Suporte dos Navegadores à URLPattern

URLPattern atingiu o status Baseline Newly Available no final de 2025. Chrome, Edge, Firefox e Safari todos a suportam. Isso não é mais uma funcionalidade experimental ou uma API exclusiva do Chrome—é um padrão web estável que você pode usar em produção.

Para JavaScript do lado do servidor, o cenário é diferente. Versões recentes do Node.js 23+ incluem URLPattern, mas a implementação permanece experimental de acordo com a documentação oficial. Se você está escrevendo código que roda em ambos os ambientes, verifique o comportamento do Node.js separadamente das expectativas do navegador.

Quando Usar URLPattern

URLPattern brilha como uma primitiva de baixo nível, não uma solução completa de roteamento. Considere-a para:

Service workers que precisam interceptar requisições e aplicar diferentes estratégias de cache baseadas em padrões de URL.

Lógica de roteamento SPA onde você está construindo tratamento de navegação personalizado ou precisa de correspondência de URL fora do roteador do seu framework.

Estado de UI orientado por URL quando componentes precisam analisar a URL atual e extrair parâmetros.

URLPattern não substituirá React Router ou Vue Router. Esses frameworks fornecem guardas de navegação, carregamento lazy e integração com ciclos de vida de componentes. URLPattern lida bem com uma coisa: fazer correspondência de URLs com padrões e extrair dados.

Uma Comparação Prática

Considere extrair uma categoria e ID de /products/electronics/123.

Com regex:

const match = /^\/products\/([^/]+)\/(\d+)$/.exec(pathname)
const category = match?.[1]
const id = match?.[2]

Com URLPattern:

const pattern = new URLPattern({ pathname: '/products/:category/:id' })
const result = pattern.exec({ pathname })
const { category, id } = result?.pathname.groups ?? {}

A versão URLPattern é mais longa, mas autodocumentada. Seis meses depois, você entenderá o que ela faz sem decodificar regex.

Conclusão

URLPattern padroniza a correspondência de URLs entre navegadores com uma sintaxe limpa e legível. Extrai parâmetros nomeados sem complexidade de regex e funciona consistentemente seja você correspondendo pathnames, hostnames ou URLs completas.

Para desenvolvedores frontend construindo SPAs, service workers ou qualquer funcionalidade orientada por URL, URLPattern fornece uma base à prova de futuro. Consulte a documentação URLPattern do MDN para a referência completa de sintaxe e comece a substituir aqueles padrões regex por algo sustentável.

Perguntas Frequentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.