真正在生产环境中管用的 Redis 缓存策略

import redis from "./redis";
 
interface CacheOptions {
  ttl?: number; // 秒
  prefix?: string;
}
 
async function cacheAside<T>(key: string, fetcher: () => Promise<T>, options: CacheOptions = {}): Promise<T> {
  const { ttl = 3600, prefix = "cache" } = options;
  const cacheKey = `${prefix}:${key}`;
 
  // 第 1 步：尝试从缓存读取
  const cached = await redis.get(cacheKey);
 
  if (cached !== null) {
    try {
      return JSON.parse(cached) as T;
    } catch {
      // 损坏的缓存条目，删除并继续
      await redis.del(cacheKey);
    }
  }
 
  // 第 2 步：缓存未命中——从源获取
  const result = await fetcher();
 
  // 第 3 步：存入缓存（不等待——发射即忘）
  redis.set(cacheKey, JSON.stringify(result), "EX", ttl).catch((err) => {
    console.error(`[Cache] Failed to set ${cacheKey}:`, err.message);
  });
 
  return result;
}

interface User {
  id: string;
  name: string;
  email: string;
  plan: "free" | "pro" | "enterprise";
}
 
async function getUser(userId: string): Promise<User | null> {
  return cacheAside<User | null>(
    `user:${userId}`,
    async () => {
      const row = await db.query("SELECT * FROM users WHERE id = $1", [userId]);
      return row[0] ?? null;
    },
    { ttl: 1800 }, // 30 分钟
  );
}

async function getUserSafe(userId: string): Promise<User | null> {
  return cacheAside<User | null>(
    `user:${userId}`,
    async () => {
      const row = await db.query("SELECT * FROM users WHERE id = $1", [userId]);
      return row[0] ?? null;
    },
    {
      // 空结果用更短的 TTL 来限制内存使用
      // 但要足够长以吸收重复的未命中
      ttl: row ? 1800 : 300,
    },
  );
}

async function getUserWithDynamicTTL(userId: string): Promise<User | null> {
  const cacheKey = `cache:user:${userId}`;
 
  const cached = await redis.get(cacheKey);
  if (cached !== null) {
    return JSON.parse(cached) as User | null;
  }
 
  const row = await db.query("SELECT * FROM users WHERE id = $1", [userId]);
  const user: User | null = row[0] ?? null;
 
  // 存在的结果缓存 30 分钟，空结果缓存 5 分钟
  const ttl = user ? 1800 : 300;
  await redis.set(cacheKey, JSON.stringify(user), "EX", ttl);
 
  return user;
}

async function updateUser(userId: string, updates: Partial<User>): Promise<User> {
  // 第 1 步：更新数据库
  const updated = await db.query(
    "UPDATE users SET name = COALESCE($2, name), email = COALESCE($3, email) WHERE id = $1 RETURNING *",
    [userId, updates.name, updates.email],
  );
  const user: User = updated[0];
 
  // 第 2 步：立即更新缓存
  const cacheKey = `cache:user:${userId}`;
  await redis.set(cacheKey, JSON.stringify(user), "EX", 1800);
 
  return user;
}

async function updateUserWriteBehind(userId: string, updates: Partial<User>): Promise<User> {
  const cacheKey = `cache:user:${userId}`;
 
  // 读取当前状态
  const current = await redis.get(cacheKey);
  const user = current ? (JSON.parse(current) as User) : null;
  if (!user) throw new Error("User not in cache");
 
  // 立即更新缓存
  const updated = { ...user, ...updates };
  await redis.set(cacheKey, JSON.stringify(updated), "EX", 1800);
 
  // 将数据库写入排队以进行异步处理
  await redis.rpush("write_behind:users", JSON.stringify({ userId, updates, timestamp: Date.now() }));
 
  return updated;
}

async function processWriteBehindQueue(): Promise<void> {
  while (true) {
    const item = await redis.blpop("write_behind:users", 5);
 
    if (item) {
      const { userId, updates } = JSON.parse(item[1]);
      try {
        await db.query("UPDATE users SET name = COALESCE($2, name), email = COALESCE($3, email) WHERE id = $1", [
          userId,
          updates.name,
          updates.email,
        ]);
      } catch (err) {
        // 失败时重新排队并带上重试计数
        console.error("[WriteBehind] Failed:", err);
        await redis.rpush("write_behind:users:dlq", item[1]);
      }
    }
  }
}

