Claude Code + Redis缓存全链路实战：从Cache-Aside到分布式锁

flowchart TB
    A[需求分析] --> B[CLAUDE.md配置]
    B --> C[基础Cache-Aside实现]
    C --> D[集成测试]
    D --> E{性能达标?}
    E -->|否| F[优化策略<br/>Write-Through/Behind]
    F --> D
    E -->|是| G[高级特性<br/>分布式锁/防击穿]
    G --> H[生产部署配置]
    H --> I[监控告警]

    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style E fill:#fff9c4

mkdir redis-cache-demo && cd redis-cache-demo
npm init -y
npm install ioredis express dotenv
npm install -D jest ioredis-mock

redis-cache-demo/
├── CLAUDE.md              # 项目级Claude Code指令
├── src/
│   ├── cache/
│   │   ├── client.js      # Redis连接管理
│   │   ├── strategies.js  # 五种缓存策略
│   │   ├── lock.js        # 分布式锁
│   │   └── stampede.js    # 防缓存击穿
│   ├── services/
│   │   └── userService.js # 业务服务层
│   └── app.js             # Express入口
├── tests/
│   ├── cache.test.js
│   └── stampede.test.js
└── docker-compose.yml     # Redis本地环境

# Redis缓存架构项目

## 技术栈
- Node.js 18+ / Express
- Redis 8.0 (ioredis客户端)
- Jest测试框架

## 缓存策略规范
- 默认使用Cache-Aside（懒加载）模式
- 热点数据使用Write-Through保证一致性
- 所有缓存键必须设置TTL，默认300秒
- 键命名格式：`{service}:{entity}:{id}:{field}`
- 序列化使用JSON，大对象考虑MessagePack

## 代码风格
- 使用ES模块 (import/export)
- 异步函数统一try-catch错误处理
- 日志使用console.error，不使用第三方日志库
- Redis操作失败时降级到数据库查询，不向上抛出错误

## 测试要求
- 每个缓存策略至少3个测试用例（命中、未命中、错误）
- 使用ioredis-mock模拟Redis
- 覆盖缓存穿透、击穿、雪崩场景

# docker-compose.yml
services:
  redis:
    image: redis:8.0
    ports:
      - "6379:6379"
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - redis-data:/data

volumes:
  redis-data:

docker compose up -d

claude

import Redis from 'ioredis';

const clients = new Map();

export function createClient(options = {}) {
  const key = JSON.stringify(options);

  if (clients.has(key)) {
    return clients.get(key);
  }

  const client = options.cluster
    ? new Redis.Cluster(options.nodes, {
        redisOptions: { password: options.password },
        ...options.clusterOptions,
      })
    : new Redis({
        host: options.host || process.env.REDIS_HOST || '127.0.0.1',
        port: options.port || parseInt(process.env.REDIS_PORT) || 6379,
        password: options.password || process.env.REDIS_PASSWORD,
        db: options.db || 0,
        maxRetriesPerRequest: 3,
        retryStrategy(times) {
          const delay = Math.min(times * 200, 5000);
          return delay;
        },
        enableReadyCheck: true,
        lazyConnect: true,
      });

  client.on('error', (err) => {
    console.error('[Redis] Connection error:', err.message);
  });

  client.on('reconnecting', () => {
    console.error('[Redis] Reconnecting...');
  });

  clients.set(key, client);
  return client;
}

export async function healthCheck(client) {
  try {
    const start = Date.now();
    await client.ping();
    return { status: 'healthy', latency: Date.now() - start };
  } catch (err) {
    return { status: 'unhealthy', error: err.message };
  }
}

export async function gracefulShutdown() {
  for (const [key, client] of clients) {
    await client.quit();
    clients.delete(key);
  }
}

import { createClient } from './client.js';

export class CacheAsideStrategy {
  constructor(client) {
    this.client = client;
  }

  async get(key, fallback, ttl = 300) {
    try {
      const cached = await this.client.get(key);
      if (cached !== null) {
        return JSON.parse(cached);
      }

      const data = await fallback();
      if (data !== null && data !== undefined) {
        await this.client.setex(key, ttl, JSON.stringify(data));
      }
      return data;
    } catch (err) {
      console.error(`[CacheAside] Error for key ${key}:`, err.message);
      return fallback();
    }
  }
}

export class ReadThroughStrategy {
  constructor(client, loader) {
    this.client = client;
    this.loader = loader;
  }

