@lark-apaas/coding-steering 0.1.33-beta.0 → 0.1.34

package/steering/nestjs-react-fullstack/skills/nestjs-cache/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: nestjs-cache
+description: Use when planning, adding, debugging, or reviewing NestJS cache logic, especially for performance optimization, repeated data access, external API or database load reduction, multi-instance FaaS cache architecture, or shared versus in-memory cache choices. 触发词：缓存方案, 缓存设计, 性能优化, 重复数据访问, 多实例缓存, FaaS 缓存, 共享缓存, 内存缓存, cache architecture, cache, caching, cache-manager, CacheInterceptor, CACHE_MANAGER, cache.wrap, CacheKey, CacheTTL, TTL, 缓存穿透, 缓存击穿, cache miss, cache stampede, single-flight, 热点缓存
+steering: true
+steering-topic: nestjs_cache
+match-template-name: nestjs-react-fullstack
+control-by-feature-ab: true
+---
+
+# NestJS Caching 使用指南
+
+在 NestJS 后端为读多写少路径加缓存。平台已注入 `CACHE_MANAGER`，业务只需要：**判断该不该缓存 → 选一种使用姿势 → 遵守 Key 命名和 TTL 规范**。
+
+## 前置约束：不要自己装配 `CacheModule`
+
+平台已经在根级注册好全局 `CacheModule` 并暴露 `CACHE_MANAGER` provider，业务模块**直接 `@Inject(CACHE_MANAGER)` 即可**。
+
+**不要**在业务 `Module` 里再 `imports: [CacheModule.register()]` 或 `CacheModule.registerAsync(...)`：
+
+```typescript
+// BAD — 会创建新的独立 store，不共享连接池 / token / fail-open 保护
+@Module({
+  imports: [CacheModule.register()],   // ← 删掉；直接 @Inject(CACHE_MANAGER) 即可（见下方姿势 A）
+  controllers: [BookController],
+  providers: [BookService],
+})
+export class BookModule {}
+```
+
+自己 `register()` 出的 store 是内存 store 且脱离平台管理链路，**不走 Redis、不受 fail-open 保护、不上报可观测**——症状是"本地看着 hit 都对，上线后集群不共享 / 重启就丢"。
+
+## 禁止使用内存缓存（CRITICAL）
+
+应用采用多 FaaS 实例部署，进程内缓存只对当前实例生效，无法被其他实例共享。因此，**禁止**使用 `new Map()`、模块级变量、全局单例或自行注册的内存 store 实现缓存；统一使用平台注入的 `CACHE_MANAGER`。
+
+## 依赖版本（CRITICAL）
+
+**必须使用 `cache-manager` v6**，禁止安装或按照 v4 / v5 / v7 的 API 语义编写缓存代码。
+
+## 什么时候该加缓存（先决策再动手）
+
+```
+决策树：加缓存吗？
+├─ 是否满足以下任一"值得缓存"信号？
+│    a) 读得频繁（同一份数据反复被查，非一次性接口）
+│    b) 读得慢（源侧要跨服务/跨库/跑聚合，用户能感觉到等待）
+│    c) 读得贵（触发外部收费 API / 高负载 RPC / 大结果集 SQL）
+│  ├─ 都不满足 → 不加。加了维护成本 > 收益
+│  └─ 满足任一 → 下一步
+├─ 是否是**授权敏感路径**？
+│    a) 该 handler / 方法被 `@CanRole` / `@Can` 装饰
+│    b) 返回值由 PostgreSQL RLS（Row Level Security）过滤（登录身份不同结果不同）
+│  ├─ 是 → 不加。授权决策 / RLS 过滤后的结果与身份强绑定，
+│  │       缓存 = 越权（陈旧 policy）或串号（不同用户读同一 key）
+│  └─ 否 → 下一步
+├─ 业务可容忍 TTL 期内数据轻微陈旧（读到几秒前的旧值不影响正确性）？
+│  ├─ 否（要强一致，如库存/余额/权限当次判定）→ 不加
+│  └─ 是 → 下一步
+├─ 数据是"读多写少"（读远多于写，写触发时能明确 invalidate 哪些 key）？
+│  ├─ 否（写路径同样频繁、或 invalidate 范围爆炸）→ 不加，命中率上不去
+│  └─ 是 → 加缓存，选一种姿势（见下方）
+└─ 是否可能出现热点 key（一份数据被大量请求同时命中，如首页配置、公共字典）？
+   └─ 是 → 必须用 `cache.wrap` 拿 single-flight 语义，防击穿
+```
+
+**判断技巧**：拿不准就问自己——"如果同一个用户 1 秒内连点 5 次，我希望后 4 次直接返回上次结果吗？" 是 → 加；否（每次必须重算）→ 不加。
+
+**典型该加**：外部 open API 元数据 / 长尾字典表 / 用户 profile / 频繁读取的配置 / 慢报表聚合结果。
+
+**典型不该加**：金融流水、库存扣减、鉴权决策、事务型写路径、每次都不同参数的即席查询。
+
+## Quick Reference
+
+| 场景 | 用法 |
+|------|------|
+| 读一次+回填 | `await cache.get(key)` → miss 时 fetch → `cache.set(key, val, ttlMs)` |
+| 热点 key 防击穿 | `await cache.wrap(key, () => loader(), ttlMs)` |
+| 幂等 GET 接口一键缓存 | `@UseInterceptors(CacheInterceptor)` + `@CacheKey` + `@CacheTTL` |
+| 写路径失效缓存 | `await cache.del(key)` |
+| TTL 单位 | 毫秒（cache-manager v6 起） |
+
+## 三种使用姿势
+
+### A. 手动 `CACHE_MANAGER`（最常用，最灵活）
+
+```typescript
+import { Inject, Injectable } from '@nestjs/common';
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import type { Cache } from 'cache-manager';
+
+@Injectable()
+export class ProfileService {
+  constructor(@Inject(CACHE_MANAGER) private readonly cache: Cache) {}
+
+  async getProfile(userId: string) {
+    const key = `profile:${userId}`;
+    const hit = await this.cache.get<Profile>(key);
+    if (hit !== null) return hit; // falsy 值（0/''/false）也是有效命中，别用 if (hit)
+
+    const fresh = await this.fetchFromRemote(userId);
+    await this.cache.set(key, fresh, 60_000); // TTL ms
+    return fresh;
+  }
+
+  async updateProfile(userId: string, patch: Partial<Profile>) {
+    const next = await this.saveToRemote(userId, patch);
+    await this.cache.del(`profile:${userId}`); // 写路径主动失效
+    return next;
+  }
+}
+```
+
+### B. `cache.wrap`（防击穿 / single-flight）
+
+热点 key 同时被 N 个请求命中时，只有一个 loader 会真正执行，其他并发请求等它结果。冷启动场景必须用这个而不是 A 方案。
+
+> **限定**：`wrap` 的 single-flight 是**单实例进程内**去重（v6 内嵌 `promise-coalesce`，本质是内存 Map）。多 pod 部署时每个实例的首个请求各自触发一次 loader → 最多 N 个 pod 并发回源 N 次，而非全局 1 次。要做真正的全局防击穿需额外配分布式锁。
+
+```typescript
+async getConfig(appApiName: string) {
+  return this.cache.wrap(
+    `app-config:${appApiName}`,
+    () => this.loadFromDB(appApiName),
+    5 * 60_000, // TTL 5min
+  );
+}
+```
+
+### C. `CacheInterceptor` + 装饰器（Controller 方法级）
+
+只适合**幂等 GET** 且返回值 JSON-safe。写请求、带循环引用 / Buffer / Date 的返回值、需要按登录用户维度分 key 的场景，不要用它——用 A 方案。
+
+**`@CacheKey` 是静态常量**：所有请求都命中同一条缓存，会忽略路由参数 / query。带路由参数（如 `:apiName`）时**不要写 `@CacheKey`**，让 interceptor 按完整 URL 自动分 key；否则 app A 的结果会被返回给 app B（串号）。
+
+```typescript
+import { CacheInterceptor, CacheTTL } from '@nestjs/cache-manager';
+
+@Controller('apps')
+@UseInterceptors(CacheInterceptor)
+export class AppsController {
+  // 不写 @CacheKey：按 GET /apps/:apiName/meta 完整 URL 自动分 key
+  @Get(':apiName/meta')
+  @CacheTTL(60_000) // ms
+  getMeta(@Param('apiName') apiName: string) { /* ... */ }
+}
+```
+
+## Key 命名约定
+
+| 规则 | 例子 | 理由 |
+|------|------|------|
+| 业务前缀必需 | `profile:${userId}` | 避免多应用共用 Redis 时 key 冲突 |
+| 冒号分层 | `app:${apiName}:config:${env}` | 便于排障时 SCAN |
+| 参数拼接稳定 | 多参数按字典序拼接 | 避免 `?a=1&b=2` vs `?b=2&a=1` 命中不同 key |
+| 禁用大对象作 key | 不要 `JSON.stringify(user)` 当 key | key 过长 / 特殊字符转义踩坑 |
+| Key 长度硬上限 | 必须 ≤ 512 字符 | 平台校验，超过直接跳过缓存 |
+
+## 平台校验限制（硬门槛）
+
+平台会在缓存读写时做以下校验。**超过限制不会抛异常，而是本次请求跳过缓存 → 原读取逻辑正常执行 → Trace 记录 error_code**。写代码时按这套边界规划 key / TTL / value：
+
+| 限制项 | 边界 | 超限行为 | error_code |
+|--------|------|----------|------------|
+| 业务 key 为空 | 不能是空串 | 本次不用缓存，直接跑原逻辑 | `CACHE_KEY_INVALID` |
+| 业务 key 长度 | ≤ 512 字符 | 本次不用缓存，直接跑原逻辑 | `CACHE_KEY_TOO_LONG` |
+| TTL 范围 | **30 秒 - 24 小时**（30_000 - 86_400_000 ms） | 本次不用缓存，直接跑原逻辑 | `CACHE_TTL_OUT_OF_RANGE` |
+| 单应用单环境 key 数量 | ≤ 10,000 个有效 key | 已存在的 key 可正常刷新；新 key 不再写入 | `CACHE_KEY_QUOTA_EXCEEDED` |
+| 单 key value 大小 | 序列化后 ≤ 1 MB | 不写入缓存，原读取结果照常返回 | `CACHE_VALUE_TOO_LARGE` |
+
+**写代码前的最小心智模型**：把这 5 条边界当作**写 key / 传 TTL / set value 前的心跳检查**——具体反例见文末 [Common Mistakes](#common-mistakes) 表格。
+
+## Fail-Open 语义（重要）
+
+**缓存不可用不应该让业务请求失败**，平台已保证：
+
+```
+cache.get(key) 场景
+├─ 缓存正常 + hit → 返回值
+├─ 缓存正常 + miss → 返回 null
+├─ 缓存后端不可达 → 返回 null（不抛异常）
+└─ 短暂网络抖动 → 返回 null，业务侧当 miss 处理即可
+```
+
+业务代码永远只需要 `if (hit === null) { fetch fresh }`（**别用 `if (!hit)`**——缓存值为 `0` / `''` / `false` 时会被误判成 miss）。**不要包 try-catch**——反例见 [Common Mistakes](#common-mistakes)。
+
+## Common Mistakes
+
+按主题分组，涵盖 API 姿势、Key、TTL、Value、防御式代码 5 类。
+
+### Key 相关
+
+| 错误 | 正确做法 |
+|------|----------|
+| Key 不加业务前缀 | 必须 `${业务域}:${resource}:${id}` 分层，避免多应用 / 多资源撞车 |
+| 空字符串 / `null` / `undefined` 当 key | 平台校验空 key，本次跳过缓存（`CACHE_KEY_INVALID`）；调用前先判空 |
+| 用户输入直接拼 key（`search:${rawQuery}`） | rawQuery 可能超 512 字符（`CACHE_KEY_TOO_LONG`）；先 hash 或截断 |
+| 把大对象 / JSON / SQL 塞进 key | 长度爆炸 + 特殊字符转义踩坑；用结构化 id 或摘要 |
+| Key 里放 traceId / timestamp / requestId | key 空间爆炸，撞 10,000 上限后新 key 不再写入（`CACHE_KEY_QUOTA_EXCEEDED`） |
+| 多参数拼接顺序不稳定 | 多参数按字典序拼接，避免 `?a=1&b=2` vs `?b=2&a=1` 命中不同 key |
+
+### TTL 相关（v6 单位是**毫秒**）
+
+| 错误 | 正确做法 |
+|------|----------|
+| TTL 传秒（v5 旧思维，`60` = 想要 1 分钟） | v6 起是毫秒，`60_000` 才是 1 分钟；且 `60` = 60ms 会被平台拒（`CACHE_TTL_OUT_OF_RANGE`） |
+| TTL 传 `0` 想表达永久 | v6 `0` = 不过期，但平台也拒；接近永久用 `24 * 3600_000`（24h 上限） |
+| TTL 短于 30s | 平台拒（`CACHE_TTL_OUT_OF_RANGE`），本次不缓存；实际范围 `30_000 - 86_400_000` |
+
+### Value 相关
+
+| 错误 | 正确做法 |
+|------|----------|
+| 缓存 Buffer / Date / 循环引用对象 | 序列化只保证 JSON-safe；复杂对象手动 toDTO |
+| 缓存 `null` 当"存在" | miss 就是 `null`，两者不可区分；表达"值就是空"用哨兵字符串（如 `'__EMPTY__'`）读到再转回 `null` |
+| 单 value 接近或超过 1 MB | 平台拒写（`CACHE_VALUE_TOO_LARGE`）；先投影裁剪或按分页 key 拆开；大 blob 用 CDN / 对象存储 |
+
+### API 姿势相关
+
+| 错误 | 正确做法 |
+|------|----------|
+| 业务模块里再 `CacheModule.register()` / `registerAsync(...)` | 平台已全局注册，直接 `@Inject(CACHE_MANAGER)`；重复注册会创建独立内存 store，不走 Redis、不 fail-open |
+| 用 `CacheInterceptor` 缓存写请求 | Interceptor 只适合幂等 GET；写请求用 A 方案，配 `cache.del(key)` |
+| `@CacheKey` 静态字符串包含用户维度，或带路由参数却写死 key | Interceptor 不感知登录态、静态 key 忽略路由参数/query → 串号；带用户或路由维度改用 A 方案手动拼 key |
+| 高 QPS 热点用 A 方案而非 `wrap` | 击穿风险，冷启动 loader 会被并发触发 N 次；换 B 方案拿 single-flight（注意仍是单实例内去重） |
+| 用 `cache.wrap` 包写路径 | wrap 是"读 + 回填"模型；写路径 `.set()` 后再 `.del()` |
+| `set` 之后立刻 `get` 期望读到 | 平台侧写入 fire-and-forget，**即便 `await set` 也不保证同请求/下一 tick 可见**；写完后直接返回本地变量 |
+
+### 授权 / 身份相关（可能导致越权）
+
+| 错误 | 正确做法 |
+|------|----------|
+| 缓存 `@CanRole` / `@Can` 装饰的 handler 返回值 | 授权决策与登录身份耦合，缓存陈旧 → 该拒的放行 = 越权；直接不加缓存 |
+| 用 `CacheInterceptor` 缓存"读取当前登录用户可见列表"（背后走 PostgreSQL RLS 过滤） | RLS 按 `current_user` / `set_config` 注入的租户/身份过滤，Interceptor 不感知身份 → 用户 A 的结果被用户 B 读到 = 越权串号；这类接口不加缓存，或用 A 方案手动把 `userId` / `tenantId` 拼进 key |
+| 手动缓存 RLS 保护表的查询结果，key 里没带身份维度（如 `list:tasks`） | 同上，多用户共享同一 key → 串号；key 必须至少含 `${tenantId}:${userId}`，且注意 key 空间是否会撞 10,000 上限 |
+
+### 防御式代码
+
+| 错误 | 正确做法 |
+|------|----------|
+| Try-catch 包 `cache.get` / `cache.set` | 平台已 fail-open，`get` 不抛、`set` 失败原逻辑照走；try-catch 会掩盖真实业务错误 |
+| 手动检测缓存后端是否可达再决定 get | 直接调；miss / 后端挂了都返回 `null`，业务侧按 miss 处理 |
+
+## 排障速查
+
+| 症状 | 优先怀疑 | 验证方法 |
+|------|----------|----------|
+| 命中率长期 0 | Key 里含请求 ID / 时间戳，每次都新 key | 打印 key 名，对齐同一业务参数应得同 key |
+| 本地测缓存正常，线上不共享 / 重启就丢 | 业务模块里自己 `CacheModule.register()` 了，跑的是内存 store | 检查 `imports:` 是否含 `CacheModule.*`；删掉，直接 `@Inject(CACHE_MANAGER)` |
+| Interceptor 不生效 | 忘 `@UseInterceptors(CacheInterceptor)` 或 Controller 没注册 | 在 loader 加日志，观察是否每次请求都被调 |
+| TTL "不生效" | 传成秒、传 `0`、或超出 `30s - 24h` 平台范围 | Trace 里出现 `CACHE_TTL_OUT_OF_RANGE` 就是超范围 |
+| 数据陈旧 | 写路径没 `cache.del` 主动失效 | 更新时 log 出 del 的 key，比对读路径的 key |
+| Trace 出现 `CACHE_KEY_TOO_LONG` | key 里塞了整段 SQL / 用户输入 / JSON | 用 hash 或结构化 id 替换 |
+| Trace 出现 `CACHE_VALUE_TOO_LARGE` | 整表 / 大 list 直接缓存 | 分页缓存或投影裁剪，把单个 value 压到 1 MB 以内 |
+| Trace 出现 `CACHE_KEY_QUOTA_EXCEEDED` | key 空间失控（含 traceId / timestamp / 用户输入） | 收敛 key 模板，用有限的枚举维度 |
+| 并发压测下源侧被打爆 | 热点未用 `wrap` | 换 A → B，加 single-flight |