const TTL = {
  // 第 1 级：很少变化，计算成本高
  // 示例：商品目录、站点配置、功能开关
  STATIC: 86400, // 24 小时
 
  // 第 2 级：偶尔变化，中等成本
  // 示例：用户资料、团队设置、权限
  MODERATE: 1800, // 30 分钟
 
  // 第 3 级：频繁变化，计算便宜但调用频繁
  // 示例：信息流数据、通知计数、会话信息
  VOLATILE: 300, // 5 分钟
 
  // 第 4 级：临时性的，用于限流和锁
  EPHEMERAL: 60, // 1 分钟
 
  // 空结果：始终短生命周期
  NOT_FOUND: 120, // 2 分钟
} as const;

function ttlWithJitter(baseTtl: number, jitterPercent = 0.1): number {
  const jitter = baseTtl * jitterPercent;
  const offset = Math.random() * jitter * 2 - jitter;
  return Math.max(1, Math.round(baseTtl + offset));
}
 
// 不要：redis.set(key, value, "EX", 3600)
// 要：  redis.set(key, value, "EX", ttlWithJitter(3600))
 
// 3600 ± 10% = 3240 到 3960 之间的随机值

const ttl = ttlWithJitter(3600, 0.2); // 2880–4320 秒

async function getWithSlidingExpiry<T>(key: string, ttl: number): Promise<T | null> {
  // GETEX 原子性地获取值并重置 TTL
  const value = await redis.getex(key, "EX", ttl);
  if (value === null) return null;
  return JSON.parse(value) as T;
}

async function getWithSlidingExpiryCompat<T>(key: string, ttl: number): Promise<T | null> {
  const pipeline = redis.pipeline();
  pipeline.get(key);
  pipeline.expire(key, ttl);
  const results = await pipeline.exec();
 
  if (!results || !results[0] || results[0][1] === null) return null;
  return JSON.parse(results[0][1] as string) as T;
}

async function cacheAsideWithMutex<T>(key: string, fetcher: () => Promise<T>, ttl: number = 3600): Promise<T | null> {
  const cacheKey = `cache:${key}`;
  const lockKey = `lock:${key}`;
 
  // 先查缓存
  const cached = await redis.get(cacheKey);
  if (cached !== null) {
    return JSON.parse(cached) as T;
  }
 
  // 尝试获取锁（NX = 仅当不存在时，EX = 自动过期）
  const acquired = await redis.set(lockKey, "1", "EX", 10, "NX");
 
  if (acquired) {
    try {
      // 我们拿到锁了——获取并缓存
      const result = await fetcher();
      await redis.set(cacheKey, JSON.stringify(result), "EX", ttlWithJitter(ttl));
      return result;
    } finally {
      // 释放锁
      await redis.del(lockKey);
    }
  }
 
  // 另一个请求持有锁——等待后重试
  await sleep(100);
 
  const retried = await redis.get(cacheKey);
  if (retried !== null) {
    return JSON.parse(retried) as T;
  }
 
  // 仍然没有缓存——直接查数据库
  // （处理锁持有者失败的情况）
  return fetcher();
}
 
function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

import { randomUUID } from "crypto";
 
async function acquireLock(lockKey: string, ttl: number): Promise<string | null> {
  const token = randomUUID();
  const acquired = await redis.set(lockKey, token, "EX", ttl, "NX");
  return acquired ? token : null;
}
 
async function releaseLock(lockKey: string, token: string): Promise<boolean> {
  // Lua 脚本确保原子性的检查并删除
  const script = `
    if redis.call("get", KEYS[1]) == ARGV[1] then
      return redis.call("del", KEYS[1])
    else
      return 0
    end
  `;
  const result = await redis.eval(script, 1, lockKey, token);
  return result === 1;
}

interface CachedValue<T> {
  data: T;
  cachedAt: number;
  ttl: number;
}
 
