mcpField
R
redis-caching

redis-caching

github.com/shipshitdev开发3864 次安装2 天前更新
代码仓库

关于 redis-caching

redis-caching 是一项开发技能，指导将 Redis 用作生产环境的辅助层，而非第二个数据库。内容涵盖缓存模式、限流、会话、失效和事件传递，并针对 Node.js、NestJS、无服务器及边缘运行时提供建议。

主要功能

  1. 01Cache-aside 与 write-through 模式
  2. 02TTL 与键失效设计
  3. 03热点键防缓存击穿
  4. 04滑动窗口限流
  5. 05会话存储与事件传递

适用场景

  1. 01为 Prisma 读取添加 Redis 缓存
  2. 02通过限流保护高开销路由
  3. 03存储短期会话或验证状态
  4. 04为事件选择发布订阅或 Streams

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shipshitdev/skills --skill redis-caching

安装后在 Claude Code 中输入/redis-caching确认已加载。

附带文件plugin.jsonreferences/examples.md

详细介绍

Redis 缓存

将 Redis 用作生产环境的辅助层，而不是第二个数据库。

适用场景

  • 在 Prisma 或 API 读取操作周围添加缓存旁路或直写缓存。
  • 通过速率限制保护开销较大的路由。
  • 存储短期会话、验证状态、锁或计数器。
  • 添加发布/订阅或基于流的事件扇出。
  • 审查 Redis 键设计、TTL、失效机制或连接处理。

对于 BullMQ 队列架构，请使用 nestjs-queue-architect，不要在此重复实现队列模式。

首要决策

  1. 选择运行时。
    • 长生命周期的 Node.js 或 NestJS 进程：使用 ioredis。
    • 无服务器或边缘运行时：优先使用 Upstash Redis SDK 或 REST API。
    • 后台作业：使用 nestjs-queue-architect 中的 BullMQ 指南。
  2. 编写代码前，先定义缓存契约。
    • 数据源：Prisma/数据库、上游 API、计算结果或会话权威源。
    • 新鲜度：固定 TTL、过期后后台刷新、显式失效或直写。
    • 失败模式：缓存读取失败时默认放行；认证/会话/速率限制写入失败时默认拒绝。
  3. 同时设计键和失效机制。
    • 为每个键添加命名空间：app:env:entity:id:variant。
    • 保持键稳定且便于检查。
    • 为每个缓存、锁、会话和速率限制键设置 TTL。

安装

bun add ioredis

# Optional serverless Redis
bun add @upstash/redis @upstash/ratelimit

每个进程使用一个 Redis 客户端（模块级单例，并防止热重载导致重复创建）。不要为每个请求都创建新的 TCP 客户端。将 error、connect 和 reconnecting 事件接入应用日志记录器或 APM。避免记录连接 URL 中的凭据。

完整设置请参见 references/examples.md（§ Redis Client Singleton）。

使用 Prisma 实现缓存旁路

对于允许短暂数据过期的读取操作，使用缓存旁路：检查缓存，未命中时调用加载器，并使用带随机抖动的 TTL（baseTtl + random(0, jitter)）写回，避免热点键同时过期。

getCached 辅助函数和基于 Prisma 的用法示例请参见 references/examples.md（§ Cache-Aside With Prisma）。

防止缓存击穿

使用短时 SET key val EX 10 NX 锁保护热点键。只有持有锁的一方（通过随机令牌匹配）才能释放锁；未获取锁的请求短暂等待并重新检查缓存，然后再直接加载。

完整的加锁与释放实现请参见 references/examples.md（§ Stampede Protection）。

失效机制

对于已知键，优先直接失效。如果一次变更会影响多个键，则使用标签集合（每个标签对应一个 Redis 集合，其中映射了该标签下写入的键）——通过管道写入；失效时读取标签对应的键集合并对这些键执行 UNLINK。紧急清理模式匹配时使用 SCAN，不要使用 KEYS。不要在高频请求路径上执行模式匹配失效。

cacheSetWithTags / invalidateTag 的实现请参见 references/examples.md（§ Tag-Based Invalidation）。

速率限制

对精度有要求时，使用有序集合实现滑动窗口限制：清除过期条目、添加当前请求、统计成员数量并设置键的过期时间，所有操作都放在一个 MULTI 中。对于公开流量，设置响应头：X-RateLimit-Limit、X-RateLimit-Remaining 和 Retry-After。

完整的 slidingWindowRateLimit 实现请参见 references/examples.md（§ Sliding-Window Rate Limiting）。

会话和验证状态

  • 存储不透明的会话 ID 或令牌哈希，不要存储原始 JWT 或长期有效的密钥。
  • 为每个会话键设置 TTL。
  • 权限变更后重新生成会话。
  • 在注销、删除账户和重置密码时删除会话。
  • 对登录、注销、MFA 和重置密码流程，将 Redis 写入失败视为认证失败。

createSession 示例请参见 references/examples.md（§ Session Storage）。

发布/订阅与流

  • 对于可以接受消息丢失的临时扇出，使用发布/订阅。
  • 当消费者需要重放、背压或持久化传递时，使用流。
  • 保持负载较小；将大型对象存储在其他位置，并发布其 ID。
  • 添加消费者可观测性：延迟、死信、重试和处理器错误。

生产环境检查清单

  • 所有缓存、锁、会话和速率限制键都设置了 TTL。
  • 缓存读取在可能的情况下采用失败开放；身份验证和速率限制写入采用失败关闭。
  • 热点键使用 TTL 抖动或缓存击穿防护。
  • 没有请求路径使用 KEYS、无界 SMEMBERS 或大型 HGETALL。
  • 与写入路径一并测试失效机制。
  • Redis 指标涵盖延迟、命中率、内存、驱逐、被阻塞的客户端和重新连接。
  • 本地测试涵盖缓存命中、缓存未命中、Redis 不可用、失效和超出速率限制。

评论

支持 Markdown