Dagger EngineCacheEntry 完全指南用 TypeScript SDK 读取与分析引擎缓存条目的 5 个核心方法【免费下载链接】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导读EngineCacheEntry是 Dagger TypeScript SDKdagger.io/dagger中用于描述引擎缓存中单个缓存条目的客户端类它把 Dagger 引擎Engine本地缓存里每一条记录如源码检出、依赖缓存、exec.cachemount挂载点等抽象为可查询的对象。本文以官方 API 文档classes/EngineCacheEntry.md为骨架结合仓库内 SDK 生成源码、核心引擎实现与集成测试完整讲解该类的构造规则、6 个实例方法、底层数据来源以及如何通过engine.cache().entrySet().entries()链路实际读取缓存条目帮助你构建缓存可视化、容量审计与占用分析工具。一、EngineCacheEntry 在 Dagger 缓存体系中的位置在 Dagger 的 TypeScript API 中缓存相关对象构成一条清晰的查询链Client.engine() → EngineCache → entrySet() → EngineCacheEntrySet → entries() → EngineCacheEntry[]EngineCache 代表 A cache storage for the Dagger engine引擎的缓存存储通过entrySet()方法返回一个缓存条目集合EngineCacheEntrySet描述 A set of cache entries returned by a query to a cache一次缓存查询返回的条目集合提供entries()、entryCount()、diskSpaceBytes()EngineCacheEntry则是集合中的单个成员官方定义为 An individual cache entry in a cache entry set。在引擎侧对应数据结构定义于 core/engine.gotype EngineCacheEntry struct { Description string field:true doc:The description of the cache entry. DiskSpaceBytes int field:true doc:The disk space used by the cache entry. CreatedTimeUnixNano int field:true doc:The time the cache entry was created, in Unix nanoseconds. MostRecentUseTimeUnixNano int field:true doc:The most recent time the cache entry was used, in Unix nanoseconds. ActivelyUsed bool field:true doc:Whether the cache entry is actively being used. RecordType string field:true doc:The type of the cache record (e.g. regular, internal, frontend, source.local, source.git.checkout, exec.cachemount). RecordTypes []string field:true doc:The storage record types represented by this cache entry. DagqlCall string field:true doc:The DagQL call that produced this cache entry. }也就是说一条缓存条目至少携带描述、磁盘占用字节、创建时间Unix 纳秒、最近使用时间Unix 纳秒、是否正在被使用这五类信息。其中RecordType的取值示例regular、internal、frontend、source.local、source.git.checkout、exec.cachemount揭示了 Dagger 缓存条目的来源多样性——从本地目录源、Git 检出到WithMountedCache的挂载缓存都各有独立的记录类型。二、类概览继承关系与构造约束2.1 继承关系EngineCacheEntry直接继承自BaseClient。所有 Dagger TypeScript SDK 客户端类都共享这一基类因此该类天然具备惰性执行 GraphQL 查询、上下文传递等通用能力。在生成源码 sdk/typescript/src/api/client.gen.ts 中可以看到它持有以下私有字段export class EngineCacheEntry extends BaseClient { private readonly _id?: ID undefined private readonly _activelyUsed?: boolean undefined private readonly _createdTimeUnixNano?: number undefined private readonly _dagqlCall?: string undefined private readonly _description?: string undefined private readonly _diskSpaceBytes?: number undefined private readonly _mostRecentUseTimeUnixNano?: number undefined private readonly _recordType?: string undefined ... }2.2 构造器仅供内部使用new EngineCacheEntry( ctx?: Context, _id?: EngineCacheEntryID, _activelyUsed?: boolean, _createdTimeUnixNano?: number, _description?: string, _diskSpaceBytes?: number, _mostRecentUseTimeUnixNano?: number, ): EngineCacheEntry文档与源码均明确标注Constructor is used for internal usage only, do not create object from it.构造器仅供内部使用请勿自行创建对象。所有参数均为可选由 SDK 在解析 GraphQL 响应时自动填充。开发者应当通过查询链路获取实例而不是new一个出来——这也符合 Dagger 客户端查询即构建的设计哲学对象代表的是对引擎的一次查询描述而非本地数据快照。三、核心方法逐一解析EngineCacheEntry共暴露 6 个实例方法均为异步方法下表先做总览方法返回类型语义id()PromiseEngineCacheEntryID该缓存条目的唯一标识符description()Promisestring缓存条目的描述文本diskSpaceBytes()Promisenumber缓存条目占用的磁盘空间字节createdTimeUnixNano()Promisenumber缓存条目创建时间Unix 纳秒mostRecentUseTimeUnixNano()Promisenumber缓存条目最近一次被使用的时间Unix 纳秒activelyUsed()Promiseboolean缓存条目当前是否正被使用3.1 id()唯一标识id(): PromiseEngineCacheEntryID返回 A unique identifier for this EngineCacheEntry该缓存条目的唯一标识。其返回类型EngineCacheEntryID在 type-aliases/EngineCacheEntryID.md 中定义为string { __EngineCacheEntryID: never }的交叉类型是一个结构化字符串标量代表 an identifier for an object of type EngineCacheEntry。注意它在 SDK 中的实现带有短路缓存若构造时已传入_id直接返回本地值否则才发起 GraphQL 选择器id的查询。这也解释了为何entries()返回的每个EngineCacheEntry都能携带已解析的 ID。3.2 description()人类可读描述description(): Promisestring返回 The description of the cache entry。对应引擎侧Description字段用于向运维人员说明该条目是什么例如某次源码检出或某个依赖层的描述文本是排查这条缓存到底是谁产生的时的首要字段。3.3 diskSpaceBytes()磁盘占用diskSpaceBytes(): Promisenumber返回 The disk space used by the cache entry单位是字节。配合EngineCacheEntrySet.diskSpaceBytes()整个集合的总占用可用于统计缓存总量与单条最大占用找出缓存大头决定清理优先级与EngineCache的maxUsedSpace()、minFreeSpace()等容量策略对照评估当前缓存水位。3.4 createdTimeUnixNano()创建时间createdTimeUnixNano(): Promisenumber返回 The time the cache entry was created, in Unix nanosecondsUnix 纳秒精度的时间戳。由于 Go 侧类型为intJS 中对应number如需转换为毫秒可除以1_000_000。该时间戳可用来筛选很久未创建、很可能可回收的冷条目。3.5 mostRecentUseTimeUnixNano()最近使用时间mostRecentUseTimeUnixNano(): Promisenumber返回 The most recent time the cache entry was used, in Unix nanoseconds。相比创建时间这个字段更能反映缓存条目的活跃度即使创建了很久只要最近仍在使用就不宜优先清理。它常与activelyUsed()组合作为评估缓存淘汰价值的两个关键信号。3.6 activelyUsed()活跃状态activelyUsed(): Promiseboolean返回 Whether the cache entry is actively being used当前是否正被活跃使用。正在被运行中的执行任务引用的缓存条目会被标记为true这类条目在清理时应被保护避免破坏正在进行的构建。四、实战读取并遍历全部缓存条目4.1 完整调用链示例由于构造器仅供内部使用实际获取EngineCacheEntry实例的唯一途径是走查询链路。参考 core/schema/engine.go 中entrySet解析器与 SDK 生成的EngineCacheEntrySet.entries()见 client.gen.ts典型 TypeScript 代码为import { connect } from dagger.io/dagger connect(async (client) { // 1. 拿到引擎缓存 const cache client.engine().cache() // 2. 获取缓存条目集合可按 key 过滤 const entrySet cache.entrySet() // 3. 遍历每一条缓存条目并读取其属性 const entries await entrySet.entries() console.log(total entries: ${await entrySet.entryCount()}) console.log(total disk space (bytes): ${await entrySet.diskSpaceBytes()}) for (const entry of entries) { const description await entry.description() const diskBytes await entry.diskSpaceBytes() const createdNs await entry.createdTimeUnixNano() const lastUsedNs await entry.mostRecentUseTimeUnixNano() const inUse await entry.activelyUsed() const id await entry.id() console.log({ id, description, diskBytes, createdMs: createdNs / 1_000_000, lastUsedMs: lastUsedNs / 1_000_000, activelyUsed: inUse, }) } })4.2 entrySet 的 key 参数cache.entrySet()支持可选的key参数EngineCacheEntrySetOpts。从 core/schema/engine.go 的实现看key默认值为空字符串当key为空时解析器会生成一个随机identity.NewID()作为 key 重新查询——即不指定 key 就返回当前默认缓存集合当指定 key 时调用query.EngineLocalCacheEntries(ctx)加载对应的缓存条目集合。4.3 惰性查询机制观察 SDK 生成代码可以发现每个访问器都遵循本地已有值直接返回否则按需发起 GraphQL 选择器查询的模式例如activelyUsed async (): Promiseboolean { if (this._activelyUsed) { return this._activelyUsed } const ctx this._ctx.select(activelyUsed) const response: Awaitedboolean await ctx.execute() return response }这意味着循环中逐个调用description()、diskSpaceBytes()等会产生多次引擎往返。如果在意性能建议按需读取字段或将多个标量字段的选择合并到一次 GraphQL 查询中执行。五、底层实现从 GraphQL 到引擎查询5.1 Schema 层EngineCacheEntry并非独立的根查询对象而是挂在EngineCache下的子对象。在 core/schema/engine.go 中Schema 注册了entrySet字段带可选key参数用于返回EngineCacheEntrySetentries字段cacheEntrySetEntries见同文件第 186 行起用于展开集合中的单个条目列表。同时该文件还展示了配套的cachePrune方法第 144 行起参数包括useDefaultPolicy、maxUsedSpace、reservedSpace、minFreeSpace、targetSpace以及结构化元数据估算值maxEstimatedBytes、targetEstimatedBytes——说明读取条目只是缓存治理的一半另一半是修剪prune。5.2 引擎查询接口从源码结构看真正加载缓存条目的是引擎查询接口 core/query.go 中声明的EngineLocalCacheEntries(context.Context) (*EngineCacheEntrySet, error) PruneEngineLocalCacheEntries(context.Context, EngineCachePruneOptions) (*EngineCacheEntrySet, error)值得注意的细节是cacheEntrySet解析器首先调用query.RequireMainClient(ctx)这意味着该 API 仅在主客户端会话上下文可用对非主客户端如某些子会话会直接报错——这是使用时需要留意的限制。5.3 测试验证集成测试 core/integration/localcache_test.go 提供了消费该 API 的完整参考getCacheEntryVals辅助函数依次调用Description、DiskSpaceBytes、CreatedTimeUnixNano、MostRecentUseTimeUnixNano、ActivelyUsed、RecordType、RecordTypes、DagqlCall并断言无错误。它同时印证了底层条目的字段比 0.19 版 TypeScript 文档暴露的 6 个方法更丰富——当前仓库的引擎模型还包含RecordType、RecordTypes、DagqlCall三个附加字段可以推断后续版本 SDK 可能会逐步暴露这些能力。六、相关类型与配套能力6.1 EngineCacheEntryIDEngineCacheEntryID是id()的返回类型定义见 type-aliases/EngineCacheEntryID.md。它是一个不透明opaque字符串类型string { __EngineCacheEntryID: never }你不能也不应手工构造其值只能通过查询获得并在同一会话内用它引用对应条目。6.2 EngineCacheEntrySet集合类型 classes/EngineCacheEntrySet.md 提供三个方法id()集合唯一标识diskSpaceBytes()集合内所有条目磁盘占用总和entryCount()集合内条目数量entries()返回EngineCacheEntry[]数组。从生成源码看entries()的实现会先只查询每个条目的id再通过selectNode(r.id, EngineCacheEntry)按 ID 重建每个条目对象见 client.gen.ts——这也是为什么上面实战示例中循环内每个访问器都是独立的懒查询。6.3 上游 EngineCache想要进一步管理缓存classes/EngineCache.md 还提供maxUsedSpace()、minFreeSpace()、reservedSpace()、targetSpace()等容量配置读取方法以及prune()修剪方法参数同上文 schema 中的EngineCachePruneOpts。典型治理流程是先entrySet().entries()审计每条条目的磁盘占用与活跃度再决定是否调用prune()释放空间。七、使用注意事项小结不要手动构造构造器仅供内部使用务必通过client.engine().cache().entrySet().entries()获取实例。单位约定diskSpaceBytes单位为字节两个时间字段单位为 Unix 纳秒展示给用户前建议换算为毫秒/秒。惰性求值每个访问器都是独立 GraphQL 查询批量场景注意合并查询或缓存结果避免 N1 次引擎往返。主客户端限制entrySet解析器要求主客户端上下文RequireMainClient在受限会话中可能不可用。活跃标记是瞬态activelyUsed()反映的是查询时刻的状态正在被执行的任务引用的条目为true清理策略应优先保护这类条目。字段在演进当前仓库引擎模型还定义了RecordType取值如source.local、source.git.checkout、exec.cachemount等、RecordTypes与DagqlCall可作为理解未来版本 API 扩展的参考。【免费下载链接】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），仅供参考