async function cacheWithEarlyExpiration<T>(key: string, fetcher: () => Promise<T>, ttl: number = 3600): Promise<T> {
  const cacheKey = `cache:${key}`;
  const cached = await redis.get(cacheKey);
 
  if (cached !== null) {
    const entry = JSON.parse(cached) as CachedValue<T>;
    const age = (Date.now() - entry.cachedAt) / 1000;
    const remaining = entry.ttl - age;
 
    // XFetch 算法：随着过期时间临近，概率性地重新生成
    // beta * Math.log(Math.random()) 产生一个负数
    // 随着过期临近变得更大（更负）
    const beta = 1; // 调优参数，1 效果不错
    const shouldRegenerate = remaining - beta * Math.log(Math.random()) * -1 <= 0;
 
    if (!shouldRegenerate) {
      return entry.data;
    }
 
    // 继续执行重新生成
    console.log(`[Cache] Early regeneration triggered for ${key}`);
  }
 
  const data = await fetcher();
  const entry: CachedValue<T> = {
    data,
    cachedAt: Date.now(),
    ttl,
  };
 
  // 设置额外的缓冲时间，这样 Redis 不会在我们重新生成之前就过期
  await redis.set(cacheKey, JSON.stringify(entry), "EX", Math.round(ttl * 1.1));
 
  return data;
}

async function staleWhileRevalidate<T>(
  key: string,
  fetcher: () => Promise<T>,
  options: {
    freshTtl: number; // 数据"新鲜"的时长
    staleTtl: number; // 过期数据可以被提供多久
  },
): Promise<T | null> {
  const cacheKey = `cache:${key}`;
  const metaKey = `meta:${key}`;
 
  const [cached, meta] = await redis.mget(cacheKey, metaKey);
 
  if (cached !== null) {
    const parsedMeta = meta ? JSON.parse(meta) : null;
    const isFresh = parsedMeta && Date.now() - parsedMeta.cachedAt < options.freshTtl * 1000;
 
    if (!isFresh) {
      // 数据过期了——提供它但触发后台刷新
      revalidateInBackground(key, cacheKey, metaKey, fetcher, options);
    }
 
    return JSON.parse(cached) as T;
  }
 
  // 完全的缓存未命中——必须同步获取
  return fetchAndCache(key, cacheKey, metaKey, fetcher, options);
}
 
async function fetchAndCache<T>(
  key: string,
  cacheKey: string,
  metaKey: string,
  fetcher: () => Promise<T>,
  options: { freshTtl: number; staleTtl: number },
): Promise<T> {
  const data = await fetcher();
  const totalTtl = options.freshTtl + options.staleTtl;
 
  const pipeline = redis.pipeline();
  pipeline.set(cacheKey, JSON.stringify(data), "EX", totalTtl);
  pipeline.set(metaKey, JSON.stringify({ cachedAt: Date.now() }), "EX", totalTtl);
  await pipeline.exec();
 
  return data;
}
 
function revalidateInBackground<T>(
  key: string,
  cacheKey: string,
  metaKey: string,
  fetcher: () => Promise<T>,
  options: { freshTtl: number; staleTtl: number },
): void {
  // 使用锁来防止多个后台刷新
  const lockKey = `revalidate_lock:${key}`;
 
  redis
    .set(lockKey, "1", "EX", 30, "NX")
    .then((acquired) => {
      if (!acquired) return;
 
      return fetchAndCache(key, cacheKey, metaKey, fetcher, options).finally(() => redis.del(lockKey));
    })
    .catch((err) => {
      console.error(`[SWR] Background revalidation failed for ${key}:`, err);
    });
}

const user = await staleWhileRevalidate<User>("user:123", fetchUserFromDB, {
  freshTtl: 300, // 5 分钟内新鲜
  staleTtl: 3600, // 在重新验证的同时最多提供 1 小时的过期数据
});

async function updateUserAndInvalidate(userId: string, updates: Partial<User>): Promise<User> {
  const user = await db.query("UPDATE users SET name = $2 WHERE id = $1 RETURNING *", [userId, updates.name]);
 
  // 使缓存失效
  await redis.del(`cache:user:${userId}`);
 
  return user[0];
}

async function setWithTags<T>(key: string, value: T, ttl: number, tags: string[]): Promise<void> {
  const pipeline = redis.pipeline();
 
  // 存储值
  pipeline.set(`cache:${key}`, JSON.stringify(value), "EX", ttl);
 
  // 将键添加到每个标签的集合中
  for (const tag of tags) {
    pipeline.sadd(`tag:${tag}`, `cache:${key}`);
    pipeline.expire(`tag:${tag}`, ttl + 3600); // 标签集合比值存活更久
  }
 
  await pipeline.exec();
}
 
