用途:当代码需要对N个相互独立的外部接口发起大量调用时(如批量查询、逐条补全、按ID获取详情),用并发加磁盘缓存替代一次一个的串行循环,减少等待时间并避免重复请求公共端点,防止被限流或封禁。
主要能力:一是并发,用有界工作池让约10至20个独立请求同时进行;二是磁盘缓存,以方法、完整URL、查询参数和POST正文的哈希作为缓存键,命中则从磁盘读取,不重新发起请求。缓存默认按内容键存续、不过期,直到显式刷新(refresh=True 或 CACHE_BYPASS=1)。
使用方式:先用 fetch(request)->response 封装单次网络调用,先查磁盘、未命中再实时请求、成功后写入;再对集合用有界池映射该函数,保留输入顺序;为项目添加 .cache/api/ 之类的本地缓存目录,写入 .gitignore,采用临时文件加重命名的原子写入,只缓存成功响应,失败不写以让下次重试;保持代码原有错误约定。
适用场景:循环体中出现 requests.get/post、httpx、urllib、fetch、axios 或 SDK 客户端调用;提示要求逐项查找、解析、标注或补全;重构已串行且较慢的代码;以及先找ID再逐ID取详情的两步式API。仅一两处调用时无需引入并发。
限制:相互依赖的调用无法并行;无界并发会触发限流并耗尽文件描述符;仅内存缓存无法跨运行留存;命中失败的缓存会永久重放错误;对稳定数据加TTL过期机制是不必要的复杂化;缓存属于派it生数据不应提交到版本库。各语言可适配实现详见 references/patterns.md。