public-redis-expert-base

Redis 知识基座。覆盖数据结构选型、Key 命名、连接池与 Pipeline、集群与副本读取、TTL 与淘汰策略。供 devlab-redis-usage 通过 extends 继承。

SKILL.md

GitHub

Redis Knowledge Base

Foundational guidance for modeling data in Redis and connecting to it efficiently.

Source: Adapted from redis/agent-skills (redis-core + redis-connections + redis-clustering). Official Redis team content.

Workflow

  1. Identify the access pattern (read/write mix, data shape, latency target).
  2. Choose the matching data structure (Section 1).
  3. Design key names following conventions (Section 2).
  4. Configure connection pool and timeouts (Section 3).
  5. Batch work with pipelining (Section 4).
  6. Plan for cluster mode if scaling (Section 5).

Data Structure Selection

Pick the type that matches the access pattern, not just the shape of the data.

Use case Recommended type Why
Simple values, counters String Atomic INCR/DECR, SET/GET
Object with independently updated fields Hash Per-field reads/writes, no whole-object rewrite
Queue, recent-N items List O(1) push/pop at ends
Unique items, membership checks Set O(1) SADD/SISMEMBER/SCARD
Rankings, score-based ranges Sorted Set Score-ordered; ZADD/ZRANGE/ZRANK
Nested / hierarchical data JSON Path-level updates, nested arrays, RQE indexing
Event log, fan-out messaging Stream Persistent, consumer groups
Vector similarity Vector Set Native vector storage with HNSW

Common anti-pattern: stuffing a flat object into a serialized string. Use a Hash instead.

References:

Key Naming

Use colon-separated segments with a stable hierarchy:

{entity}:{id}:{attribute}
user:1001:profile
session:abc123
article:987:likes

Rules:

  • Lowercase, colon-separated. No spaces, no mixed casing.
  • Keep keys short but readable.
  • Don't use full URLs or long strings as keys.
  • Prefix for multi-tenancy (tenant:42:user:7:cart).

References:

Connection Management

Always use pooling or multiplexing — never one connection per request.

Style Used by Note
Pool redis-py, Jedis, go-redis Each lease blocks if pool exhausted
Multiplex Lettuce, NRedisStack Single connection; cannot carry blocking commands

Set explicit timeouts: connect timeout shorter than read/write timeout.

References:

Pipelining & Batching

For N commands that don't depend on each other's results, send as a single batch.

pipe = redis.pipeline()
for user_id in user_ids:
    pipe.get(f"user:{user_id}")
results = pipe.execute()

Avoid commands that scan everything: use SCAN instead of KEYS, SSCAN instead of SMEMBERS on large sets.

References:

Clustering & Replication

In Redis Cluster, keys are distributed across 16,384 slots. Multi-key operations require all keys on the same slot — use hash tags: {user:1001}:profile.

For read-heavy workloads, route reads to replicas (eventually consistent).

References:

TTL & Eviction

  • Always set TTL for cache keys; never rely on manual cleanup.
  • Use EXPIRE / PEXPIRE for time-based eviction.
  • Choose eviction policy based on workload: allkeys-lru for cache, volatile-lru for mixed.
  • Monitor evicted_keys in INFO stats to detect memory pressure.

Guardrails

  • Never use KEYS * in production — use SCAN.
  • Never HGETALL or SMEMBERS on large containers — use HSCAN/SSCAN.
  • Prefer Hash over serialized String for objects with multiple fields.
  • Set TTL on all cache keys; avoid manual cleanup patterns.

参考文档:

  • references/REFERENCE-README.md