async function invalidateByTag(tag: string): Promise<number> {
  const keys = await redis.smembers(`tag:${tag}`);
 
  if (keys.length === 0) return 0;
 
  const pipeline = redis.pipeline();
  for (const key of keys) {
    pipeline.del(key);
  }
  pipeline.del(`tag:${tag}`);
 
  await pipeline.exec();
  return keys.length;
}

// 缓存团队数据时，用所有成员 ID 标记
const team = await fetchTeam(teamId);
await setWithTags(`team:${teamId}`, team, 1800, [
  `entity:team:${teamId}`,
  ...team.members.map((m) => `entity:user:${m.id}`),
]);
 
// 当用户 42 更新了资料，使包含他的所有缓存失效
await invalidateByTag("entity:user:42");

// 发布者（在你的 API 服务中）
async function publishInvalidation(entityType: string, entityId: string): Promise<void> {
  await redis.publish("cache:invalidate", JSON.stringify({ entityType, entityId, timestamp: Date.now() }));
}
 
// 订阅者（在每个应用实例中）
const subscriber = new Redis(/* 相同配置 */);
 
subscriber.subscribe("cache:invalidate", (err) => {
  if (err) console.error("[PubSub] Subscribe error:", err);
});
 
subscriber.on("message", async (_channel, message) => {
  const { entityType, entityId } = JSON.parse(message);
  await invalidateByTag(`entity:${entityType}:${entityId}`);
  console.log(`[Cache] Invalidated ${entityType}:${entityId}`);
});

async function invalidateByPattern(pattern: string): Promise<number> {
  let cursor = "0";
  let deletedCount = 0;
 
  do {
    const [nextCursor, keys] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
    cursor = nextCursor;
 
    if (keys.length > 0) {
      await redis.del(...keys);
      deletedCount += keys.length;
    }
  } while (cursor !== "0");
 
  return deletedCount;
}
 
// 使某个特定团队的所有缓存数据失效
await invalidateByPattern("cache:team:42:*");

// 把用户存为 hash
async function setUserHash(user: User): Promise<void> {
  const key = `user:${user.id}`;
  await redis.hset(key, {
    name: user.name,
    email: user.email,
    plan: user.plan,
    updatedAt: Date.now().toString(),
  });
  await redis.expire(key, 1800);
}
 
// 读取特定字段
async function getUserPlan(userId: string): Promise<string | null> {
  return redis.hget(`user:${userId}`, "plan");
}
 
// 更新单个字段
async function upgradeUserPlan(userId: string, plan: string): Promise<void> {
  await redis.hset(`user:${userId}`, "plan", plan);
}
 
// 读取整个 hash 为对象
async function getUserHash(userId: string): Promise<User | null> {
  const data = await redis.hgetall(`user:${userId}`);
  if (!data || Object.keys(data).length === 0) return null;
 
  return {
    id: userId,
    name: data.name,
    email: data.email,
    plan: data.plan as User["plan"],
  };
}

// 排行榜
async function addScore(leaderboard: string, userId: string, score: number): Promise<void> {
  await redis.zadd(leaderboard, score, userId);
}
 
async function getTopPlayers(
  leaderboard: string,
  count: number = 10,
): Promise<Array<{ userId: string; score: number }>> {
  const results = await redis.zrevrange(leaderboard, 0, count - 1, "WITHSCORES");
 
  const players: Array<{ userId: string; score: number }> = [];
  for (let i = 0; i < results.length; i += 2) {
    players.push({
      userId: results[i],
      score: parseFloat(results[i + 1]),
    });
  }
  return players;
}
 
async function getUserRank(leaderboard: string, userId: string): Promise<number | null> {
  const rank = await redis.zrevrank(leaderboard, userId);
  return rank !== null ? rank + 1 : null; // 从 0 索引变为 1 索引
}

async function slidingWindowRateLimit(
  identifier: string,
  windowMs: number,
  maxRequests: number,
): Promise<{ allowed: boolean; remaining: number }> {
  const key = `ratelimit:${identifier}`;
  const now = Date.now();
  const windowStart = now - windowMs;
 
  const pipeline = redis.pipeline();
 
  // 移除窗口外的条目
  pipeline.zremrangebyscore(key, 0, windowStart);
 
  // 添加当前请求
  pipeline.zadd(key, now, `${now}:${Math.random()}`);
 
  // 统计窗口内的请求数
  pipeline.zcard(key);
 
  // 设置整个键的过期
  pipeline.expire(key, Math.ceil(windowMs / 1000));
 
  const results = await pipeline.exec();
  const count = results?.[2]?.[1] as number;
 
  return {
    allowed: count <= maxRequests,
    remaining: Math.max(0, maxRequests - count),
  };
}

