Gerador de cabeçalho HTTP Cache-Control | Compor diretivas com detecção de conflitos
Monte um cabeçalho de resposta Cache-Control com botões de opção e caixas de seleção. Escolha entre public e private, defina max-age, s-maxage e stale-while-revalidate em segundos, ative indicadores como must-revalidate ou immutable, e a ferramenta gera uma única linha como Cache-Control: private, max-age=3600 acompanhada de uma explicação em linguagem clara. Ela também aponta cinco combinações contraditórias comuns, como usar no-store com max-age.
💡 Sobre esta ferramenta
Escrever uma linha Cache-Control numa configuração do Nginx, do Cloudflare ou de um bucket de armazenamento parece simples até surgir a pergunta central: esta linha faz mesmo o que eu acho? Os nomes das diretivas são fáceis de memorizar, mas é na interação entre elas que os erros se escondem. no-cache e no-store são parecidos e, ainda assim, agem de forma oposta; descobrir qual prevalece quando você também define max-age costuma exigir mais uma consulta à documentação.
Esta ferramenta monta o cabeçalho e, sobretudo, destaca as combinações que se anulam. Escolha no-store e digite um valor de max-age: ela avisa que no-store prevalece e nada é armazenado. Marque immutable com max-age em zero: ela alerta que o indicador não surte efeito. Use-a como rascunho: ajuste as diretivas, confira o resultado e só então leve um cabeçalho confiável para a sua configuração real.
🧐 Perguntas frequentes
Q. Qual a diferença entre no-cache e no-store? no-cache armazena a resposta, mas precisa revalidá-la com a origem antes de reutilizá-la. no-store proíbe armazená-la por completo. Use no-store para dados sensíveis que nunca devem ser gravados em cache e no-cache quando quiser garantir atualidade permitindo reutilização condicional.
Q. Quando usar s-maxage em vez de max-age? max-age vale para todos os caches, inclusive o navegador. s-maxage vale apenas para caches compartilhados como CDNs e proxies, onde prevalece sobre max-age. Um padrão comum é um max-age curto para navegadores e um s-maxage mais longo para que a CDN absorva mais tráfego.
Q. O que acontece com a minha CDN se eu escolher private? private indica que a resposta só pode ser guardada num cache privado como o navegador; CDNs e proxies não mantêm cópia. É adequado para páginas que variam por usuário. Escolha public quando quiser que caches compartilhados armazenem a resposta.
Q. Existe um limite máximo de segundos? max-age, s-maxage, stale-while-revalidate e stale-if-error aceitam inteiros de 0 a 31536000 segundos (um ano). Qualquer valor maior é ajustado para 31536000.
Q. Para que serve immutable? immutable informa ao navegador que o arquivo não mudará durante seu período de validade, permitindo pular a requisição condicional de revalidação ao recarregar. Combina bem com nomes de arquivo com hash e um max-age longo, em que a URL muda sempre que o conteúdo muda.
📚 Como o cache HTTP funciona
Vale entender a sequência de decisões de um cache. Primeiro ele verifica se a resposta pode ser armazenada (public, private, no-store); depois calcula se ainda está atualizada usando max-age ou s-maxage; e só quando expira faz a revalidação com a origem por meio de um ETag ou da data da última modificação. Enxergar as diretivas como etapas desse fluxo, e não como interruptores isolados, ajuda a escolher a combinação certa.
O cabeçalho Cache-Control surgiu no HTTP/1.1 e hoje é descrito no RFC 9111. Antes, o HTTP/1.0 dependia do cabeçalho Expires com uma data absoluta, sensível à diferença de relógio entre servidor e cliente. A mudança para durações relativas em segundos com max-age corrigiu essa falha e é a base das estratégias modernas de cache.