Cache API y KV en Cloudflare Workers: Guía de caching serverless
Introducción: El problema del estado en el edge
Cuando construimos APIs serverless en Cloudflare Workers, el mayor desafío no es escribir la lógica de negocio, sino gestionar el estado y la latencia. Cada solicitud puede ejecutarse en un "aislamiento" diferente, distribuido en más de 300 centros de datos alrededor del mundo. Sin un mecanismo de almacenamiento adecuado, cada petición podría terminar golpeando tu origen o una base de datos central, aniquilando la promesa de rendimiento del edge computing.
Cloudflare ofrece dos herramientas complementarias para resolver este cuello de botella: la Cache API (almacenamiento efímero y de alta velocidad) y Workers KV (almacenamiento persistente, eventualmente consistente). Entender cuándo usar cada una, y cómo combinarlas, es la diferencia entre una API que responde en 5 ms y una que tarda 200 ms. En este artículo exploraremos los patrones técnicos, comandos reales y decisiones de arquitectura sin caer en un tutorial lineal.
Cache API: La memoria de corto plazo del worker
Qué es y cómo funciona internamente
La Cache API en Cloudflare Workers no es un simple objeto Map en memoria. Es una interfaz compatible con la especificación del estándar Cache de los service workers, pero operada a nivel de infraestructura. Cuando haces caches.default.put(), el objeto se almacena en una caché compartida en el PoP (Punto de Presencia) local. Esto significa que la caché no se replica automáticamente a otras regiones; si un usuario en Tokio hace una petición y el worker se ejecuta en Tokio, la caché estará fría aunque un usuario en Nueva York ya haya solicitado el mismo recurso.
// Ejemplo: Cacheo manual de una respuesta JSON async function handleRequest(request) { const cacheKey = new Request(request.url, { method: 'GET' }); const cache = caches.default;// 1. Intentar obtener de la caché let response = await cache.match(cacheKey); if (response) { console.log(‘Cache HIT en’, request.url); return response; }
// 2. Fetch al backend (origen) const url = new URL(request.url); const backendURL =
https://api.origin.com${url.pathname}; const backendResponse = await fetch(backendURL);// 3. Clonar y almacenar solo si es exitoso if (backendResponse.ok) { const responseToCache = backendResponse.clone(); // TTL de 60 segundos const headers = new Headers(responseToCache.headers); headers.set(‘Cache-Control’, ‘public, max-age=60’);
const cachedResponse = new Response(responseToCache.body, { status: responseToCache.status, statusText: responseToCache.statusText, headers: headers }); await cache.put(cacheKey, cachedResponse); console.log('Cache MISS - Almacenado');}
return backendResponse; }
addEventListener(‘fetch’, event => { event.respondWith(handleRequest(event.request)); });
Un detalle crítico: no puedes cachear respuestas con Set-Cookie ni cuerpos con Content-Length: 0 si no son 204. Además, la Cache API no respeta automáticamente las cabeceras Cache-Control del origen. Debes gestionar la expiración manualmente, como en el ejemplo anterior, o usar las reglas de caché del panel de Cloudflare.
Cuándo NO usar Cache API
La Cache API es volátil. Si tu worker se actualiza o el PoP sufre una evacuación de memoria, los datos desaparecen. No sirve para estado crítico ni para datos que deban sobrevivir minutos con garantía. Tampoco es adecuada para personalización por usuario (a menos que incluyas el header de autenticación en la clave, lo cual fragmenta la caché). Para datos de sesión o configuración global, necesitas persistencia.
Workers KV: Persistencia global con consistencia eventual
Arquitectura y rendimiento real
Workers KV (Key-Value) está construido sobre la infraestructura de almacenamiento de Cloudflare, replicado en todos los PoPs. Escribir en KV es casi instantáneo desde el punto de vista del cliente, pero la replicación global tarda entre 5 y 10 segundos en condiciones normales. Leer es extremadamente rápido (menos de 1 ms en el PoP local si el dato ya está allí), pero puede hacer un viaje al PoP central si la clave no se ha replicado aún.
La API es asíncrona y basada en promesas. Los comandos básicos incluyen put(), get(), delete() y list(). Para entornos de alta escritura, es recomendable usar la opción de expirationTtl para evitar que los datos huérfanos se acumulen.
// Ejemplo: Almacenar y leer configuración con expiración
import { KVNamespace } from '@cloudflare/workers-types';
interface Env {
SETTINGS: KVNamespace;
}
export default {
async fetch(request: Request, env: Env) {
const url = new URL(request.url);
const key = feature_flags:${url.hostname};
// Escribir en KV con TTL de 1 hora (3600 segundos)
if (request.method