Noções Básicas de Cache

8 exemplos para você começar com cache para APIs Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

npm install ioredis
npm install -D typescript@5.6 tsx @types/node

Execute o Redis localmente: docker run -d -p 6379:6379 redis:7. Veja ioredis para detalhes de conexão.

Exemplos Básicos

1. Leitura Cache-Aside

import Redis from "ioredis";
 
const redis = new Redis(process.env.REDIS_URL!);
 
export async function getProduct(sku: string, loadFromDb: (sku: string) => Promise<Product | null>) {
  const key = `product:${sku}`;
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached) as Product;
 
  const product = await loadFromDb(sku);
  if (product) {
    await redis.set(key, JSON.stringify(product), "EX", 300);
  }
  return product;
}

• O app é responsável pela consistência - o DB é a fonte da verdade
• TTL (EX 300) limita a obsolescência
• Em caso de cache miss, apenas um caminho de código carrega o DB

Relacionado: ioredis - configuração do cliente

2. Estratégia de TTL

• TTL mais curto é mais simples do que invalidação perfeita para leituras de baixo risco
• Documente a obsolescência máxima por endpoint na documentação da API

3. Exclusão de Cache na Escrita

export async function updateProduct(sku: string, data: Partial<Product>, save: () => Promise<Product>) {
  const updated = await save();
  await redis.del(`product:${sku}`);
  return updated;
}

• Escreva primeiro no DB, depois invalide o cache
• Para chaves relacionadas, use um padrão de exclusão ou mantenha um conjunto de índice reverso
• A falta de invalidação causa leituras obsoletas até que o TTL expire

4. Chaves com Namespace

const NS = `api:${process.env.APP_ENV}:v1`;
 
function productKey(sku: string) {
  return `${NS}:product:${sku}`;
}

• Prefixe por ambiente para que staging nunca acesse chaves de produção
• Incremente v1 para v2 em caso de alterações que quebrem o formato do cache
• Evite cardinalidade de chave ilimitada (sem strings de busca de usuário brutas)

5. Degradação Graciosa com Redis Indisponível

export async function getWithFallback<T>(
  fetchCache: () => Promise<T | null>,
  fetchOrigin: () => Promise<T>
): Promise<T> {
  try {
    const hit = await fetchCache();
    if (hit !== null) return hit;
  } catch (err) {
    console.warn({ msg: "cache_unavailable", err: (err as Error).message });
  }
  return fetchOrigin();
}

• Falha no Redis não deve derrubar endpoints de leitura
• Registre erros de cache; alerte em caso de falha sustentada
• Escritas que dependem do Redis (locks, limites de taxa) ainda podem falhar fechadas

6. Custo de Serialização JSON

await redis.set(key, JSON.stringify(value), "EX", ttl);
const raw = await redis.get(key);
const value = raw ? (JSON.parse(raw) as T) : null;

• Objetos grandes afetam CPU e largura de banda - cacheie DTOs, não grafos ORM completos
• Considere MessagePack apenas quando a profilagem provar que JSON é um gargalo
• Veja Custo de Serialização JSON

Exemplos Intermediários

7. Prevenção de Stampede (Lock Single-Flight)

async function getOrLoad(key: string, ttlSec: number, loader: () => Promise<string>) {
  const hit = await redis.get(key);
  if (hit) return hit;
 
  const lockKey = `${key}:lock`;
  const acquired = await redis.set(lockKey, "1", "EX", 10, "NX");
  if (!acquired) {
    await new Promise((r) => setTimeout(r, 50));
    return (await redis.get(key)) ?? loader();
  }
  try {
    const value = await loader();
    await redis.set(key, value, "EX", ttlSec);
    return value;
  } finally {
    await redis.del(lockKey);
  }
}

• Quando uma chave quente expira, um loader a repopula; outros esperam ou tentam get novamente
• TTL do lock previne deadlocks se o loader travar
• Alternativa: expiração antecipada probabilística

Relacionado: Locks Distribuídos - ressalvas sobre locks

8. Cache-Aside vs. Read-Through

• APIs Node quase sempre implementam cache-aside explicitamente
• Workers de fila aquecem caches após atualizações em massa do DB

FAQs

Relacionados

• ioredis - conexão e pipelines
• Session Stores - sessões Redis
• Distributed Locks - coordenação
• Caching Best Practices - checklist da equipe
• Performance Basics - orçamentos de latência

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.