Cache key vs restore key: como funcionam as buscas de cache no CI
A cache key é o nome exato sob o qual você salva e busca primeiro. Restore keys são prefixos que capturam um quase-acerto, para que uma pequena alteração restaure um cache antigo útil em vez de nada.
O cache de CI tem dois botões que as pessoas confundem: a key precisa e as restore keys de fallback. Entender como uma busca caminha de uma para a outra é a chave tanto para altas taxas de acerto quanto para dados frescos.
A key exata
Ao salvar, o cache é armazenado sob a key. Ao restaurar, o runner primeiro busca uma correspondência exata. Uma correspondência perfeita é o ideal: ela restaura precisamente o cache para este conjunto de dependências. A key normalmente embute um hash de lockfile para que mude apenas quando deve.
Restore keys (fallback por prefixo)
Se não há correspondência exata, o runner tenta cada restore key como um *prefixo*, pegando o cache mais recente cuja key começa com esse prefixo. Isso significa que um lockfile alterado (nova key exata, sem acerto exato) ainda pode restaurar o store da execução anterior e deixar o instalador atualizar só o delta.
key: deps-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
deps-Semântica de save vs restore
- Save: grava sob a key exata (no-op se essa key já existe).
- Restore: key exata primeiro, depois restore-keys como prefixos, mais recente vence.
- Um acerto por restore-key é parcial - o instalador reconcilia a diferença.
Ajustando o trade-off
Uma key específica demais sem restore keys → erros totais frequentes e instalações a frio. Um prefixo frouxo demais → você pode restaurar um cache obsoleto e inchado. Uma key exata apertada mais um fallback de prefixo sensato dá frescor em uma correspondência e um início aquecido em um erro.
Principais conclusões
- A key exata é tentada primeiro; ela deve mudar apenas quando o conteúdo deve.
- Restore keys são fallbacks por prefixo; o cache correspondente mais recente vence.
- Um acerto por restore-key é parcial - o instalador preenche o delta.
- Key apertada + bom prefixo = frescor no acerto, início aquecido no erro.