用途
本技能用于 Effect(TypeScript 效应系统库)中的自动优化:批处理(Batching)、缓存(Caching)与请求去重(Deduplication)。核心目标是自动解决 N+1 查询问题——把循环中逐个发起的 API 调用合并为单次批量调用。
主要能力
请求批处理(Request-Based Batching):基于 Request 与 RequestResolver 实现。分四步:
- 定义 Request 类型(使用 Request.Request 接口与 Request.tagged 构造器)。
- 创建 Resolver(RequestResolver.makeBatched 处理请求数组,在单次调用中完成全部请求,并用 Request.completeEffect 回填每个结果)。
- 定义查询函数(Effect.request(请求, Resolver))。
- 以自动批处理方式使用(在 Effect.forEach 中设置 concurrency: "unbounded")。
示例中把逐个 getUserById 的调用转换为一次 POST /api/users/batch 请求。
Resolver 类型:标准 Resolver(RequestResolver.fromEffect,不批处理);批处理 Resolver(RequestResolver.makeBatched);带 Context 的 Resolver(可从 Context 获取 HttpClient、Logger 等服务,并用 RequestResolver.provideContext 提供上下文)。
缓存能力:
- Effect.cached:记忆化 Effect 结果。
- Effect.cachedWithTTL:基于时间过期(如 "5 minutes")。
- Effect.cachedInvalidateWithTTL:返回缓存与手动失效函数。
- Cache 服务(Cache.make):可配置 capacity(如 100)、timeToLive(如 "10 minutes")与 lookup 函数,支持 cache.get、cache.contains、cache.invalidate、cache.cacheStats。
请求缓存与去重:在查询上下文内,相同请求自动缓存与去重(重复 getUserById(1) 只请求一次)。可通过 Effect.withRequestCaching(false) 禁用,通过 Request.makeCache 创建自定义缓存(capacity、timeToLive)并用 Effect.withRequestCache 应用。可用 Effect.withRequestBatching(false) 禁用批处理。
使用方式
以示例代码逐步定义 Request 类型、批处理 Resolver 与查询函数,然后在业务 Effect 中以普通调用方式使用,批处理与缓存会自动生效;如需上下文或自定义参数,使用 provideContext、makeCache 等组合子。参数(容量、TTL)由开发者按需设定。
适用场景
- N+1 场景(尤其涉及数据库或 API 的循环单请求)。
- 需要缓存昂贵计算的场合。
- 并发重复请求需要去重的场合。
- 在 API 边界上合并相关请求。
限制与注意事项
资料仅给出使用模式与最佳实践(如为 N+1 使用批处理、缓存昂贵计算、设置合适 TTL、利用自动去重、在 API 边界批处理),未说明性能基准或具体框架兼容范围。批处理与缓存的容量、TTL 等取值需自行权衡新鲜度与性能,资料未提供推荐数值。完整文档指向 ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt,可检索 Batching、Caching、Cache、Caching Effects 等章节。