  async get(key, ttl = 300) {
    try {
      const cached = await this.client.get(key);
      if (cached !== null) {
        return JSON.parse(cached);
      }

      const data = await this.loader(key);
      if (data !== null && data !== undefined) {
        await this.client.setex(key, ttl, JSON.stringify(data));
      }
      return data;
    } catch (err) {
      console.error(`[ReadThrough] Error for key ${key}:`, err.message);
      return this.loader(key);
    }
  }
}

export class WriteThroughStrategy {
  constructor(client, writer) {
    this.client = client;
    this.writer = writer;
  }

  async set(key, data, ttl = 300) {
    try {
      await this.writer(key, data);
      await this.client.setex(key, ttl, JSON.stringify(data));
    } catch (err) {
      console.error(`[WriteThrough] Error for key ${key}:`, err.message);
      throw err;
    }
  }

  async delete(key) {
    try {
      await this.client.del(key);
    } catch (err) {
      console.error(`[WriteThrough] Delete error:`, err.message);
    }
  }
}

export class WriteBehindStrategy {
  constructor(client, writer, options = {}) {
    this.client = client;
    this.writer = writer;
    this.flushInterval = options.flushInterval || 5000;
    this.buffer = new Map();
    this.timer = null;
  }

  start() {
    this.timer = setInterval(() => this.flush(), this.flushInterval);
  }

  stop() {
    if (this.timer) clearInterval(this.timer);
    return this.flush();
  }

  async set(key, data, ttl = 300) {
    try {
      await this.client.setex(key, ttl, JSON.stringify(data));
      this.buffer.set(key, data);
    } catch (err) {
      console.error(`[WriteBehind] Set error:`, err.message);
    }
  }

  async flush() {
    if (this.buffer.size === 0) return;

    const batch = new Map(this.buffer);
    this.buffer.clear();

    for (const [key, data] of batch) {
      try {
        await this.writer(key, data);
      } catch (err) {
        console.error(`[WriteBehind] Flush error for ${key}:`, err.message);
        this.buffer.set(key, data);
      }
    }
  }
}

export class RefreshAheadStrategy {
  constructor(client, loader, options = {}) {
    this.client = client;
    this.loader = loader;
    this.refreshRatio = options.refreshRatio || 0.8;
    this.timers = new Map();
  }

  async get(key, ttl = 300) {
    try {
      const cached = await this.client.get(key);
      if (cached === null) {
        const data = await this.loader(key);
        if (data !== null && data !== undefined) {
          await this.client.setex(key, ttl, JSON.stringify(data));
        }
        return data;
      }

      const ttlRemaining = await this.client.ttl(key);
      if (ttlRemaining > 0 && ttlRemaining < ttl * (1 - this.refreshRatio)) {
        this.backgroundRefresh(key, ttl);
      }

      return JSON.parse(cached);
    } catch (err) {
      console.error(`[RefreshAhead] Error for key ${key}:`, err.message);
      return this.loader(key);
    }
  }

  async backgroundRefresh(key, ttl) {
    try {
      const data = await this.loader(key);
      if (data !== null && data !== undefined) {
        await this.client.setex(key, ttl, JSON.stringify(data));
      }
    } catch (err) {
      console.error(`[RefreshAhead] Background refresh failed:`, err.message);
    }
  }
}

graph TD
    Start[选择缓存策略] --> Q1{读写比例?}
    Q1 -->|读多写少| Q2{一致性要求?}
    Q1 -->|写多读少| Q3{可接受数据丢失?}
    Q1 -->|读写均衡| WriteThrough[Write-Through]

    Q2 -->|最终一致性| CacheAside[Cache-Aside]
    Q2 -->|强一致性| Q4{延迟容忍?}
    Q4 -->|低延迟| RefreshAhead[Refresh-Ahead]
    Q4 -->|可接受| WriteThrough2[Write-Through]

    Q3 -->|不可接受| WriteThrough3[Write-Through]
    Q3 -->|可接受少量| WriteBehind[Write-Behind]

    style CacheAside fill:#c8e6c9
    style WriteThrough fill:#bbdefb
    style WriteBehind fill:#fff9c4
    style RefreshAhead fill:#f3e5f5

export class SingleFlight {
  constructor() {
    this.flights = new Map();
  }

