Zum Inhalt springen
Deutsch

Redis-Cache

RedisCache ist die Redis-gestützte Cache-Implementierung. Produktionsreif, Multi-Pod-sicher, mit Single-Round-Trip-Bulk- Operationen.

import { RedisCache, RedisCacheOptions } from 'actor-ts/cache';
const redisCacheOptions = RedisCacheOptions.create().withUrl('redis://redis.example.com:6379');
const cache = new RedisCache(
redisCacheOptions,
);

Die meisten Multi-Pod-Produktionsfälle:

  • Cache-Sharing über Pods — Pods sehen denselben Cache-State.
  • Bulk-Operationen zählen — MGET / MSET in einem Round-Trip.
  • Persistenz gewünscht — AOF / RDB überleben Redis-Neustarts.
  • Du betreibst schon Redis — bestehende Infrastruktur wiederverwenden.

Für Single-Pod ist In-Memory einfacher.

type RedisCacheOptionsType = {
url?: string; // 'redis://host:port'
host?: string;
port?: number;
password?: string;
db?: number;
keyPrefix?: string;
client?: RedisClientLike; // vorgefertigter ioredis-Client
};

URL-Form:

const redisCacheOptions = RedisCacheOptions.create().withUrl('redis://localhost:6379/0');
new RedisCache(redisCacheOptions);
const redisCache2Options = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');
new RedisCache(redisCache2Options); // TLS
const redisCache3Options = RedisCacheOptions.create().withUrl('redis://user:pass@host:6379');
new RedisCache(redisCache3Options);

Feld-Form:

const redisCacheOptions = RedisCacheOptions.create()
.withHost('redis.example.com')
.withPort(6379)
.withPassword(process.env.REDIS_PASS)
.withDb(1)
.withKeyPrefix('my-app:');
new RedisCache(
redisCacheOptions,
);

keyPrefix wird auf jeden Key angewendet — nützlich, wenn du eine Redis-Instanz über mehrere Apps teilst:

keyPrefix: 'my-app:cache:'
// → 'my-app:cache:user:42', 'my-app:cache:session:abc', ...

Das Framework registriert die Redis-Factory selbst; ein Cache kommt also auf Redis hoch, ohne registerCache-Aufruf und ohne irgendein new RedisCache(...) in deinem Code — es braucht nur eine Plugin-Id und einen Block:

actor-ts.cache {
sessions.plugin = "actor-ts.cache.redis" # cache('sessions') is Redis
redis {
url = ${?REDIS_URL} # or host/port below
db = 0
key-prefix = "my-app:"
password = ${?REDIS_PASSWORD}
}
}

Die Blätter sind die Felder aus RedisCacheOptionsType oben in kebab-case. host und port werden gelesen, stehen in der reference.conf aber als Kommentare: url schließt sie gegenseitig aus, und ein ausgeliefertes host = "localhost" wäre für jedes Deployment gesetzt und machte jede url zu einem OptionsError. Ungesetzt nimmt ioredis sein eigenes 127.0.0.1:6379.

Ein leerer String bedeutet „nicht gesetzt”. url, key-prefix und password werden als "" ausgeliefert, damit du die Form des Keys siehst; der Reader verwirft sie, statt sie weiterzureichen. Explizite Options stechen den Block, und der Block sticht die eingebauten Defaults.

Jeder benannte Cache kann eigene Verbindungs-Settings haben, Blatt für Blatt über den globalen Block gelegt — genau das lässt zwei Consumer sich einen Server teilen, ohne sich eine Datenbank zu teilen:

actor-ts.cache {
redis.url = ${?REDIS_URL}
rate-limit { plugin = "actor-ts.cache.redis", redis.db = 1 }
idempotency { plugin = "actor-ts.cache.redis", redis.db = 2 }
}

