# Cloudflare KV: cache, sessões e links curtos sem improviso
> Aprenda quando usar Cloudflare KV para cache, sessão e short links — e quando consistência eventual, limite de escrita e preço pedem outra escolha.
**Autores:** Mauro Mequelussi
**Publicado:** 2026-07-24T12:00:00.000Z
**Atualizado:** 2026-07-24T12:00:57.499884595Z
**Tags:** short-links, kv, cache, autenticacao, cloudflare
---
Cloudflare Workers KV é um armazenamento global de chave e valor feito para leituras rápidas e muito frequentes. Ele é excelente para cache, preferências, sessões auxiliares, flags simples e resolução de links curtos. Ele não é um banco transacional nem uma fila; usar KV como se fosse um desses produtos cria bugs que aparecem quando o tráfego cresce.

No nosso cenário, namespaces separados atendem autenticação, cache, API e short links. Essa separação evita que uma limpeza de cache atinja sessão e que um contador temporário concorra com a resolução pública de um link.

## Quando usar KV — e quando não usar

KV faz sentido quando ler é mais comum que escrever e uma pequena janela de consistência eventual é aceitável. A documentação da Cloudflare descreve propagação global eventual, normalmente em até 60 segundos, e limite de uma escrita por segundo por chave. Isso define a fronteira do produto.

| Necessidade | Escolha mais adequada | Por quê |
| --- | --- | --- |
| cache de artigo ou configuração | KV | leitura global e TTL simples |
| sessão auxiliar ou desafio temporário | KV | acesso rápido e expirável |
| link curto publicado | KV + fonte canônica | resolve rápido; banco reconcilia |
| saldo, estoque ou permissão crítica | banco transacional / Durable Object | não aceite consistência eventual |
| arquivo, imagem ou PDF | R2 | KV não é object storage |
| trabalho para depois | Queue | uma chave não confirma processamento |

::callout{type="warning" title="Cache não é fonte de verdade"}
O KV acelera leitura. A fonte de verdade continua no banco ou no serviço de domínio. Sempre defina como reconstruir, invalidar e expirar uma chave.
::

## Cenário brasileiro: blog, sessão e link curto

Um blog pode guardar uma listagem de artigos em KV por uma hora e servir conteúdo antigo enquanto regenera a resposta. Isso protege o banco de picos quando uma campanha ou uma aula gera muitos acessos. Já uma sessão de autenticação pode usar KV como armazenamento secundário, mas a aplicação ainda precisa validar a identidade e aplicar permissão no servidor.

Para short links, o fluxo saudável é: o Gestor grava a regra de negócio no banco, projeta a versão resolvível no `KV_SHORTLINKS` e o Worker de links lê apenas o necessário para redirecionar. Se o KV perder uma chave, um processo de reconciliação consegue repovoá-la; se o banco perder a regra, o sistema tem um problema diferente e mais grave.

## Preço e como estimar

Na tabela vigente em julho de 2026, Workers Paid inclui 10 milhões de leituras por mês, 1 milhão de escritas, deletes e listagens, além de 1 GB armazenado. Leituras adicionais custam US$ 0,50 por milhão; escritas, deletes e listagens, US$ 5 por milhão; armazenamento adicional, US$ 0,50 por GB-mês. O plano gratuito tem limites diários bem menores.

O custo orienta uma decisão simples: cache com muita leitura costuma ser barato; um desenho que escreve uma chave por clique, por token ou por contador pode ficar caro e sofrer limite de escrita. Prefira agregação, TTL e um contador especializado quando a taxa por chave for alta.

## Padrão de chave que permite operar

Use chaves previsíveis, curtas e com domínio explícito:

```text
auth:session:{id}
cache:blog:list:v1
cache:blog:article:{slug}
shortlink:{slug}
rate-limit:{tenant}:{janela}
```

Evite colocar CPF, e-mail ou token em uma chave legível. Além de privacidade, você torna logs, listagens e ferramentas de suporte mais arriscados. Se o dado for sensível, use identificador interno, TTL e menor conjunto possível de metadados.

::read-more{slug="cloudflare-r2-arquivos-custo" label="Continuar: arquivos e capas no R2, não no KV" placement="mid_content"}
## Prós, contras e armadilhas

**Prós:** leitura global rápida, binding simples, TTL nativo e preço previsível em cenários read-heavy. **Contras:** consistência eventual, limite por chave, sem consulta por atributos e sem transação. Você também precisa tratar cache stale e invalidação como parte do produto.

Não use `list()` como consulta de negócio. Liste chaves para manutenção ou reconciliação; para buscar “todos os artigos de uma categoria” ou “pedidos de um cliente”, use o banco que modela essa relação.

## Checklist antes de criar um namespace

- [ ] a leitura é muito mais frequente que a escrita;
- [ ] até 60 segundos de propagação eventual não quebra a regra;
- [ ] existe fonte canônica fora do KV;
- [ ] cada ambiente tem namespace físico próprio;
- [ ] TTL e prefixo foram definidos;
- [ ] a limpeza não pode apagar dados de outro domínio;
- [ ] métricas incluem hit, miss, write e falha de reconciliação.

## Perguntas frequentes

### KV serve para rate limit?

Pode servir para casos tolerantes a aproximação, mas não oferece contador atômico global por padrão. Para bloqueio estrito, avalie o Rate Limiting binding, Durable Objects ou outra solução apropriada.

### Posso guardar sessão no KV?

Sim, quando a biblioteca e o modelo de segurança suportarem isso. Separe namespace, use expiração e não confunda a presença de uma chave com autorização para qualquer ação.

### O que acontece em um cache miss?

O Worker consulta a fonte de verdade, monta uma resposta validada e grava uma cópia com TTL. O código deve continuar funcionando se a gravação de cache falhar.

### Fontes e leitura recomendada

- [Cloudflare Workers KV](https://developers.cloudflare.com/kv/)
- [FAQ e consistência do KV](https://developers.cloudflare.com/kv/reference/faq/)
- [Preços de Workers e KV](https://developers.cloudflare.com/workers/platform/pricing/)