design-cache-layer
Design a Redis cache layer — key schema, TTLs, eviction policy, stampede + thundering-herd protection, hot-key + big-key avoidance. Use after caching-tradeoffs picks where; not Redis server config.
- License 许可
- MIT
- 最近更新
- 2026-10-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- design-cache-layer
- description
- Design a Redis cache layer — key schema, TTLs, eviction policy, stampede + thundering-herd protection, hot-key + big-key avoidance. Use after caching-tradeoffs picks where; not Redis server config.
03 SKILL.md 正文
design-cache-layer
Cache design that survives Black Friday, not just the demo. Output: key schema, TTL strategy, write/read path, failure modes considered.
Mode: analytical — judgment inside a fixed frame. Keep the output shape; every verdict cites its evidence; unknowns are marked [TBD] or [VERIFY], never filled in.
When to use
- A read-heavy endpoint needs caching.
- An existing cache is causing incidents (stampedes, hot keys, memory pressure).
- A PRD says "use Redis" with no further detail.
Inputs
- The cache shape decided by
polymath-performance:caching-tradeoffs(what, where, invalidation, staleness) — required; without it, run that first. - Traffic: request rate, key cardinality, value sizes, hot-key candidates (measured or
[TBD]). - The Redis deployment (optional): managed vs self-hosted, cluster vs single primary, memory limit.
Related skills
polymath-performance:caching-tradeoffs— vendor-agnostic decision: what to cache, where to cache, staleness tolerance, failure modes. Run that first to decide the shape; use this skill to ship the Redis layer.polymath-performance:audit-redis-config— once the cache layer is running, reviewmaxmemory, eviction, persistence, replication.
Procedure
- Identify the value. Caching is for expensive-to-compute, frequently-read, eventually-consistent values. If the data is cheap to compute or strongly consistent, do not cache.
- Key schema. Structured + versioned:
The<domain>:<entity>:<id>:v<version> e.g. refund:profile:42:v3 <domain>:list:<filter-hash>:v<version> e.g. refund:list:sha8af2:v3v<n>suffix lets a deploy invalidate everything by bumping it; the alternative (deleting keys) is slow on large keyspaces. - TTL strategy.
- Per-entry TTL with jitter:
TTL = base ± random(0, base/10). Prevents synchronized expiry storms. - Sliding TTL only when reads are bursty around a record (re-set on hit).
- Negative caching: also cache "not found" for a shorter TTL to absorb 404 floods.
- Per-entry TTL with jitter:
- Eviction.
maxmemory-policy = allkeys-lrufor pure caches;volatile-lruif you also store non-cache data with no TTL. - Read path with stampede protection.
Single-flight by lock; concurrent misses don't all hammer the origin. A plainvalue = GET key if value: return value # cache miss token = random_uuid() if SET nx:lock:key token NX EX=5: try: value = expensive_compute() SET key value EX=jittered_ttl return value finally: # release only OUR lock — compare-and-delete in one Lua call EVAL "if redis.call('get',KEYS[1])==ARGV[1] then return redis.call('del',KEYS[1]) end return 0" 1 nx:lock:key token for attempt in 1..3: # someone else is computing sleep(50ms × attempt) value = GET key if value: return value return serve_stale_or_compute_without_caching() # bounded wait, never spin foreverDELwould delete another worker's lock if compute outlived the 5 s expiry. - Write path. Update-then-invalidate (
SET origin = new; DEL key) is simpler than write-through. Know its race: a reader that fetched the old value before the write can re-populate the cache after theDEL. Bound it with the TTL, a version in the key/value, or a delayed secondDEL, depending on how much staleness the data tolerates. - Hot keys. A key with > 1% of total RPS is a hot key. Strategies:
- Shard the value into multiple keys (
refund:profile:42:shard:{0..9}round-robin). - Use a local in-process cache in front (Caffeine / lru-cache) for sub-second TTL.
- Shard the value into multiple keys (
- Big keys. A single key > 100KB or a single LIST/HASH with > 10k items is a big key. Cluster mode bites on slot rebalances; split.
- Failure modes.
- Cache down → origin slammed. Add a circuit breaker that fails open (skip cache) for a short window.
- Origin slow + cache miss → request hangs. Set a cache-fill timeout and serve stale.
- Observability. Hit ratio, miss latency, eviction rate, slow-log entries. Without these, you don't know if the cache is helping or hurting.
Output
design-cache-layer
Endpoint: GET /refund/profile/:id
Value: RefundProfile (~5KB JSON, computed from 4 SQL queries)
Key schema
refund:profile:<id>:v3 primary
nx:lock:refund:profile:<id>:v3 EX=5s, NX stampede guard
TTL: 300s ± 30s (jitter)
Negative: 10s for not-found
Eviction: allkeys-lru, maxmemory ~ 8GB.
Read path:
GET → on miss, NX-lock → compute → SET EX=jittered → DEL lock.
Write path:
Update SQL → DEL refund:profile:<id>:v3.
Failure modes covered:
✓ stampede via NX lock
✓ thundering herd via TTL jitter
✓ origin slowness via cache-fill timeout + stale-serve
⚠ hot key: monitor; shard if a single id exceeds 1% RPS
Observability: hit ratio, miss latency p99, eviction rate, slow-log.
Quality bar
- Key schema versioned for cheap global invalidation.
- TTL has jitter.
- Stampede protection in the read path: token-owned lock, compare-and-delete release, bounded waiting.
- Failure modes named, not assumed.
Anti-patterns to avoid
- TTL without jitter on a hot key. Synchronized expiry → origin stampede.
- Write-through caching for everything. Couples writes to cache latency.
- Forgetting negative caching. 404 floods are real.
- Using Redis as a primary store without persistence understanding. RDB + AOF have different durability stories.
04 同仓库更多 Skills
runbook
Write or refresh an operational runbook for an alert/symptom; structured as TL;DR + Pre-checks + Steps + Verification + Rollback + Escalation.
rfc
Draft a lightweight design RFC to docs/rfcs/<slug>.md; Summary, Motivation, Detailed design, Drawbacks, Alternatives, Unresolved questions. A proposal to debate, not a recorded decision (adr).
editorial-pass
Review and tighten prose in a Markdown artifact for a target tone (terse, formal, friendly) without dropping information; preserve quotations and load-bearing constraints.
architecture-review-facilitation
Run an architecture review as a process — entry criteria, reviewer checklist, decision log, and follow-up actions — pairing the design artifact with a red-team pass.
architecture-doc
Write a C4-style architecture document; System Context + Containers (+ Components when interesting) with mermaid diagrams. Describes structure, not a decision (adr) or proposal (rfc).
adr
Write an Architecture Decision Record (Michael Nygard format) to docs/adrs/NNNN-<slug>.md; frontmatter validated by the ADR artifact schema. Records a made decision, not a proposal to debate (rfc).