ioredis ist ein lazy geladener optionaler Peer, der Block kostet also nichts, solange kein Cache tatsächlich darauf auflöst: Der Treiber wird bei der ersten Cache-Operation importiert, nicht beim Start. Ein ungültiger Wert wird beim ersten cache(name) mit einem OptionsError abgelehnt, der das Feld benennt.

import { Cluster } from 'ioredis';
const redisCacheOptions = RedisCacheOptions.create().withClient(
new Cluster([
{ host: 'redis-1', port: 6379 },
{ host: 'redis-2', port: 6379 },
{ host: 'redis-3', port: 6379 },
]),
);
new RedisCache(
redisCacheOptions,
);

ioredis übernimmt das Cluster-Protokoll (MOVED-/ASK-Redirects, Slot-Tracking). Nimm Redis Cluster für horizontale Skalierung über den Speicher eines einzelnen Redis-Servers hinaus.

const redisCacheOptions = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');
new RedisCache(redisCacheOptions);
// TLS wird über das URL-Schema `rediss://` gewählt:
const redisCache2Options = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');
new RedisCache(redisCache2Options);

Das URL-Präfix rediss:// wählt TLS — oder gib einen vorgefertigten TLS-Client via withClient mit. Cert- Verifizierung läuft über Nodes TLS-Defaults; für selbstsignierte Zertifikate im Dev brauchst du explizite ioredis-TLS-Optionen.

const users = await cache.mget<User>(['user:1', 'user:2', 'user:3']);
// ↑
// ein MGET-Round-Trip

mget auf RedisCache → ein einzelner Redis-MGET-Befehl → ein Netzwerk-Round-Trip. Entscheidend für das Muster der Hydratation gesharder Entitäten (State für viele Entitäten beim Node-Start wieder aufbauen).

Beide mappen auf Redis-Primitive:

  • incr → Redis INCR (atomar, kein Race).
  • setIfAbsent → Redis SET NX (atomares CAS).

Wird von der Rate-Limit- + Idempotency-Key-Middleware des Frameworks genutzt. Sicher über Pods hinweg.

Redis ist das am besten geeignete Backend zum Locken: ein Key lebt in einem logischen Keyspace, SET NX entscheidet ein Rennen also für jeden Pod gleich. Siehe acquireLock für das dazu passende tokengeprüfte Release.

// Nicht direkt im Cache exponiert; ioredis-Pipelining ist automatisch
// für gebatcheten Aufrufe innerhalb desselben Ticks.

ioredis pipelined Befehle, die im selben JS-Tick abgesetzt werden, und sendet sie in einem einzigen TCP-Write. Das Cache- Interface exponiert Pipelining nicht explizit; die Implementierung des Frameworks nutzt Pipelining, wo hilfreich.

Terminal-Fenster
npm install ioredis
# oder: bun add ioredis

ioredis ist der zugrunde liegende Client. Versionen 5+ sind getestet.

Redis unterstützt zwei Persistenz-Modi:

  • RDB — periodische Snapshots. Default in vielen Configs.
  • AOF — Append-only-Log. Durabler, langsamer.

Der Cache des Frameworks kümmert sich nicht um Redis-seitige Persistenz-Config — Caches sind opportunistisch. Aber für Cache-Überleben über Redis-Neustarts aktiviere mindestens RDB.

const redisCacheOptions = RedisCacheOptions.create().withUrl(
'rediss://default:password@my-cluster.cache.amazonaws.com:6380',
);
new RedisCache(
redisCacheOptions,
);

AWS ElastiCache, GCP Memorystore, Azure Cache for Redis — alle unterstützen rediss://-URLs. Nutze sie.

import { Cluster } from 'ioredis';
const redisCacheOptions = RedisCacheOptions.create().withClient(
new Cluster([...], {
enableReadyCheck: true,
redisOptions: { maxRetriesPerRequest: 3 },
}),
);
new RedisCache(
redisCacheOptions,
);

Defaultet auf vernünftige ioredis-Defaults. Für sehr enge Latenz oder spezifische Connection-Pool-Größen gib ioredis-artige Optionen explizit mit.