interface Job {
  id: string;
  type: string;
  payload: Record<string, unknown>;
  createdAt: number;
}
 
// 生产者
async function enqueueJob(queue: string, type: string, payload: Record<string, unknown>): Promise<string> {
  const job: Job = {
    id: randomUUID(),
    type,
    payload,
    createdAt: Date.now(),
  };
 
  await redis.lpush(`queue:${queue}`, JSON.stringify(job));
  return job.id;
}
 
// 消费者（阻塞直到有任务可用）
async function dequeueJob(queue: string, timeout: number = 5): Promise<Job | null> {
  const result = await redis.brpop(`queue:${queue}`, timeout);
  if (!result) return null;
 
  return JSON.parse(result[1]) as Job;
}

// 跟踪每日独立访客
async function trackVisitor(page: string, visitorId: string): Promise<boolean> {
  const key = `visitors:${page}:${new Date().toISOString().split("T")[0]}`;
  const isNew = await redis.sadd(key, visitorId);
 
  // 48 小时后自动过期
  await redis.expire(key, 172800);
 
  return isNew === 1; // 1 = 新成员，0 = 已存在
}
 
// 获取独立访客数
async function getUniqueVisitors(page: string, date: string): Promise<number> {
  return redis.scard(`visitors:${page}:${date}`);
}
 
// 检查用户是否已经执行过某操作
async function hasUserVoted(pollId: string, userId: string): Promise<boolean> {
  return (await redis.sismember(`votes:${pollId}`, userId)) === 1;
}

// HyperLogLog 用于近似唯一计数
async function trackVisitorApprox(page: string, visitorId: string): Promise<void> {
  const key = `hll:visitors:${page}:${new Date().toISOString().split("T")[0]}`;
  await redis.pfadd(key, visitorId);
  await redis.expire(key, 172800);
}
 
async function getApproxUniqueVisitors(page: string, date: string): Promise<number> {
  return redis.pfcount(`hll:visitors:${page}:${date}`);
}

const user = {
  id: "usr_abc123",
  name: "Ahmet Kousa",
  email: "ahmet@example.com",
  plan: "pro",
  preferences: {
    theme: "dark",
    language: "tr",
    notifications: true,
  },
};
 
// JSON：189 字节
const jsonStr = JSON.stringify(user);
console.log(Buffer.byteLength(jsonStr)); // 189
 
// 热路径上的 JSON.parse：每次约 0.02 毫秒
// 每秒 10000 个请求：每秒 200 毫秒的总 CPU 时间

npm install msgpackr

import { pack, unpack } from "msgpackr";
 
// MessagePack：约 140 字节（小 25%）
const packed = pack(user);
console.log(packed.length); // ~140
 
// 存为 Buffer
await redis.set("user:123", packed);
 
// 读为 Buffer
const raw = await redis.getBuffer("user:123");
if (raw) {
  const data = unpack(raw);
}

import { promisify } from "util";
import { gzip, gunzip } from "zlib";
 
const gzipAsync = promisify(gzip);
const gunzipAsync = promisify(gunzip);
 
async function setCompressed<T>(key: string, value: T, ttl: number): Promise<void> {
  const json = JSON.stringify(value);
 
  // 仅在大于 1KB 时压缩（小值的压缩开销不值得）
  if (Buffer.byteLength(json) > 1024) {
    const compressed = await gzipAsync(json);
    await redis.set(key, compressed, "EX", ttl);
  } else {
    await redis.set(key, json, "EX", ttl);
  }
}
 
async function getCompressed<T>(key: string): Promise<T | null> {
  const raw = await redis.getBuffer(key);
  if (!raw) return null;
 
  try {
    // 先尝试解压
    const decompressed = await gunzipAsync(raw);
    return JSON.parse(decompressed.toString()) as T;
  } catch {
    // 没有压缩，作为普通 JSON 解析
    return JSON.parse(raw.toString()) as T;
  }
}

// app/api/products/route.ts
import { NextResponse } from "next/server";
import redis from "@/lib/redis";
 
