@lark-apaas/coding-steering 0.1.32-beta.0 → 0.1.32-dev.05acdd1

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

@@ -0,0 +1,265 @@
+---
+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
+---
+
+# NestJS Caching 使用指南
+
+本 Skill 用于妙搭 NestJS 后端的缓存评估、接入、优化、审查和排障。先判断数据能否复用、谁可以读取、允许多旧，再确定 Key、TTL、失效方式和实现。平台已注入 `CACHE_MANAGER`，业务直接使用。触发本 Skill 只表示需要评估缓存；收益不足或正确性条件不满足时，说明原因并给出合适的处理方向。
+
+## 前置约束：不要自己装配 `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) 读得贵（外部 HTTP 服务、多维表格等插件、AI 模型调用、高负载 RPC / 大结果集 SQL）
+│  ├─ 都不满足 → 不加。加了维护成本 > 收益
+│  └─ 满足任一 → 下一步
+├─ 返回数据是否受身份或权限影响？
+│  ├─ 否 → 下一步
+│  └─ 是 → 每次请求仍须执行必要鉴权；缓存命中不能跳过方法内的权限检查
+│           身份相关结果必须隔离，权限变化后旧结果不得越权访问
+│           无法满足时 → 不缓存该结果；继续评估可独立复用的公共数据
+├─ 业务可容忍 TTL 期内数据轻微陈旧（读到几秒前的旧值不影响正确性）？
+│  ├─ 否（要强一致，如库存/余额/权限当次判定）→ 不加
+│  └─ 是 → 下一步
+├─ 数据复用收益是否高于缓存维护成本？
+│    结合重复读取量、更新频率、允许的陈旧时间和失效成本判断；读多写少是优先信号
+│  ├─ 否，或无法满足一致性要求 → 不加
+│  └─ 是 → 可加；写入较频繁时，仍需确认失效方式可维护、预期命中率有价值
+└─ 是否存在同一 Key 的并发回源？
+   └─ 是 → 使用 `cache.wrap` 合并单进程内并发；多实例仍可能分别回源，继续评估源侧承载能力
+```
+
+**判断技巧**：先确认相同输入是否会重复读取，再检查身份隔离、允许的陈旧时间和失效方式。连续请求可以返回相同结果，只是复用信号，不能替代这些检查。接口慢时也要检查索引、重复查询等源侧问题。
+
+**优先评估**：外部 API 元数据、公共字典、配置、热点详情、允许陈旧的报表，以及满足身份隔离和权限变化要求的用户资料。一个接口包含多步读取时，分别评估各步骤。
+
+**不使用缓存替代**：库存扣减、余额校验、授权决定等当次权威判断，以及事务型写入。历史记录和统计展示可单独评估；参数不重复、复用收益低的查询通常不加。
+
+## Quick Reference
+
+| 场景 | 用法 |
+|------|------|
+| 单次读缓存、未命中回源 | `get` → 未命中时读取源数据 → `set`；需并发合并时用 `wrap` |
+| 公共配置、字典、热点数据 | 使用平台共享缓存；`wrap` 仅合并单进程内对同一 Key 的并发读取 |
+| 外部 HTTP / 多维表格等插件 / AI 模型调用结果 | 只有 Server 侧调用能用 `CACHE_MANAGER`，调用放在哪一侧按 plugin-guide 决定；Key 用规范化后的完整请求参数（AI 另加实例 id 与模型参数）；只缓存成功的最终结果，超时、错误、流式过程不缓存；缓存响应数据，不缓存凭证；外部数据靠 TTL 发现变化，AI 结果仅在相同输入可复用、且不是「重新生成」流程时缓存 |
+| 可缓存的 GET 返回值 | `CacheInterceptor` + `CacheTTL`；静态 Key 仅用于所有相关请求结果相同的场景 |
+| 用户或租户维度的数据 | 先确认鉴权、身份隔离和权限变化要求，再选择手动缓存或受支持的动态 Key |
+| 列表、筛选、分页、报表 | Key 纳入影响结果的身份与有效查询参数；估算容量并明确失效方式 |
+| 反复读取不存在的资源 | 满足新数据可见性要求时缓存带类型标记的空结果；不缓存暂时故障 |
+| 一个接口包含多步读取 | 分别评估公共数据、用户数据和计算结果，只缓存满足条件的部分 |
+| 写后失效 | 业务数据提交成功后 `del` 相关 Key，并评估并发旧值回填 |
+| TTL 单位 | 毫秒；同时遵循平台允许的范围 |
+
+## 三种使用姿势
+
+### 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，`cache.wrap` 会合并同一进程内重叠的读取：只有一个 loader 执行，其他请求等待结果。热点或冷启动出现并发回源时优先使用。
+
+> **边界**：不同 FaaS 实例各自合并，`wrap` 不保证全局只回源一次。若源侧仍无法承受多实例并发，应根据平台已有能力选择进一步措施；不要假设 `CACHE_MANAGER` 自带分布式锁。
+
+```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，缓存命中不能跳过必要鉴权或方法内的权限检查。默认按 URL 生成 Key，不会自动包含登录身份。身份相关结果须满足前述隔离与权限变化要求，再选择手动缓存或动态 Key。
+
+当前 `@nestjs/cache-manager@3.1.3` 的 `@CacheKey` 支持字符串和 Key 工厂函数。字符串 Key 是固定值，仅适用于相关请求结果相同的场景；动态 Key 应包含影响结果的路由、查询与身份维度。无身份等额外差异时，可不写 `@CacheKey` 并沿用 URL Key。已有项目先确认版本支持；示例中的 URL 方案仍可使用。
+
+```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 |
+| 参数拼接稳定且完整 | 筛选、排序、分页等有效参数按固定字段顺序编码；按需加入可信的身份维度 | 相同条件得到相同 Key，不同结果不能因遗漏参数而共用 Key |
+| 禁用大对象作 key | 不要 `JSON.stringify(user)` 当 key | key 过长 / 特殊字符转义踩坑 |
+| Key 长度硬上限 | 必须 ≤ 512 字符 | 平台校验，超过直接跳过缓存 |
+
+## 平台校验限制（硬门槛）
+
+以下是当前平台规定的 Key、TTL、数量和 Value 边界，业务代码按这些限制设计。缓存失败或拒写时，业务应使用正常回源结果；具体拒绝行为和 Trace 字段以部署版本的 SDK 与服务端契约为准。排障时核对实际错误，不仅凭本表推断原因。
+
+| 限制项 | 边界 | 超限行为 | 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，或截断后作为 Key | 先规范化影响结果的完整参数，再计算摘要；不要用截断代替摘要。摘要只缩短 Key，不减少不同参数组合的数量，仍需评估平台配额 |
+| 把大对象 / JSON / SQL 塞进 key | 长度爆炸 + 特殊字符转义踩坑；用结构化 id 或摘要 |
+| Key 里放 traceId / timestamp / requestId | key 空间爆炸，撞 10,000 上限后新 key 不再写入（`CACHE_KEY_QUOTA_EXCEEDED`） |
+| 多参数拼接顺序不稳定或遗漏有效参数 | 固定字段顺序，包含所有影响结果的参数；规范化不能改变查询含义，例如有顺序语义的数组不能随意排序 |
+
+### TTL 相关（v6 单位是**毫秒**）
+
+| 错误 | 正确做法 |
+|------|----------|
+| TTL 单位误传为秒，例如用 `60` 表示 1 分钟 | `cache-manager` v5、v6 的 TTL 均以毫秒计，1 分钟应传 `60_000`。当前平台仍要求 TTL 在 `30_000 - 86_400_000` ms 内，`60` 不在允许范围内 |
+| 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 DTO，并明确缓存命中与回源返回相同的数据结构；日期可转为约定的字符串，二进制使用文件地址 |
+| 缓存 `null` 表示“资源不存在” | 用带类型标记的结构，如 `{ kind: 'not-found' }`，与 miss 区分。只有允许延迟发现新数据时才缓存；TTL 遵循平台范围，超时和服务错误不能写成“不存在” |
+| 单 value 接近或超过 1 MB | 先裁剪字段或按分页 Key 拆分；大文件用 CDN / 对象存储。分页 Key 仍需纳入查询维度并估算数量 |
+
+### API 姿势相关
+
+| 错误 | 正确做法 |
+|------|----------|
+| 业务模块里再 `CacheModule.register()` / `registerAsync(...)` | 平台已全局注册，直接 `@Inject(CACHE_MANAGER)`；重复注册会创建独立内存 store，不走 Redis、不 fail-open |
+| 用 `CacheInterceptor` 缓存写请求 | Interceptor 只适合幂等 GET；写请求用 A 方案，配 `cache.del(key)` |
+| 不同路由、查询或身份结果共用一个静态 `@CacheKey` | 静态 Key 不会区分这些结果；无额外身份差异时可用 URL Key，否则使用包含必要维度的动态 Key 或手动缓存，并满足鉴权要求 |
+| 高 QPS 热点用 A 方案而非 `wrap` | 击穿风险，冷启动 loader 会被并发触发 N 次；换 B 方案拿 single-flight（注意仍是单实例内去重） |
+| 用 `cache.wrap` 包业务写入 | `wrap` 仅用于读取和回填。业务数据提交成功后，再 `cache.del(key)` 失效相关缓存；涉及详情和列表时分别确定相关 Key。删除缓存不能保证与并发读取强一致 |
+| 把 `await cache.set()` 等同于业务数据提交，或默认它一定不等待写入 | 当前锁定 SDK 会等待底层 `set`；服务端写入可见性取决于后端契约。缓存不能作为业务提交依据；写后直接使用本次计算或保存得到的结果，不用立即 `get` 来证明业务成功 |
+
+### 授权 / 身份相关（可能导致越权）
+
+| 错误 | 正确做法 |
+|------|----------|
+| 看到 `@CanRole` / `@Can` 就直接拒绝缓存 | 每次请求保留必要鉴权；按返回数据的共享范围评估，命中不能跳过方法内的权限检查 |
+| 用默认 URL Key 缓存按当前身份过滤的结果 | URL 不能表达身份；需从可信请求上下文取得租户、用户等必要维度，隔离结果并满足权限变化要求 |
+| 认为 Key 带 `tenantId` / `userId` 就足够安全 | 身份隔离不能解决权限撤销；无法确保旧结果仍有权访问时，不缓存该结果。Key 数量仍须遵循平台配额 |
+
+### 防御式代码
+
+| 错误 | 正确做法 |
+|------|----------|
+| 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` 就是超范围 |
+| 数据陈旧 | 写后未失效、删除失败、遗漏相关 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 模板，用有限的枚举维度 |
+| 并发压测下源侧被打爆 | 同一 Key 并发回源、Key 不稳定、缓存不可用或多实例同时冷启动 | 先核对 Key、命中与实例数；`wrap` 只合并单进程内并发，多实例压力需结合平台能力另行处理 |
+
+## 验证缓存行为
+
+按本次改动验证相关场景：命中时减少回源，未命中正常读取，`0` / `false` / 空字符串不被误判；影响结果的参数和身份维度正确隔离；写入后按约定失效；缓存不可用时正常回源且业务错误仍能暴露。
+
+涉及身份数据时，验证缓存命中不会跳过鉴权，并检查权限撤销后旧结果不可越权访问。涉及热点时区分单进程并发合并与多实例分别回源。无法运行的检查应说明原因，不将方案预期写成已验证结果。