Dagger TypeScript SDK 的 EngineCacheEntryID 类型别名引擎缓存条目标识符的 branded string 模式深度解析【免费下载链接】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本篇技术指南聚焦 Dagger自动化引擎用于构建、测试并交付任意代码库TypeScript SDK 中自动生成的EngineCacheEntryID类型别名。它代表了引擎本地缓存中单个缓存条目EngineCacheEntry对象的唯一标识符。读完本文你将理解该类型的精确定义、它背后对应的 GraphQLscalar与 Go 端实现、如何在 TypeScript 代码中通过entrySet/entries/id()链路获取并使用它以及为什么 SDK 要用string object这种品牌化字符串branded string来约束它。一、类型别名定义EngineCacheEntryID到底是什么在docs/versioned_docs/version-0.19/reference/typescript/api/client.gen/type-aliases/EngineCacheEntryID.md中官方文档给出的定义非常简洁type EngineCacheEntryID string object1. 语义EngineCacheEntry 对象的标识符该类型别名代表类型为EngineCacheEntry的对象所对应的标识符scalar 类型。EngineCacheEntry是引擎本地缓存中的一个条目其 GraphQL 注释为 An individual cache entry in a cache entry set缓存条目集合中的单个缓存条目。因此EngineCacheEntryID就是引用某个具体缓存条目时使用的 ID。2. Type Declaration唯一的__EngineCacheEntryID字段原文档中 Type Declaration 部分声明了唯一一个成员__EngineCacheEntryID: never这是典型的phantom / nominal名义化类型技巧object这个交叉项本身不会在运行时产生任何真实属性__EngineCacheEntryID: never只是一个幽灵字段它只存在于类型层面用来让 TypeScript 编译器区分任意 string与EngineCacheEntryID。为什么需要它引擎缓存条目 ID 在运行时就是一个不透明的字符串由引擎生成、内容对客户端无意义但如果你直接把它声明为string开发者就可能误把描述文本、用户名等普通字符串当作 ID 传入 API导致查询失败。通过string { __EngineCacheEntryID: never }这种交叉类型编译器会强制要求该值必须来源于引擎返回的 ID普通字符串字面量无法直接赋值给它从而在编译期就拦截了一类低级错误。二、GraphQL 与源码端的真实形态scalar EngineCacheEntryID该 TypeScript 类型别名并不是凭空定义的它由 Dagger 的代码生成器从 GraphQL Schema 自动生成。在 Schema 测试基准 base_schema.graphqls 中可以找到它的根源An individual cache entry in a cache entry set type EngineCacheEntry implements Node { Whether the cache entry is actively being used. activelyUsed: Boolean! The time the cache entry was created, in Unix nanoseconds. createdTimeUnixNano: Int! The DagQL call that produced this cache entry. dagqlCall: String! The description of the cache entry. description: String! The disk space used by the cache entry. diskSpaceBytes: Int! A unique identifier for this EngineCacheEntry. id: ID! The most recent time the cache entry was used, in Unix nanoseconds. mostRecentUseTimeUnixNano: Int! The type of the cache record (e.g. regular, internal, frontend, source.local, source.git.checkout, exec.cachemount). recordType: String! The storage record types represented by this cache entry. recordTypes: [String!]! } A unique identifier for an object. scalar EngineCacheEntryID从中可以看到几个关键信息EngineCacheEntry实现了Node接口因此它拥有id: ID!字段EngineCacheEntryID正是这个id字段在 TypeScript 端映射出的类型。Schema 还提供了反向加载入口Load a EngineCacheEntry from its ID. loadEngineCacheEntryFromID(id: EngineCacheEntryID!): EngineCacheEntry!这意味着只要持有一个EngineCacheEntryID就可以通过查询重新唤醒对应的缓存条目对象。三、TypeScript SDK 中的对象模型与 ID 获取链路在 TypeScript SDK 的自动生成客户端 client.gen.ts 中围绕EngineCacheEntryID有三个核心类1.EngineCache缓存的入口export class EngineCache extends BaseClient { /** * The current set of entries in the cache */ entrySet (opts?: EngineCacheEntrySetOpts): EngineCacheEntrySet { const ctx this._ctx.select(entrySet, { ...opts }) return new EngineCacheEntrySet(ctx) } // maxUsedSpace / minFreeSpace / reservedSpace / targetSpace / prune ... }其中entrySet可接收EngineCacheEntrySetOptsclient.gen.tsexport type EngineCacheEntrySetOpts { key?: string }key用于按缓存键精确筛选条目不传或传空字符串时引擎会生成一个随机的占位键返回全量条目对应源码 core/schema/engine.go 中args.Key 时identity.NewID()的分支逻辑。2.EngineCacheEntrySet条目集合export class EngineCacheEntrySet extends BaseClient { /** * The list of individual cache entries in the set */ entries async (): PromiseEngineCacheEntry[] { type entries { id: ID } const ctx this._ctx.select(entries).select(id) const response: Awaitedentries[] await ctx.execute() return response.map( (r) new EngineCacheEntry(ctx.copy().selectNode(r.id, EngineCacheEntry)), ) } }这段实现非常值得注意entries()在 GraphQL 查询中只先拉取每个条目的id然后用selectNode(r.id, EngineCacheEntry)把每个 id 重新封装成惰性的EngineCacheEntry对象。也就是说EngineCacheEntryID是对象句柄的基础——后续对该条目任意字段的读取都由这个 id 驱动。3.EngineCacheEntry单个缓存条目与其id()export class EngineCacheEntry extends BaseClient { /** * A unique identifier for this EngineCacheEntry. */ id async (): PromiseID { if (this._id) { return this._id } const ctx this._ctx.select(id) const response: AwaitedID await ctx.execute() return response } }id()返回的正是EngineCacheEntryID在 SDK 中统一以ID类型表示其定义见 client.gen.tsexport type ID string { __ID: never }——与文档中的string object是完全一致的模式。它是惰性求值的如果对象构造时已经携带了 id比如来自entries()的结果则直接返回缓存值否则才发起 GraphQL 查询。四、EngineCacheEntry 的字段拿到 ID 后能读什么一旦通过EngineCacheEntryID拿到条目对象你可以读取以下字段字段定义在 Go 端 core/engine.go并通过 TypeScript 生成器映射为 client.gen.ts 中的方法字段 / 方法类型含义id()PromiseID该缓存条目的唯一标识符即EngineCacheEntryIDdescription()Promisestring缓存条目的描述信息diskSpaceBytes()Promisenumber该条目占用的磁盘空间字节createdTimeUnixNano()Promisenumber条目创建时间Unix 纳秒mostRecentUseTimeUnixNano()Promisenumber条目最近一次被使用的时间Unix 纳秒activelyUsed()Promiseboolean该条目当前是否正在被使用recordType()Promisestring缓存记录类型如regular、internal、frontend、source.local、source.git.checkout、exec.cachemount等recordTypes()Promisestring[]该条目所涵盖的存储记录类型列表dagqlCall()Promisestring产生该缓存条目的 DagQL 调用这些字段配合EngineCacheEntryID可用于分析缓存里到底存了什么、占了多少空间、多久没用过为缓存清理决策提供依据。五、ID 与缓存清理prune的关系EngineCacheEntryID所属的整个缓存查询体系通常服务于缓存治理场景。引擎在 core/schema/engine.go 中提供了prune操作func (s *engineSchema) cachePrune(ctx context.Context, parent *core.EngineCache, args struct { UseDefaultPolicy bool default:false MaxUsedSpace string default: ReservedSpace string default: MinFreeSpace string default: TargetSpace string default: MaxEstimatedBytes dagql.Optional[dagql.Int] TargetEstimatedBytes dagql.Optional[dagql.Int] }) (dagql.Nullable[core.Void], error)对应 TypeScript 端是EngineCache.prune(opts?)其参数定义在 client.gen.tsexport type EngineCachePruneOpts { /** Use enabled engine-wide default disk and structural policies. */ useDefaultPolicy?: boolean /** Override the maximum disk space to keep before pruning (e.g. 200GB or 80%). */ maxUsedSpace?: string /** Override the minimum disk space to retain during pruning (e.g. 500GB or 10%). */ reservedSpace?: string /** Override the minimum free disk space target during pruning (e.g. 20GB or 20%). */ minFreeSpace?: string /** Override the target disk space to keep after pruning (e.g. 200GB or 50%). */ targetSpace?: string maxEstimatedBytes?: number targetEstimatedBytes?: number }典型的工作流是先通过entrySet().entries()拿到一批EngineCacheEntry每个条目都关联一个EngineCacheEntryID读取diskSpaceBytes/mostRecentUseTimeUnixNano等字段评估缓存占用情况再决定是否需要调用prune()按磁盘策略清理。而 Go 端的缓存策略结构core/engine.go定义了四个关键阈值字段MaxUsedSpace不清理时缓存可占用的最大字节数、TargetSpace清理后保留的目标字节数、ReservedSpace策略保证保留的最小磁盘空间、MinFreeSpace垃圾回收希望保留的可用磁盘空间目标。六、使用要点与注意事项1. 不要手工构造 IDEngineCacheEntryID是引擎生成的不透明标识符其内容对客户端而言没有可解析的语义。唯一可靠的获取方式是调用EngineCacheEntry.id()或通过loadEngineCacheEntryFromID相关查询进行往返验证。2. 惰性求值与一次查询Dagger 客户端是惰性的entrySet()本身不会立即发请求只有当你 await 某个字段如entries()、entryCount()时才真正执行 GraphQL 查询。而entries()内部只 selectid后续字段按需再查这保证了以EngineCacheEntryID为句柄的访问模型足够轻量。3. 类型安全是编译期红利由于string object的 phantom 字段设计你在代码里无法把任意字符串直接当作EngineCacheEntryID使用这有效避免了把缓存键、路径等字符串误传给 ID 参数。同时这一模式在 Dagger SDK 中具有一致性——ContainerID、DirectoryID等所有对象 ID 类型都采用相同的品牌化字符串策略统一基础类型见 client.gen.ts 的ID定义。4. 生成代码勿手改EngineCacheEntryID与上述所有类均由 Dagger 的代码生成器从 GraphQL Schema 自动产出SDK 生成结果集中在 sdk/typescript/src/api/client.gen.ts。升级 Dagger 版本后该类型别名及其关联类的定义会自动更新业务代码只需基于稳定的id()/entries()等公开方法编写即可。总结EngineCacheEntryID看似只是一个string object的类型别名背后却串起了完整的一条链GraphQLscalar EngineCacheEntryID→ Go 端 core/engine.go 的EngineCacheEntry结构 → TypeScript SDK 中 EngineCacheEntry.id() 返回的类型。理解它就等于掌握了 Dagger 引擎缓存条目以 ID 为句柄、惰性查询、按需取字段的访问模型也为后续使用entrySet/prune做缓存观测与治理打下了基础。【免费下载链接】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），仅供参考