export async function GET(request: Request) {
  const url = new URL(request.url);
  const category = url.searchParams.get("category") || "all";
  const cacheKey = `api:products:${category}`;
 
  // 检查缓存
  const cached = await redis.get(cacheKey);
  if (cached) {
    return NextResponse.json(JSON.parse(cached), {
      headers: {
        "X-Cache": "HIT",
        "Cache-Control": "public, s-maxage=60",
      },
    });
  }
 
  // 从数据库获取
  const products = await db.products.findMany({
    where: category !== "all" ? { category } : undefined,
    orderBy: { createdAt: "desc" },
    take: 50,
  });
 
  // 缓存 5 分钟并带抖动
  await redis.set(cacheKey, JSON.stringify(products), "EX", ttlWithJitter(300));
 
  return NextResponse.json(products, {
    headers: {
      "X-Cache": "MISS",
      "Cache-Control": "public, s-maxage=60",
    },
  });
}

// lib/session.ts
import { randomUUID } from "crypto";
import redis from "./redis";
 
interface Session {
  userId: string;
  role: string;
  createdAt: number;
  data: Record<string, unknown>;
}
 
const SESSION_TTL = 86400; // 24 小时
const SESSION_PREFIX = "session:";
 
export async function createSession(userId: string, role: string): Promise<string> {
  const sessionId = randomUUID();
  const session: Session = {
    userId,
    role,
    createdAt: Date.now(),
    data: {},
  };
 
  await redis.set(`${SESSION_PREFIX}${sessionId}`, JSON.stringify(session), "EX", SESSION_TTL);
 
  return sessionId;
}
 
export async function getSession(sessionId: string): Promise<Session | null> {
  const key = `${SESSION_PREFIX}${sessionId}`;
 
  // 使用 GETEX 在每次访问时刷新 TTL（滑动过期）
  const raw = await redis.getex(key, "EX", SESSION_TTL);
  if (!raw) return null;
 
  return JSON.parse(raw) as Session;
}
 
export async function destroySession(sessionId: string): Promise<void> {
  await redis.del(`${SESSION_PREFIX}${sessionId}`);
}
 
// 销毁用户的所有会话（适用于"全部退出"）
export async function destroyAllUserSessions(userId: string): Promise<void> {
  // 这需要维护一个 user->sessions 索引
  const sessionIds = await redis.smembers(`user_sessions:${userId}`);
 
  if (sessionIds.length > 0) {
    const pipeline = redis.pipeline();
    for (const sid of sessionIds) {
      pipeline.del(`${SESSION_PREFIX}${sid}`);
    }
    pipeline.del(`user_sessions:${userId}`);
    await pipeline.exec();
  }
}

// middleware.ts（或中间件使用的辅助函数）
import redis from "@/lib/redis";
 
interface RateLimitResult {
  allowed: boolean;
  remaining: number;
  resetAt: number;
}
 
export async function rateLimit(
  identifier: string,
  limit: number = 60,
  windowSeconds: number = 60,
): Promise<RateLimitResult> {
  const key = `rate:${identifier}`;
  const now = Math.floor(Date.now() / 1000);
  const windowStart = now - windowSeconds;
 
  // 原子性限流的 Lua 脚本
  const script = `
    redis.call('ZREMRANGEBYSCORE', KEYS[1], 0, ARGV[1])
    redis.call('ZADD', KEYS[1], ARGV[2], ARGV[3])
    local count = redis.call('ZCARD', KEYS[1])
    redis.call('EXPIRE', KEYS[1], ARGV[4])
    return count
  `;
 
  const count = (await redis.eval(
    script,
    1,
    key,
    windowStart,
    now,
    `${now}:${Math.random()}`,
    windowSeconds,
  )) as number;
 
  return {
    allowed: count <= limit,
    remaining: Math.max(0, limit - count),
    resetAt: now + windowSeconds,
  };
}

// lib/distributed-lock.ts
import { randomUUID } from "crypto";
import redis from "./redis";
 
