O que é versionamento de URLs?

O versionamento de URLs publica conteúdo alterado em uma nova URL, geralmente incluindo um hash do conteúdo ou um identificador de versão no nome do arquivo, no caminho ou na string de consulta. Os caches HTTP buscam respostas armazenadas pela URL, portanto uma solicitação ao novo endereço não pode ser atendida com a cópia armazenada no endereço antigo, desde que nenhum cache esteja configurado para ignorar a parte da URL que mudou.

Um cache HTTP reutiliza uma resposta armazenada enquanto ela está dentro do prazo de validade, sem contatar a origem. Assim, um arquivo servido com um valor alto de max-age deixa de gerar as solicitações por meio das quais o servidor poderia substituí-lo. Geralmente é possível limpar o cache de uma CDN, mas essa limpeza não alcança as cópias que os navegadores já têm. O versionamento de URLs contorna ambos os problemas. Por especificação, uma chave de cache contém pelo menos o método da solicitação e a URL; algumas CDNs podem ser configuradas para excluir dela a string de consulta. Uma URL cuja chave não foi armazenada não tem uma resposta armazenada, então cada cache precisa encaminhar a solicitação em direção à origem. Na prática, os arquivos versionados recebem um valor alto de max-age (o exemplo da MDN usa um ano, max-age=31536000), opcionalmente com immutable, enquanto o documento que faz referência a eles é servido com no-cache. Dessa forma, um cache precisa revalidar o documento antes de reutilizá-lo, e um novo carregamento da página recebe os nomes atuais dos arquivos. A MDN observa que no-cache não garante a revalidação na navegação pelo histórico, então o botão Voltar pode restaurar uma página anterior. Empacotadores como webpack e Vite geram os nomes de arquivo com hash durante a compilação.

Nome de arquivo ou string de consulta? Tanto app.3f9a1c.js quanto app.js?v=3f9a1c alteram a URL, mas uma versão na string de consulta só funciona se todos os caches no caminho mantiverem a string de consulta na chave de cache. O nível de cache padrão Standard da Cloudflare faz isso, enquanto o nível Ignore Query String serve uma única cópia em cache de um arquivo estático, qualquer que seja o valor da consulta. O Amazon CloudFront só armazena conteúdo em cache por string de consulta quando a distribuição está configurada para isso, e os buckets de back-end do Google Cloud CDN precisam que o parâmetro de versão esteja em uma lista de inclusão. Uma versão na string de consulta também tende a manter um único arquivo na origem, que cada nova versão sobrescreve no mesmo local. Assim, uma página da versão anterior que solicita sua antiga URL ?v= após uma ausência no cache recebe o arquivo da nova versão. As orientações do Google para o Cloud CDN recomendam nomes de arquivo exclusivos, pois um arquivo atualizado no mesmo local pode ser armazenado em cache enquanto ainda está incompleto.
Os arquivos que não mudaram mantêm a URL entre versões? Com um hash do conteúdo, sim, desde que a compilação gere bytes idênticos; um número de versão ou carimbo de data e hora aplicado a todos os caminhos altera todas as URLs a cada versão e descarta as cópias em cache de arquivos que não mudaram. O hash de um arquivo ainda pode mudar mesmo que seu código-fonte não tenha mudado: o guia de cache do webpack mostra o [contenthash] de um pacote de dependências mudando após a adição de um módulo sem relação com ele, porque os IDs dos módulos seguiam a ordem de resolução. O guia observa que o modo de produção do webpack 5 usa IDs de módulo determinísticos por padrão e também move o runtime para um fragmento separado.
Em que ordem fazer a implantação? Faça primeiro o upload dos novos arquivos versionados e publique por último o documento que faz referência a eles; as orientações do Google para o Cloud CDN consideram crucial fazer o upload das dependências antes dos arquivos que fazem referência a elas. Mantenha também os arquivos da versão anterior disponíveis: uma página carregada antes da implantação ainda solicita os nomes antigos, e tanto o webpack quanto o Vite documentam falhas no carregamento de fragmentos ou erros de importação quando uma implantação os exclui. O guia do webpack sugere deixar que a CDN expire os arquivos antigos após cerca de um dia, em vez de fazê-lo na próxima implantação, e recarregar a página no máximo uma vez quando um fragmento ainda não carregar, já que uma aba pode permanecer aberta por mais tempo que o período de retenção.
O que immutable acrescenta a um valor alto de max-age? Ele instrui os clientes a não revalidar o arquivo ao recarregar a página enquanto ele ainda está dentro do prazo de validade, evitando solicitações condicionais que retornariam apenas 304. Ele não estende o prazo de validade e só é correto quando o arquivo nessa URL não vai mudar enquanto a resposta estiver dentro desse prazo, como ocorre com um nome de arquivo com hash que nunca é sobrescrito. A MDN observa que o Chrome não implementa a diretiva e, em vez disso, não revalida os sub-recursos ao recarregar a página.

Use o versionamento de URLs para sub-recursos como scripts, folhas de estilo e imagens que os navegadores e as CDNs devem manter por bastante tempo, mas cujas atualizações os navegadores e as CDNs devem obter logo após o lançamento de uma versão. Ele não pode ser aplicado a uma URL que precisa permanecer igual, como a do documento HTML que faz referência a esses arquivos; sirva esse documento com no-cache para que os navegadores o revalidem a cada novo carregamento da página. Se a CDN estiver configurada para servir o documento a partir do próprio cache sem revalidá-lo, limpe essa cópia também a cada implantação; a limpeza por si só não atualiza os navegadores. Cada nova chave de cache começa sem uma resposta armazenada: cada cache precisa buscar o arquivo uma vez, na origem ou em um cache mais próximo dela, antes de poder servi-lo.

O Smart CDN da Transloadit atribui uma URL própria a cada variante transformada: o Workspace, o nome do Template, o caminho do arquivo de origem e os parâmetros de transformação fazem parte do endereço tlcdn.com. Solicitar um tamanho ou formato diferente, portanto, altera a URL e produz uma representação separada em cache, enquanto um acerto de cache para a mesma URL reutiliza o resultado em cache em vez de executar o Template novamente. Para URLs assinadas, o prazo de validade efetivo de uma resposta em cache é limitado pelo prazo de validade restante da assinatura.

As páginas vinculadas aqui não descrevem uma operação de limpeza de cache nem o que acontece com um resultado em cache quando o original é substituído sem alterar o caminho do arquivo. Armazenar um novo original em outro caminho altera a URL do Smart CDN; teste o caso em que o caminho permanece igual no seu próprio Workspace antes de depender desse comportamento.

Explore os recursos de entrega da Transloadit

O que é versionamento de URLs?

Como funciona o versionamento de URLs

Informações essenciais

Quando o versionamento de URLs é importante

Como a Transloadit ajuda no versionamento de URLs

Fontes

Transforme conhecimento sobre mídia em um pipeline funcional