  async execute(key, fn, ttl, cacheClient) {
    if (this.flights.has(key)) {
      return this.flights.get(key);
    }

    const promise = fn()
      .then(async (data) => {
        if (data !== null && data !== undefined) {
          await cacheClient.setex(key, ttl, JSON.stringify(data));
        }
        return data;
      })
      .finally(() => {
        this.flights.delete(key);
      });

    this.flights.set(key, promise);
    return promise;
  }
}

import { randomUUID } from 'crypto';

export class DistributedLock {
  constructor(client, options = {}) {
    this.client = client;
    this.ttl = options.ttl || 10000;
    this.retryDelay = options.retryDelay || 200;
    this.maxRetries = options.maxRetries || 10;
  }

  async acquire(key) {
    const token = randomUUID();
    const lockKey = `lock:${key}`;
    let retries = 0;

    while (retries < this.maxRetries) {
      const result = await this.client.set(
        lockKey, token, 'PX', this.ttl, 'NX'
      );

      if (result === 'OK') {
        const timer = setInterval(async () => {
          const exists = await this.client.get(lockKey);
          if (exists === token) {
            await this.client.pexpire(lockKey, this.ttl);
          } else {
            clearInterval(timer);
          }
        }, this.ttl * 0.6);

        return {
          token,
          release: async () => {
            clearInterval(timer);
            const script = `
              if redis.call("get", KEYS[1]) == ARGV[1] then
                return redis.call("del", KEYS[1])
              else
                return 0
              end
            `;
            await this.client.eval(script, 1, lockKey, token);
          },
        };
      }

      retries++;
      await new Promise((r) => setTimeout(r, this.retryDelay));
    }

    throw new Error(`Failed to acquire lock for ${key} after ${this.maxRetries} retries`);
  }

  async withLock(key, fn) {
    const lock = await this.acquire(key);
    try {
      return await fn();
    } finally {
      await lock.release();
    }
  }
}

import { createClient } from '../cache/client.js';
import { CacheAsideStrategy } from '../cache/strategies.js';
import { WriteThroughStrategy } from '../cache/strategies.js';
import { SingleFlight } from '../cache/stampede.js';
import { DistributedLock } from '../cache/lock.js';

const redis = createClient();
const cacheAside = new CacheAsideStrategy(redis);
const writeThrough = new WriteThroughStrategy(redis, async (key, data) => {
  await db.updateUser(data.id, data);
});
const flight = new SingleFlight();
const lock = new DistributedLock(redis, { ttl: 5000 });

// 模拟数据库
const db = {
  users: new Map([
    ['user:1', { id: 1, name: 'Alice', email: '[email protected]' }],
    ['user:2', { id: 2, name: 'Bob', email: '[email protected]' }],
  ]),

  async findUserById(id) {
    // 模拟数据库延迟
    await new Promise((r) => setTimeout(r, 50));
    return this.users.get(`user:${id}`) || null;
  },

  async updateUser(id, data) {
    await new Promise((r) => setTimeout(r, 80));
    this.users.set(`user:${id}`, { ...data, id });
    return data;
  },
};

export class UserService {
  async getUserById(id) {
    const cacheKey = `user:svc:user:${id}`;

    return cacheAside.get(cacheKey, async () => {
      return flight.execute(cacheKey, () => db.findUserById(id), 300, redis);
    }, 300);
  }

  async updateUser(id, data) {
    const cacheKey = `user:svc:user:${id}`;
    const updated = { ...data, id };

    return lock.withLock(`user:${id}`, async () => {
      await writeThrough.set(cacheKey, updated, 300);
      return updated;
    });
  }

  async invalidateUser(id) {
    const cacheKey = `user:svc:user:${id}`;
    await redis.del(cacheKey);
  }

  async getUserProfile(id) {
    const cacheKey = `user:svc:profile:${id}`;
    return cacheAside.get(cacheKey, async () => {
      const user = await this.getUserById(id);
      if (!user) return null;
      return {
        ...user,
        avatar: `https://api.dicebear.com/7.x/avataaars/svg?seed=${user.name}`,
        joinedAt: '2025-01-15',
      };
    }, 600);
  }
}

import express from 'express';
import { UserService } from './services/userService.js';
import { healthCheck, gracefulShutdown } from './cache/client.js';
import { createClient } from './cache/client.js';

const app = express();
app.use(express.json());

const userService = new UserService();
const redis = createClient();

app.get('/health', async (req, res) => {
  const redisHealth = await healthCheck(redis);
  res.json({ status: 'ok', redis: redisHealth });
});