export async function withLock<T>(
  lockName: string,
  fn: () => Promise<T>,
  options: { ttl?: number; retryDelay?: number; maxRetries?: number } = {},
): Promise<T | null> {
  const { ttl = 30, retryDelay = 200, maxRetries = 10 } = options;
  const token = randomUUID();
  const lockKey = `dlock:${lockName}`;
 
  // 尝试获取锁
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const acquired = await redis.set(lockKey, token, "EX", ttl, "NX");
 
    if (acquired) {
      try {
        // 为长时间运行的任务自动延长锁
        const extender = setInterval(
          async () => {
            const script = `
            if redis.call("get", KEYS[1]) == ARGV[1] then
              return redis.call("expire", KEYS[1], ARGV[2])
            else
              return 0
            end
          `;
            await redis.eval(script, 1, lockKey, token, ttl);
          },
          (ttl * 1000) / 3,
        );
 
        const result = await fn();
        clearInterval(extender);
        return result;
      } finally {
        // 仅在我们仍持有锁时释放
        const releaseScript = `
          if redis.call("get", KEYS[1]) == ARGV[1] then
            return redis.call("del", KEYS[1])
          else
            return 0
          end
        `;
        await redis.eval(releaseScript, 1, lockKey, token);
      }
    }
 
    // 等待后重试
    await new Promise((r) => setTimeout(r, retryDelay));
  }
 
  // 所有重试后仍无法获取锁
  return null;
}

// 在 cron 触发的 API 路由中
export async function POST() {
  const result = await withLock("daily-report", async () => {
    // 只有一个实例运行这个
    const report = await generateDailyReport();
    await sendReportEmail(report);
    return report;
  });
 
  if (result === null) {
    return NextResponse.json({ message: "Another instance is already processing" }, { status: 409 });
  }
 
  return NextResponse.json({ success: true });
}

// lib/cache-metrics.ts
import redis from "./redis";
 
const METRICS_KEY = "metrics:cache";
 
export async function recordCacheHit(): Promise<void> {
  await redis.hincrby(METRICS_KEY, "hits", 1);
}
 
export async function recordCacheMiss(): Promise<void> {
  await redis.hincrby(METRICS_KEY, "misses", 1);
}
 
export async function getCacheStats(): Promise<{
  hits: number;
  misses: number;
  hitRate: number;
}> {
  const stats = await redis.hgetall(METRICS_KEY);
  const hits = parseInt(stats.hits || "0", 10);
  const misses = parseInt(stats.misses || "0", 10);
  const total = hits + misses;
 
  return {
    hits,
    misses,
    hitRate: total > 0 ? hits / total : 0,
  };
}
 
// 每天重置指标
export async function resetCacheStats(): Promise<void> {
  await redis.del(METRICS_KEY);
}

redis-cli INFO memory

redis-cli INFO stats

# 永远不要在生产环境中让它持续运行
# 它会增加显著的开销并可能记录敏感数据
redis-cli MONITOR

# 为过期和淘汰事件启用键空间通知
redis-cli CONFIG SET notify-keyspace-events Ex

const subscriber = new Redis(/* 配置 */);
 
// 监听键过期事件
subscriber.subscribe("__keyevent@0__:expired", (err) => {
  if (err) console.error("Subscribe error:", err);
});
 
subscriber.on("message", (_channel, expiredKey) => {
  console.log(`Key expired: ${expiredKey}`);
 
  // 主动重新生成重要的键
  if (expiredKey.startsWith("cache:homepage")) {
    regenerateHomepageCache().catch(console.error);
  }
});

# 采样 10 个最大的键
redis-cli --bigkeys

# 特定键的内存使用（字节）
redis-cli MEMORY USAGE "cache:search:electronics"

// 编程式内存分析
async function analyzeMemory(pattern: string): Promise<void> {
  let cursor = "0";
  const stats: Array<{ key: string; bytes: number }> = [];
 
  do {
    const [nextCursor, keys] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
    cursor = nextCursor;
 
    for (const key of keys) {
      const bytes = await redis.memory("USAGE", key);
      if (bytes) {
        stats.push({ key, bytes: bytes as number });
      }
    }
  } while (cursor !== "0");
 
  // 按大小降序排列
  stats.sort((a, b) => b.bytes - a.bytes);
 
  console.log("Top 20 keys by memory usage:");
  for (const { key, bytes } of stats.slice(0, 20)) {
    const mb = (bytes / 1024 / 1024).toFixed(2);
    console.log(`  ${key}: ${mb} MB`);
  }
}

# 在 redis.conf 中或通过 CONFIG SET
maxmemory 512mb
maxmemory-policy allkeys-lru

// lib/cache.ts
import Redis from "ioredis";
 
const redis = new Redis({
  host: process.env.REDIS_HOST || "127.0.0.1",
  port: Number(process.env.REDIS_PORT) || 6379,
  password: process.env.REDIS_PASSWORD || undefined,
  maxRetriesPerRequest: 3,
  retryStrategy(times) {
    return Math.min(times * 200, 5000);
  },
});
 
