Dagger TypeScript SDK 的 EngineCacheEntrySet 类查询与理解引擎缓存条目集合【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger导读EngineCacheEntrySet是 Dagger TypeScript SDKdagger.io/dagger版本 0.20中用于表示一次缓存查询所返回的缓存条目集合的核心类。它由engine.localCache.entrySet()查询产生是对 Dagger 引擎本地缓存local cache进行观测、分析与容量评估的关键入口。阅读本文后你将掌握EngineCacheEntrySet的完整 API 面构造器约束、四个查询方法、与之配套的EngineCacheEntry/EngineCacheEntrySetID/EngineCacheEntrySetOpts类型以及它在 Dagger 引擎侧GraphQL schema 与核心结构体的底层实现原理与典型使用方式。类概览EngineCacheEntrySet 是什么EngineCacheEntrySet的官方定义是 A set of cache entries returned by a query to a cache即一次缓存查询所返回的一组缓存条目。在 Dagger 的 TypeScript API 分层中它位于api/client.gen模块下完整路径为api/client.gen.EngineCacheEntrySet。继承关系EngineCacheEntrySet直接继承自BaseClient。BaseClient是所有 Dagger GraphQL 客户端对象的公共基类负责持有Context、执行 GraphQL 查询与结果解析等底层能力因此该类的所有方法都遵循惰性查询、返回 Promise的 SDK 约定。构造器仅供内部使用new EngineCacheEntrySet(ctx?, _id?, _diskSpaceBytes?, _entryCount?)参数类型说明ctx?ContextDagger 客户端上下文_id?EngineCacheEntrySetID该条目集合的唯一标识_diskSpaceBytes?number集合内条目占用的总磁盘字节数_entryCount?number集合内条目数量官方文档明确标注Constructor is used for internal usage only, do not create object from it.构造器仅供内部使用请勿直接通过它创建对象。这一点与 Dagger SDK 的整体设计一致所有客户端对象都应通过 GraphQL 查询链路例如client.engine().localCache().entrySet()由 SDK 自动实例化而不是手动new。获取 EngineCacheEntrySet查询链路EngineCacheEntrySet不能凭空存在它来自对引擎缓存对象的查询。在 TypeScript SDK 中典型链路为// 获取引擎缓存条目集合全量缓存 const entrySet await client.engine().localCache().entrySet();entrySet()方法接受可选的key参数对应EngineCacheEntrySetOpts用于按缓存键定位特定条目集合未传key时返回当前缓存的全量条目集合。从引擎侧实现看core/schema/engine.go当key为空字符串时schema 解析器会生成一个基于identity.NewID()的随机 key 并重新选择entrySet字段当key非空时则调用query.EngineLocalCacheEntries(ctx)加载真实的本地缓存条目并包装为结果。同时该解析器通过query.RequireMainClient(ctx)校验当前调用来自主客户端这与文档中查询缓存的语义吻合。实例方法详解EngineCacheEntrySet共暴露四个实例方法全部返回PromisediskSpaceBytes()diskSpaceBytes(): Promisenumber返回该集合中所有缓存条目占用的总磁盘空间字节。该字段对应核心结构体中的DiskSpaceBytes int见 core/engine.go。它是评估引擎本地缓存体积的首要指标常用于容量监控或触发清理前的自查。entryCount()entryCount(): Promisenumber返回该集合中缓存条目的数量。对应核心结构体的EntryCount int字段见 core/engine.go。与diskSpaceBytes()结合可以计算单条目平均占用判断缓存碎片化程度。entries()entries(): PromiseEngineCacheEntry[]返回集合内各个独立缓存条目的数组元素类型为EngineCacheEntry。从 GraphQL 解析器看core/schema/engine.go该字段直接返回父对象上已加载的EntriesList。这是对缓存做细粒度分析的入口——每个EngineCacheEntry还携带描述、占用字节数、创建/最近使用时间、是否活跃、记录类型等字段。id()id(): PromiseEngineCacheEntrySetID返回该EngineCacheEntrySet的唯一标识符类型为EngineCacheEntrySetID见 type-aliases/EngineCacheEntrySetID.md。该 ID 类型是string object的交叉类型属于 Dagger 的 ID 标量体系可在后续查询中用于引用该对象实例。配套类型EngineCacheEntry、EngineCacheEntrySetID 与 EngineCacheEntrySetOptsEngineCacheEntry集合中的单个条目entries()返回的每个元素是EngineCacheEntry详见 classes/EngineCacheEntry.md其方法面如下方法返回类型语义id()EngineCacheEntryID条目的唯一标识description()string条目描述diskSpaceBytes()number该条目占用的磁盘字节数createdTimeUnixNano()number条目创建时间Unix 纳秒mostRecentUseTimeUnixNano()number最近一次使用时间Unix 纳秒activelyUsed()boolean条目当前是否正被活跃使用recordType()string缓存记录类型如regular、internal、frontend、source.local、source.git.checkout、exec.cachemount等其中recordType()对缓存分析尤其重要它揭示了缓存条目的来源类别例如exec.cachemount表示某次容器执行中挂载的缓存卷source.git.checkout表示 Git 检出结果。这些字段与核心结构体EngineCacheEntry见 core/engine.go一一对应其中核心结构体还额外保留了RecordTypes []string存储记录类型列表与DagqlCall string产生该条目的 DagQL 调用两个字段。EngineCacheEntrySetIDEngineCacheEntrySetID定义为string object其类型声明包含一个值为never的__EngineCacheEntrySetID属性见 type-aliases/EngineCacheEntrySetID.md。这种品牌化字符串branded string手法用于在编译期区分不同对象类型的 ID避免把缓存的 ID 误用于其他对象查询。EngineCacheEntrySetOptsEngineCacheEntrySetOpts是entrySet()的可选参数对象见 type-aliases/EngineCacheEntrySetOpts.md仅含一个可选属性{ key?: string; // 用于定位特定缓存条目集合的缓存键 }不传key时表示查询整个缓存的条目集合。源码级原理从 GraphQL 到核心结构体从仓库源码可以完整还原EngineCacheEntrySet的底层链路Schema 注册engineSchema.Install()在 GraphQL 服务器上注册了Engine→EngineCache→EngineCacheEntrySet→EngineCacheEntry的层级见 core/schema/engine.goQuery.engine返回引擎对象Engine.localCache返回本地缓存对象同时携带策略字段ReservedSpace、TargetSpace、MaxUsedSpace、MinFreeSpace见 core/schema/engine.goEngineCache.entrySet以 NodeFunc 形式注册接受可选的key输入返回EngineCacheEntrySetEngineCacheEntrySet.entries返回EngineCacheEntry[]。核心结构体EngineCacheEntrySet在 Go 侧定义为包含EntryCount、DiskSpaceBytes两个可查询字段以及未暴露的EntriesList切片见 core/engine.go。EngineCacheEntry则承载描述、空间、时间戳、活跃状态与记录类型等字段见 core/engine.go。与缓存清理的关系EngineCache还注册了prune变异mutation支持useDefaultPolicy、maxUsedSpace、reservedSpace、minFreeSpace、targetSpace、maxEstimatedBytes、targetEstimatedBytes等清理参数见 core/schema/engine.go。也就是说EngineCacheEntrySet负责观察缓存现状而prune负责执行缓存回收二者共同构成 Dagger 引擎本地缓存的可观测与治理能力。ID 与缓存entrySet以dagql.NodeFunc注册并带dagql.PerCallInput配合EngineCacheEntrySetID这类品牌化 ID 类型使该对象可以被 Dagger 的 DAGQL 缓存与引用机制管理。典型使用场景与示例将上述 API 组合起来可以在一个 TypeScript 模块中完成缓存体检import { connect } from dagger.io/dagger; connect(async (client) { // 1. 获取本地缓存条目集合 const entrySet await client.engine().localCache().entrySet(); // 2. 总量概览 const totalBytes await entrySet.diskSpaceBytes(); const count await entrySet.entryCount(); const id await entrySet.id(); console.log(cache id${id} entries${count} totalBytes${totalBytes}); // 3. 逐条分析可结合 prune 决定清理策略 const entries await entrySet.entries(); for (const entry of entries) { const desc await entry.description(); const bytes await entry.diskSpaceBytes(); const type await entry.recordType(); const active await entry.activelyUsed(); console.log(${type} | ${active ? active : idle} | ${bytes}B | ${desc}); } });典型应用包括缓存容量监控周期性读取diskSpaceBytes()在接近EngineCache的maxUsedSpace策略阈值前预警缓存效率分析通过entries()与recordType()统计各类缓存如exec.cachemount、source.git.checkout的占比与闲置情况清理决策辅助结合EngineCache.prune()的useDefaultPolicy、targetSpace等参数先观测后清理。使用注意事项不要直接构造EngineCacheEntrySet的构造器仅供 SDK 内部使用必须通过client.engine().localCache().entrySet()等查询链路获取实例。字段为惰性加载所有方法返回Promise即每次调用都会解析对应 GraphQL 字段批量读取时注意按需取用避免无谓的重复查询。主客户端约束从源码看cacheEntrySet解析器会调用RequireMainClient(ctx)见 core/schema/engine.go即该查询要求由主客户端发起多客户端会话中需注意调用方身份。时间字段为纳秒createdTimeUnixNano等字段使用 Unix 纳秒精度与其他 SDK 中常见的毫秒/秒单位不同换算时可除1e9得到秒。小结EngineCacheEntrySet是 Dagger TypeScript SDK 中观测引擎本地缓存的统一入口通过diskSpaceBytes()、entryCount()、entries()与id()四个方法开发者可以快速掌握缓存总体规模并下钻到单个EngineCacheEntry的细节而其底层由 core/schema/engine.go 的 GraphQL 解析器与 core/engine.go 的核心结构体共同支撑并与EngineCache.prune缓存回收能力形成观测—治理闭环。理解这个类是编写缓存感知型 Dagger 模块、诊断构建性能的第一步。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考