app.get('/api/users/:id', async (req, res) => {
  try {
    const user = await userService.getUserById(req.params.id);
    if (!user) return res.status(404).json({ error: 'User not found' });
    res.json(user);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.put('/api/users/:id', async (req, res) => {
  try {
    const user = await userService.updateUser(req.params.id, req.body);
    res.json(user);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.delete('/api/users/:id/cache', async (req, res) => {
  await userService.invalidateUser(req.params.id);
  res.json({ message: 'Cache invalidated' });
});

const server = app.listen(3000, () => {
  console.log('Server running on port 3000');
});

process.on('SIGTERM', async () => {
  server.close();
  await gracefulShutdown();
  process.exit(0);
});

import { CacheAsideStrategy } from '../src/cache/strategies.js';

describe('CacheAsideStrategy', () => {
  let mockClient;
  let strategy;

  beforeEach(() => {
    mockClient = {
      get: jest.fn(),
      setex: jest.fn(),
    };
    strategy = new CacheAsideStrategy(mockClient);
  });

  test('cache hit - returns cached data without calling fallback', async () => {
    mockClient.get.mockResolvedValue(JSON.stringify({ id: 1, name: 'Alice' }));

    const fallback = jest.fn();
    const result = await strategy.get('user:1', fallback, 300);

    expect(result).toEqual({ id: 1, name: 'Alice' });
    expect(fallback).not.toHaveBeenCalled();
    expect(mockClient.setex).not.toHaveBeenCalled();
  });

  test('cache miss - calls fallback and caches result', async () => {
    mockClient.get.mockResolvedValue(null);
    mockClient.setex.mockResolvedValue('OK');
    const fallback = jest.fn().mockResolvedValue({ id: 1, name: 'Alice' });

    const result = await strategy.get('user:1', fallback, 300);

    expect(result).toEqual({ id: 1, name: 'Alice' });
    expect(fallback).toHaveBeenCalledTimes(1);
    expect(mockClient.setex).toHaveBeenCalledWith(
      'user:1', 300, JSON.stringify({ id: 1, name: 'Alice' })
    );
  });

  test('Redis error - degrades to fallback', async () => {
    mockClient.get.mockRejectedValue(new Error('Connection refused'));
    const fallback = jest.fn().mockResolvedValue({ id: 1, name: 'Alice' });

    const result = await strategy.get('user:1', fallback, 300);

    expect(result).toEqual({ id: 1, name: 'Alice' });
    expect(fallback).toHaveBeenCalledTimes(1);
  });

  test('null result - does not cache', async () => {
    mockClient.get.mockResolvedValue(null);
    const fallback = jest.fn().mockResolvedValue(null);

    const result = await strategy.get('user:99', fallback, 300);

    expect(result).toBeNull();
    expect(mockClient.setex).not.toHaveBeenCalled();
  });
});

// tests/stampede.test.js
import { SingleFlight } from '../src/cache/stampede.js';

describe('SingleFlight防击穿', () => {
  test('100个并发请求只触发1次数据库查询', async () => {
    const flight = new SingleFlight();
    let dbCalls = 0;

    const mockFn = async () => {
      dbCalls++;
      await new Promise((r) => setTimeout(r, 100));
      return { id: 1, name: 'Alice' };
    };

    const mockCacheClient = {
      setex: jest.fn().mockResolvedValue('OK'),
    };

    const promises = Array(100)
      .fill(null)
      .map(() => flight.execute('user:1', mockFn, 300, mockCacheClient));

    const results = await Promise.all(promises);

    expect(dbCalls).toBe(1);
    expect(results).toHaveLength(100);
    results.forEach((r) => expect(r).toEqual({ id: 1, name: 'Alice' }));
  });
});

npx jest --verbose

PASS tests/cache.test.js
  CacheAsideStrategy
    ✓ cache hit - returns cached data without calling fallback (5ms)
    ✓ cache miss - calls fallback and caches result (3ms)
    ✓ Redis error - degrades to fallback (2ms)
    ✓ null result - does not cache (1ms)

PASS tests/stampede.test.js
  SingleFlight防击穿
    ✓ 100个并发请求只触发1次数据库查询 (112ms)

import { createClient } from './client.js';

export class SemanticCache {
  constructor(client, options = {}) {
    this.client = client;
    this.similarityThreshold = options.threshold || 0.92;
    this.ttl = options.ttl || 3600;
    this.vectorSetName = 'semantic_cache';
  }

  async set(queryEmbedding, response, metadata = {}) {
    const id = `cache:${Date.now()}:${Math.random().toString(36).slice(2)}`;

    // Redis 8 Vector Set: VADD存储向量
    await this.client.call(
      'VADD', this.vectorSetName,
      'FP32', ...queryEmbedding,
      id
    );

    // 存储完整响应到Hash
    await this.client.hset(`scache:${id}`, {
      response: JSON.stringify(response),
      query: metadata.query || '',
      created: Date.now().toString(),
    });
    await this.client.expire(`scache:${id}`, this.ttl);

    return id;
  }

  async get(queryEmbedding) {
    // VSIM搜索最相似的向量
    const results = await this.client.call(
      'VSIM', this.vectorSetName,
      'FP32', ...queryEmbedding,
      'COUNT', 1,
      'WITHSCORES'
    );

    if (!results || results.length < 2) return null;

    const [id, score] = results;
    if (parseFloat(score) < this.similarityThreshold) return null;

    const cached = await this.client.hgetall(`scache:${id}`);
    if (!cached || !cached.response) return null;

    return {
      response: JSON.parse(cached.response),
      similarity: parseFloat(score),
      originalQuery: cached.query,
      cachedAt: parseInt(cached.created),
    };
  }
}

import { SemanticCache } from './cache/semanticCache.js';
import { createClient } from './cache/client.js';

const redis = createClient();
const semanticCache = new SemanticCache(redis, {
  threshold: 0.90,
  ttl: 7200,
});

// 假设你有一个获取embedding的函数
async function getEmbedding(text) {
  const resp = await fetch('https://api.anthropic.com/v1/embeddings', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.ANTHROPIC_API_KEY,
    },
    body: JSON.stringify({ model: 'claude-3-embedding', input: text }),
  });
  const data = await resp.json();
  return data.data[0].embedding;
}

app.post('/api/chat', async (req, res) => {
  const { message } = req.body;
  const embedding = await getEmbedding(message);

  // 先检查语义缓存
  const cached = await semanticCache.get(embedding);
  if (cached) {
    return res.json({
      response: cached.response,
      fromCache: true,
      similarity: cached.similarity,
    });
  }

  // 缓存未命中，调用LLM
  const llmResponse = await callLLM(message);

  // 存入语义缓存
  await semanticCache.set(embedding, llmResponse, { query: message });

  res.json({ response: llmResponse, fromCache: false });
});

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY src ./src
COPY package.json ./

ENV NODE_ENV=production
ENV REDIS_HOST=redis-production
ENV REDIS_PORT=6379

USER node
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -q --spider http://localhost:3000/health || exit 1

CMD ["node", "src/app.js"]

## Redis缓存生产部署检查清单

### 连接管理
- [ ] maxRetriesPerRequest设置为3-5
- [ ] 启用lazyConnect避免启动阻塞
- [ ] 配置retryStrategy指数退避
- [ ] 连接池大小匹配并发量（默认10）

### 内存管理
- [ ] 设置maxmemory（建议物理内存的70%）
- [ ] 选择合适的eviction policy（allkeys-lru通用场景）
- [ ] 监控used_memory_rss碎片率
- [ ] 大value（>10KB）考虑压缩或拆分

### 安全
- [ ] 启用AUTH密码或ACL
- [ ] 禁止外网访问（bind 127.0.0.1或内网IP）
- [ ] 启用TLS（生产环境必须）
- [ ] 禁用危险命令（FLUSHALL、CONFIG）

### 高可用
- [ ] Sentinel或Cluster模式
- [ ] 最少6节点（3主3从）
- [ ] 持久化策略：AOF+RDB混合
- [ ] 跨可用区部署

### 监控
- [ ] 跟踪hit_rate（目标>80%）
- [ ] 监控eviction_rate
- [ ] SLOWLOG慢查询（>10ms）
- [ ] connected_clients连接数
- [ ] replication_lag主从延迟

flowchart LR
    subgraph 开发阶段
        A[CLAUDE.md配置] --> B[Claude Code<br/>生成缓存策略]
        B --> C[集成到业务层]
    end

    subgraph 测试阶段
        C --> D[Jest单元测试]
        D --> E[SingleFlight<br/>压力测试]
        E --> F[autocannon<br/>基准测试]
    end

    subgraph 生产阶段
        F --> G[Docker打包]
        G --> H[Redis Cluster<br/>部署]
        H --> I[Prometheus + Grafana<br/>监控]
        I --> J[告警规则]
    end

    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style J fill:#c8e6c9