// TTL 分级
const TTL = {
  STATIC: 86400,
  MODERATE: 1800,
  VOLATILE: 300,
  EPHEMERAL: 60,
  NOT_FOUND: 120,
} as const;
 
type TTLTier = keyof typeof TTL;
 
function ttlWithJitter(base: number, jitter = 0.1): number {
  const offset = base * jitter * (Math.random() * 2 - 1);
  return Math.max(1, Math.round(base + offset));
}
 
// 核心的 cache-aside 配合雪崩保护
async function get<T>(
  key: string,
  fetcher: () => Promise<T>,
  options: {
    tier?: TTLTier;
    ttl?: number;
    tags?: string[];
    swr?: { freshTtl: number; staleTtl: number };
  } = {},
): Promise<T> {
  const { tier = "MODERATE", tags } = options;
  const baseTtl = options.ttl ?? TTL[tier];
  const cacheKey = `c:${key}`;
 
  // 检查缓存
  const cached = await redis.get(cacheKey);
 
  if (cached !== null) {
    try {
      const parsed = JSON.parse(cached);
      recordHit();
      return parsed as T;
    } catch {
      await redis.del(cacheKey);
    }
  }
 
  recordMiss();
 
  // 获取锁防止雪崩
  const lockKey = `lock:${key}`;
  const acquired = await redis.set(lockKey, "1", "EX", 10, "NX");
 
  if (!acquired) {
    // 另一个进程正在获取——短暂等待后重试缓存
    await new Promise((r) => setTimeout(r, 150));
    const retried = await redis.get(cacheKey);
    if (retried) return JSON.parse(retried) as T;
  }
 
  try {
    const result = await fetcher();
    const ttl = ttlWithJitter(baseTtl);
 
    const pipeline = redis.pipeline();
    pipeline.set(cacheKey, JSON.stringify(result), "EX", ttl);
 
    // 存储标签关联
    if (tags) {
      for (const tag of tags) {
        pipeline.sadd(`tag:${tag}`, cacheKey);
        pipeline.expire(`tag:${tag}`, ttl + 3600);
      }
    }
 
    await pipeline.exec();
    return result;
  } finally {
    await redis.del(lockKey);
  }
}
 
// 失效
async function invalidate(...keys: string[]): Promise<void> {
  if (keys.length === 0) return;
  await redis.del(...keys.map((k) => `c:${k}`));
}
 
async function invalidateByTag(tag: string): Promise<number> {
  const keys = await redis.smembers(`tag:${tag}`);
  if (keys.length === 0) return 0;
 
  const pipeline = redis.pipeline();
  for (const key of keys) {
    pipeline.del(key);
  }
  pipeline.del(`tag:${tag}`);
  await pipeline.exec();
  return keys.length;
}
 
// 指标
function recordHit(): void {
  redis.hincrby("metrics:cache", "hits", 1).catch(() => {});
}
 
function recordMiss(): void {
  redis.hincrby("metrics:cache", "misses", 1).catch(() => {});
}
 
async function stats(): Promise<{
  hits: number;
  misses: number;
  hitRate: string;
}> {
  const raw = await redis.hgetall("metrics:cache");
  const hits = parseInt(raw.hits || "0", 10);
  const misses = parseInt(raw.misses || "0", 10);
  const total = hits + misses;
 
  return {
    hits,
    misses,
    hitRate: total > 0 ? ((hits / total) * 100).toFixed(1) + "%" : "N/A",
  };
}
 
export const cache = {
  get,
  invalidate,
  invalidateByTag,
  stats,
  redis,
  TTL,
};

import { cache } from "@/lib/cache";
 
// 简单的 cache-aside
const products = await cache.get("products:featured", fetchFeaturedProducts, {
  tier: "VOLATILE",
  tags: ["entity:products"],
});
 
// 自定义 TTL
const config = await cache.get("app:config", fetchAppConfig, {
  ttl: 43200, // 12 小时
});
 
// 更新商品后
await cache.invalidateByTag("entity:products");
 
// 检查健康
const metrics = await cache.stats();
console.log(`Cache hit rate: ${metrics.hitRate}`);

async function resilientGet<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
  try {
    return await cache.get(key, fetcher);
  } catch (err) {
    console.error(`[Cache] Degraded mode for ${key}:`, err);
    return fetcher(); // 完全绕过缓存
  }
}