Dagger TypeScript SDKCloud 类参考解析Dagger Cloud 配置与 Trace 链接【免费下载链接】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 0.19 版本 TypeScript SDK API 参考中Cloud类的深度解读。文章围绕该类的继承关系、构造函数签名与id()、traceURL()两个方法展开并结合仓库中的引擎侧 schema 实现core/schema/cloud.go与生成代码sdk/typescript/src/api/client.gen.ts帮助你在编写 Dagger TypeScript 模块时正确获取当前会话的 Cloud 追踪链接理解其取值规则、错误行为与缓存语义。概述Cloud 是 Dagger Cloud 的配置与状态入口Cloud类在 SDK 中的文档描述为Dagger Cloud configuration and stateDagger Cloud 的配置与状态它是Query根对象下cloud()方法返回的节点用于访问与 Dagger Cloud 服务相关的配置和运行时状态。从仓库的 TypeScript 生成代码看Query上暴露了如下访问入口见 client.gen.ts/** * Dagger Cloud configuration and state */ cloud (): Cloud { const ctx this._ctx.select(cloud) return new Cloud(ctx) }因此在 TypeScript 模块中的典型用法是dagger.cloud().traceURL()而不是直接new Cloud(...)。引擎侧对应实现在 core/schema/cloud.gocloud字段被安装为Query上的dagql.Func直接返回一个空的*core.Cloud对象它本身不携带业务字段真正的状态组织信息、Trace ID是在解析traceURL时从调用上下文动态提取的。继承关系extends BaseClient文档标注Cloud继承自BaseClient。BaseClient是所有生成节点类Container、Directory、Cloud等的公共基类负责持有 GraphQL 查询上下文Context并提供通用的执行能力。Cloud在此之上只增加了两个私有状态字段export class Cloud extends BaseClient { private readonly _id?: ID undefined private readonly _traceURL?: string undefined /** * Constructor is used for internal usage only, do not create object from it. */ constructor(ctx?: Context, _id?: ID, _traceURL?: string) { super(ctx) this._id _id this._traceURL _traceURL } // ... }见 client.gen.ts两个私有字段_id、_traceURL的作用是缓存memoize当 SDK 内部通过反序列化例如从服务端返回的 ID恢复一个Cloud对象时已知字段会预先注入调用方法时可以直接短路返回无需再向引擎发起查询。构造函数仅供内部使用文档给出的构造函数签名new Cloud(ctx?,_id?,_traceURL?):CloudConstructor is used for internal usage only, do not create object from it.参数类型说明ctx?Context内部查询上下文由 SDK 在构建查询树时传入_id?CloudID已知的 Cloud 节点 ID存在时id()直接返回不再查询_traceURL?string已知的 trace URL存在时traceURL()直接返回不再查询返回值Cloud新的 Cloud 实例文档明确提示不要直接使用该构造函数创建对象OverridesBaseClient.constructor。正确的获取方式是从Query根节点调用dagger.cloud()如上文所示。构造函数的三个可选参数全部服务于 SDK 内部的状态恢复路径。方法 id()获取 Cloud 节点的唯一标识id():PromiseCloudIDA unique identifier for this Cloud.CloudID是 SDK 的 ID 类型别名CloudID.md与其他 Dagger 资源ContainerID、FileID等一样属于全局节点 ID 体系。生成代码中的实现逻辑见 client.gen.tsid async (): PromiseID { if (this._id) { return this._id // 已缓存直接短路 } const ctx this._ctx.select(id) // 在查询树上追加选择 id 字段 const response: AwaitedID await ctx.execute() return response }其工作机制是先在本地查询树上追加id字段的选择然后执行整棵查询树并取回结果。由于Cloud在引擎侧是一个近乎无状态的“配置节点”id()主要用于 SDK 内部的状态引用与跨节点传递日常编写模块时很少直接使用。方法 traceURL()获取当前会话的 Trace 链接traceURL():PromisestringThe trace URL for the current session这是Cloud类对外最具实用价值的方法返回当前 DAG 执行会话在 Dagger Cloud 上的追踪Trace页面 URL便于在 CI 日志、模块输出中直接贴出可点击的执行详情链接。客户端实现同样是“先查缓存、再走查询”的模式见 client.gen.tstraceURL async (): Promisestring { if (this._traceURL) { return this._traceURL } const ctx this._ctx.select(traceURL) const response: Awaitedstring await ctx.execute() return response }引擎侧实现为什么 traceURL 每次都重新计算结合引擎侧源码core/schema/cloud.go可以确认traceURL的完整取值规则不做缓存字段注册时显式声明了DoNotCache(This value changes every single run)——即该字段每次运行都会变化因此引擎不会把它纳入结果缓存。依赖主调用方的 Cloud 组织信息解析器先取出当前查询再读取query.MainClientCallerMetadata(ctx)中的CloudOrg字段。未配置组织时返回错误若md.CloudOrg 解析直接失败错误信息为no cloud organization configured;dagger loginto configure your Dagger Cloud organization拼接规则从当前 OpenTelemetry 上下文中提取TraceID最终返回形如https://dagger.cloud/org/traces/traceID的 URLtid : trace.SpanContextFromContext(ctx).TraceID().String() return fmt.Sprintf(https://dagger.cloud/%s/traces/%s, md.CloudOrg, tid), nil由此可以推断出使用上的关键约束只有当你通过dagger login配置了 Dagger Cloud 组织且客户端将组织元数据传递给引擎时traceURL()才能成功在纯本地、未登录 Cloud 的环境中调用它会抛错模块代码应对该场景做容错。URL 中的 trace ID 来自当前请求的 OTel span 上下文所以“每次运行结果不同”是设计使然而不是缓存失效。核心类型定义引擎侧Cloud的 Go 类型定义非常轻量仅承载类型元信息core/cloud.gotype Cloud struct { } func (*Cloud) TypeDescription() string { return Dagger Cloud configuration and state }类型描述与 SDK 文档中的一致说明 SDK 的Cloud类文档正是由该核心定义驱动代码生成的。使用示例与注意事项在 TypeScript 模块dagger.ts中通过Client根对象访问import { dagger } from dagger.io/dagger async function main() { // dagger 即 Query 根对象cloud() 返回 Cloud 节点 try { const url await dagger.cloud().traceURL() console.log(Trace available at:, url) } catch (e) { // 未执行 dagger login 配置 Cloud 组织时会抛错 // no cloud organization configured; dagger login to configure your Dagger Cloud organization console.warn(Cloud trace unavailable:, e) } }使用要点小结要点说明获取方式通过dagger.cloud()获取不要new Cloud(...)前置条件需要已配置 Dagger Cloud 组织dagger login否则traceURL()报错缓存语义traceURL引擎侧声明DoNotCache每次运行重新计算_id/_traceURL预注入仅供 SDK 内部恢复对象状态时使用外部调用方不感知CloudID与其他资源一致的全局 ID 类型主要用于 SDK 内部引用参考文件本文依据的 API 文档Cloud.mdTypeScript SDK 生成代码client.gen.tsCloud类位于 L4330-L4376Query.cloud()位于 L13204-L13210引擎侧字段安装与解析cloud.go核心类型定义cloud.goCloudID类型别名文档CloudID.md【免费下载链接】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），仅供参考