NestJS 缓存策略实战：在 Comp AI CRM 中基于 CacheModule 与 Redis 构建高性能数据层

后端前端CRM人工智能AI Agent【免费下载链接】crmComp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.项目地址https://gitcode.com/gh_mirrors/crm48/crm点击查看免费下载导读缓存是 NestJS 应用中降低数据库负载、缩短响应时间的核心手段但缓存一切与完全不缓存同样是性能陷阱。本文以 Comp AI CRMAgentic-first 开源 CRMAPI 服务中的真实实现为蓝本系统讲解如何使用 NestJSCacheModule基于cache-manager与keyv/redis为昂贵查询、频繁访问数据和外部 API 调用建立分层缓存并配合 TTL、主动失效、事件驱动失效与分布式锁等策略实现既显著减负又保证数据一致性的缓存架构。读完本文你将掌握模块级缓存配置、手动缓存读写、装饰器式自动缓存以及事件驱动失效的完整落地方法。一、缓存原则聚焦高影响区域拒绝两个极端NestJS 官方缓存文档与 Comp AI CRM 的开发规范见 .agents/skills/nestjs-best-practices/rules/perf-use-caching.md都强调同一核心原则为昂贵操作、频繁访问的数据和外部 API 调用实现缓存配合恰当的 TTL 与失效策略而不是缓存一切。两种典型的反面写法必须避免完全不缓存每次请求都重复执行复杂的聚合查询如多表leftJoingroupByorderBy即使结果在短时间内不会变化也白白消耗数据库资源。无脑缓存一切给所有查询都加上CacheInterceptor并设置超长 TTL如 3600 秒。对变化频繁的数据如用户列表缓存 1 小时会导致用户看到过期的数据且失效路径缺失时缓存永远不会刷新。正确的姿势是战略性缓存识别出读多写少、计算昂贵、对实时性要求不高的高影响区域再为每个场景选择 TTL 与失效策略。下面结合 Comp AI CRM 的源码逐一展开四种实战形态。二、模块级配置CacheModule KeyvRedis 全局接入NestJS 官方推荐的接入方式是在根模块通过CacheModule.registerAsync()注册缓存实例使其对全应用可用。Comp AI CRM 在此基础上封装了一个全局缓存模块位于 apps/api/src/cache/cache.module.ts完整实现如下import KeyvRedis from keyv/redis; import { CacheModule, type CacheOptions } from nestjs/cache-manager; import { Logger, Module } from nestjs/common; import { ConfigService } from nestjs/config; import type { EnvironmentVariables } from ../config/env.validation; const DEFAULT_TTL_MS 60_000; Module({ imports: [ CacheModule.registerAsync({ isGlobal: true, inject: [ConfigService], useFactory: ( config: ConfigServiceEnvironmentVariables, true, ): CacheOptions { const logger new Logger(CacheModule); const redisUrl config.get(REDIS_URL, { infer: true }); const ttl config.get(CACHE_TTL_MS, { infer: true }) ?? DEFAULT_TTL_MS; if (!redisUrl) { logger.warn({ message: REDIS_URL is not set — falling back to a per-instance in-memory cache., ttl, }); return { ttl }; } logger.log({ message: Cache backed by Redis, ttl }); return { ttl, stores: [new KeyvRedis(redisUrl)] }; }, }), ], exports: [CacheModule], }) export class AppCacheModule {}该实现的关键细节isGlobal: true缓存模块全局注册任何业务模块无需重复导入即可注入CACHE_MANAGER。在 apps/api/src/app.module.ts 中AppCacheModule被加入根模块imports全 API 服务共享同一缓存实例。双后端自适应通过REDIS_URL判断存储后端——配置了 Redis 则使用keyv/redis的KeyvRedis存储未配置则回退到进程内内存缓存并打出Logger.warn。这意味着本地开发无需 Redis 即可运行生产环境再切换到分布式 Redis。默认 TTL 全局可调CACHE_TTL_MS环境变量控制默认 TTL默认 60 秒各业务模块可在此基础上用更短的局部 TTL 覆盖。对应的环境变量在 apps/api/src/config/env.validation.ts 中声明为可选REDIS_URL?: string与CACHE_TTL_MS?: number带IsInt、Min(0)校验并在 .env.example 中给出示例# REDIS_URLredis://localhost:6379 # CACHE_TTL_MS60000启用 Redis 缓存只需设置REDIS_URL并重启 API 服务启动日志会输出Cache backed by Redis未设置时则会输出回退警告。三、手动缓存粒度控制 显式失效cache-manager API装饰器自动缓存适合读接口但需要缓存命中后的自定义逻辑、异步写缓存、按需失效的场景就必须直接注入CACHE_MANAGER手动操作。cache-manager提供三件套cache.get(key)、cache.set(key, value, ttlMs)、cache.del(key)。Comp AI CRM 的AuthService是手动缓存的典型范例apps/api/src/auth/auth.service.tsconst PROFILE_TTL_MS 5 * 60_000; const profileKey (userId: string) auth:profile:${userId}; Injectable() export class AuthService { constructor( InjectDatabase() private readonly db: Db, Inject(CACHE_MANAGER) private readonly cache: Cache, ) {} async getProfile(userId: string): PromiseUserProfile { const key profileKey(userId); const cached await this.cache.getUserProfile(key); if (cached) { return cached; } this.logger.debug({ message: Profile cache miss, userId }); const user await this.db.user.findUnique({ where: { id: userId }, select: { id: true, name: true, email: true, emailVerified: true, image: true, createdAt: true, }, }); if (!user) { this.logger.warn({ message: Session user no longer exists, userId }); throw new NotFoundException(No user with id ${userId}.); } const profile: UserProfile { ...user, createdAt: user.createdAt.toISOString(), }; await this.cache.set(key, profile, PROFILE_TTL_MS); return profile; } async invalidateProfile(userId: string): Promisevoid { await this.cache.del(profileKey(userId)); this.logger.debug({ message: Invalidated cached profile, userId }); } }这里沉淀了三条可复用的经验命名规范缓存键采用auth:profile:${userId}的命名空间冒号分隔格式避免不同业务模块键冲突。TTL 按数据特性定用户资料属于读多写少但会变的数据5 分钟 TTLPROFILE_TTL_MS既能吸收大部分重复读又保证资料变更最多延迟 5 分钟生效。失效与写入对称invalidateProfile()在资料更新路径上被调用主动删除对应键配合 TTL 形成双保险。外部 API 调用是另一个高价值缓存场景。ModelCatalogServiceapps/api/src/settings/model-catalog.service.ts将模型目录这种第三方 HTTP 接口的结果缓存 30 分钟const CATALOG_TTL_MS 30 * 60_000; const CATALOG_KEY settings:model-catalog; const CATALOG_TIMEOUT_MS 5_000; async models(): PromiseCatalogModel[] | null { const cached await this.cache.getCatalogModel[](CATALOG_KEY); if (cached) return cached; const models await this.fetchCatalog(); if (!models) return null; await this.cache.set(CATALOG_KEY, models, CATALOG_TTL_MS); return models; }fetchCatalog()内部还使用了AbortSignal.timeout(CATALOG_TIMEOUT_MS)设置 5 秒超时并在失败时返回null而不是抛错——外部依赖故障时降级、且不污染缓存这是缓存外部调用的重要容错姿势。四、装饰器缓存CacheInterceptor CacheKey CacheTTL对于纯粹的读接口NestJS 提供声明式缓存在控制器或方法上挂CacheInterceptor自动缓存返回值配合CacheKey自定义键、CacheTTL覆盖 TTL。Controller(categories) UseInterceptors(CacheInterceptor) export class CategoriesController { Get() CacheTTL(30 * 60 * 1000) // 30 minutes - categories rarely change findAll(): PromiseCategory[] { return this.categoriesService.findAll(); } Get(:id) CacheTTL(60 * 1000) // 1 minute CacheKey(category) findOne(Param(id) id: string): PromiseCategory { return this.categoriesService.findOne(id); } }使用要点TTL 与数据变化频率匹配几乎不变的数据如分类目录可用 30 分钟甚至更长变化稍快的数据如单条详情用 1 分钟。TTL 单位是毫秒。CacheKey是静态的多个动态参数的方法共享同一键会互相覆盖因此动态接口更适合在方法内部手动构造键回到第三节的写法或让CacheInterceptor默认基于路由自动生成键。只读接口优先装饰器写路径必须配合失效如果该控制器存在更新操作务必在写方法中通过cache.del()清理对应键否则缓存会长期过期。五、事件驱动失效OnEvent 批量清缓存当同一类数据被多个写路径修改时逐个调用cache.del()容易遗漏。NestJS 的事件系统可以把失效收敛到一处Injectable() export class CacheInvalidationService { constructor(Inject(CACHE_MANAGER) private cache: Cache) {} OnEvent(product.created) OnEvent(product.updated) OnEvent(product.deleted) async invalidateProductCaches(event: ProductEvent) { await Promise.all([ this.cache.del(products:popular), this.cache.del(product:${event.productId}), ]); } }多个OnEvent装饰器可以叠加在同一方法上批量清除受影响的键用Promise.all并发删除失效延迟降到最低。这种模式特别适合产品、公司、联系人这类多入口变更的领域对象。Comp AI CRM 的TrackingConfigServiceapps/api/src/tracking/tracking-config.service.ts给出了事件失效的进阶变体——代数失效generation-based invalidation它维护一个generation计数器任何配置变更invalidate()、rotateSiteId()都会generation 1并删除缓存键写入新配置时只有当前代数未被并发覆盖才重新填充缓存从而避免并发写场景下的读写竞态async invalidate(): Promisevoid { this.generation 1; const written this.generation; await this.cache.del(CONFIG_KEY); // ...重新读取配置、更新 hash... if (written ! this.generation) return; // 已被更新的写入抢占 if (!(await this.current(hash))) return; // hash 已过期 await this.cache.set(CONFIG_KEY, { config, hash }, CONFIG_TTL_MS); }同时它用configHash与数据库中的trackingConfigHash比对确保只有当前仍是权威配置时才回填缓存从源头避免缓存写入过期数据。六、进阶实践用缓存实现分布式防重Backfill 自动任务锁缓存不仅能提速还能充当跨实例的短期互斥锁。BackfillServiceapps/api/src/backfill/backfill.service.ts在用户登录后触发自动回填用一个 5 分钟 TTL 的缓存键防止多实例/多用户同时触发重复的回填任务const AUTO_KEY backfill:auto; const AUTO_EVERY_MS 5 * 60_000; async auto(): Promise{ started: boolean } { if (await this.cache.get(AUTO_KEY)) return { started: false }; await this.cache.set(AUTO_KEY, true, AUTO_EVERY_MS); void (async () { try { await this.sweepWorkspace(); const companies await this.runCompanies(false); const contacts await this.runContacts(); // ... } catch (error) { this.logger.error(...); } })(); return { started: true }; }这段代码展示了缓存超越提速的第二种价值缓存即分布式锁。AUTO_KEY存在即表示最近 5 分钟内已有一次回填在跑后续调用直接短路返回。相比数据库锁它零额外表、天然带过期进程崩溃也不会死锁代价是 5 分钟内最多触发一次——对回填这种幂等批处理任务完全够用。其注释还揭示了缓存与重试频率配合的设计思想照片搜索等昂贵操作 30 天才重试一次RECHECK_PHOTO_AFTER_MS避免反复支付外部服务费用。七、实战对照把规则落进你的 NestJS 项目综合 Comp AI CRM 的落地实践可以提炼出一份可直接套用的决策清单场景推荐方案TTL 参考失效策略重复执行的复杂聚合查询手动cache.get/set包裹查询5s ~ 60s写路径显式cache.del用户资料等读多写少数据手动缓存 命名空间键5 分钟资料更新时失效外部第三方 API 结果手动缓存 超时 失败降级10 ~ 30 分钟TTL 自然过期纯只读列表/详情接口CacheInterceptorCacheTTL按变化频率 1~30 分钟写接口配del多写路径的领域对象事件驱动批量失效中等 TTLOnEvent集中失效批处理/定时任务防重缓存键即分布式锁等于任务执行窗口TTL 自动解锁最后回到最初的规则perf-use-caching.md先度量再缓存聚焦高影响区域。缓存不是银弹——键设计、TTL 选择、失效时机与并发安全共同决定成败。Comp AI CRM 给出的参考实现全局 CacheModule、手动缓存、代数失效、缓存即锁覆盖了从读路径提速到写路径一致性再到分布式防重的完整闭环值得在引入缓存时逐一对标。赞分享后端前端CRM人工智能AI Agent【免费下载链接】crmComp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.项目地址https://gitcode.com/gh_mirrors/crm48/crm点击查看免费下载相关推荐Comp AI CRM 中的 NestJS 接口限流实践基于 nestjs/throttler 的多层限流方案Comp AI CRM 中的 NestJS 接口限流实践基于 nestjs/throttler 的多层限流方案 导读 本文围绕 .agents/skills后端前端CRM人工智能AI AgentAwesome MQTT工具大全25款必备客户端与调试工具推荐Awesome MQTT工具大全25款必备客户端与调试工具推荐 MQTT作为轻量级的客户端 服务器发布/订阅消息协议在物联网、传感器网络、智能家居等领域有着终极指南如何使用Electric与Redis构建高性能数据访问层终极指南如何使用Electric与Redis构建高性能数据访问层 在现代应用开发中数据访问性能直接影响用户体验和系统可扩展性。Electric作为一款灵活的后端数据同步数据库人工智能AI AgentMCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考