Dagger TypeScript SDK ErrorID 类型详解Error 对象唯一标识符的语义、持久化与加载【免费下载链接】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本文以 version-0.19 TypeScript API 参考文档 为主线剖析dagger.io/dagger中ErrorID这一类型别名的精确定义、其在 Dagger 类型系统中的定位并结合 core/schema/error.go 与 core/error.go 的源码讲清一个Error对象的 ID 是如何产生、持久化并重新加载的。读完本文你将理解 Dagger 全量 ID 体系的设计思路并能在 TypeScript 代码中正确创建错误、获取其 ID、通过 ID 反向加载错误对象。一、ErrorID 是什么在 Dagger 的 GraphQL API 中几乎所有可持久化的对象类型都配套一个对应的 ID 标量Error对象也不例外。根据 ErrorID.md 的定义ErrorID标量类型表示 Error 类型对象的一个标识符TheErrorIDscalar type represents an identifier for an object of type Error。也就是说ErrorID是某个具体Error对象的唯一引用。在 Dagger 的语义中ID 是对象的稳定句柄拿到 ID即可通过引擎在任意时刻重新加载出同一个对象而无需重新走一遍构造该对象的完整调用链。这是 Dagger 分布式、可缓存执行模型的核心基础——对象以 DAG 形式构建ID 则相当于给 DAG 中的每个节点颁发了一张身份证。类型别名定义ErrorID在文档中的完整声明为 **ErrorID** string object其 Type Declaration 只有一个成员### \_\_ErrorID **\_\_ErrorID**: never需要说明的是这一页是 SDK 的**类型别名Type Alias**参考文档。真正的底层类型定义位于 SDK 的运行时生成代码中在 sdk/typescript/runtime/internal/dagger/dagger.gen.go 中可以看到 Go 侧与之对应的声明// A unique identifier for an object. type ErrorID string从声明形式可以推断文档中的string object是 TypeScript 中典型的品牌化类型branded type写法ErrorID的值形态是一个字符串但通过与对象类型的交叉以及__ErrorID: never这个保留字段使其成为一个与普通string在类型层面互不兼容的独立类型从而避免在编译期把任意字符串误当作ErrorID使用。__ErrorID: never意味着该品牌字段永远不可能被真实赋值它只是类型系统中的一个标记。二、Error 对象在 Dagger 中的角色要理解ErrorID先要理解它标识的Error对象本身。在 Dagger 中Error不是 Go 或 TypeScript 语言层面的异常而是暴露在 GraphQL API 上、可被查询和持久化的核心对象类型。引擎侧的定义位于 core/error.gotype Error struct { Message string field:true doc:A description of the error. Values []*ErrorValue field:true doc:The extensions of the error. }Error携带两个字段Message错误的人类可读描述Values错误的扩展值列表ErrorValue由Name JSONValue组成用于携带结构化附加信息。对应的 GraphQL 解析器注册在 core/schema/error.go查询字段error(message)创建一个新的Error对象message参数为错误描述方法withValue(name, value)向已有错误追加一个扩展值。从这里可以看出Error是一个不可变、可组合的对象每次withValue都会基于克隆返回一个新的错误见 core/error.go 的WithValue实现这与 Dagger 全链式、惰性求值的 API 风格完全一致。而ErrorID正是用来唯一标识这种错误对象的句柄。三、ErrorID 是如何产生的Error.ID()在 TypeScript SDK 中任何Error客户端对象都可以调用ID()方法获取自己的标识符。生成代码位于 sdk/typescript/runtime/internal/dagger/dagger.gen.go// A unique identifier for this Error. func (r *Error) ID(ctx context.Context) (ID, error) { if r.id ! nil { return *r.id, nil } q : r.query.Select(id) var response ID q q.Bind(response) return response, q.Execute(ctx) }两个值得注意的实现细节惰性与缓存如果对象已经持有 ID 则直接返回否则才向引擎发起id字段的 GraphQL 查询。这说明ErrorID本质上是一个 GraphQL 标量值由引擎端计算并下发给客户端。序列化与反序列化Error对象实现了MarshalJSON/UnmarshalJSONdagger.gen.go——序列化时输出其 ID 字符串反序列化时则通过selectNode(dag.query, id, Error)仅凭 ID 重建一个指向该对象的客户端句柄。这正体现了ID 即对象引用的设计跨进程传递Error时实际传递的只是它的ErrorID。四、ID 的持久化从对象到标识符的编码ErrorID并非凭空产生其背后是 Dagger 的统一持久化框架dagql.PersistedObject。在 core/error.go 中var _ dagql.PersistedObject (*Error)(nil) var _ dagql.PersistedObjectDecoder (*Error)(nil)Error实现了两个关键接口EncodePersistedObjectcore/error.go将Error的完整状态Message、Values编码为 JSON 负载DecodePersistedObjectcore/error.go从 JSON 负载还原Error对象。从源码结构看ErrorID就是对这种编码负载的寻址方式引擎把对象编码后存入持久化存储并把地址封装为 ID 返回给调用方后续使用该 ID 时引擎解码负载、恢复对象从而保证同一 ID 始终指向同一对象状态。这也是loadErrorFromID这类查询能够成立的底层机制。另外可以注意到Error本身也实现了标准错误接口errorError() string返回Message见 core/error.go以及dagql.ExtendedError接口Extensions()把Values还原为扩展字段见 core/error.go。这意味着 Dagger 既能以普通错误的形式传播它也能以带扩展信息的结构化错误传播它——这两条路径最终都会生成可供标识的ErrorID。五、通过 ErrorID 加载对象LoadErrorFromID生成代码为每个持久化对象都提供了对应的加载入口。Error的加载方法定义在 sdk/typescript/runtime/internal/dagger/dagger.gen.go// Load a Error from its ID. func (r *Query) LoadErrorFromID(id ErrorID) *Error { q : r.query.Select(loadErrorFromID) q q.Arg(id, id) return Error{query: q} }对应的 API 文档见 Client 类文档 中的loadErrorFromID(id): Error。TypeScript 侧的典型用法如下import { connect } from dagger.io/dagger await connect(async (client) { // 1. 创建一个 Error 对象 const err client.error(build failed: missing dependency) // 2. 获取其 ErrorID const id await err.id() // 3. 仅凭 ID 重新加载该错误对象 const loaded client.loadErrorFromID(id) // 4. 读取 message 验证加载结果 console.log(await loaded.message()) // build failed: missing dependency })client.error()方法对应 Client 类文档 中error(message)的查询构造器其底层 GraphQL 实现就是上文提到的 core/schema/error.go 中的error解析器。六、ErrorID 与 ErrorValueID 的关系Error的扩展值字段Values中的每个元素同样是一个可持久化对象ErrorValue定义见 core/error.go因此它也拥有自己的 ID 类型ErrorValueID。两者声明完全同构——ErrorValueID.md 中同样是string object的形式ErrorValueIDstringobject表示 ErrorValue 类型对象的一个标识符。生成代码中ErrorValueID string紧邻ErrorID stringdagger.gen.go加载入口LoadErrorValueFromID也紧邻LoadErrorFromIDdagger.gen.go。从这些源码布局可以看出Dagger 的 ID 体系是一套完全统一、机械生成的机制每种持久化对象类型都获得同构的 ID 标量、ID()访问器、loadXxxFromID加载器。掌握ErrorID的语义就等于掌握了 Dagger 全部 ID 类型ContainerID、DirectoryID、FileID、CacheVolumeID等完整清单见 api/client.gen README的通用规律。七、使用限制与注意事项基于当前仓库内容使用ErrorID时需要注意以下几点版本前提本文所述类型声明对应 Dagger v0.19 的 TypeScript SDK API文档位于 docs/versioned_docs/version-0.19更高版本的类型定义可能发生变化请以对应版本文档为准。ID 的字符串形态ErrorID的值形态是字符串但由于品牌化类型设计它不能与普通string直接互用需要保持其原生类型以通过编译期检查。生成代码位置SDK 的底层生成代码位于 sdk/typescript/runtime/internal/dagger/dagger.gen.go属于运行时内部实现日常开发应直接使用dagger.io/dagger暴露的公开 API如client.error()、client.loadErrorFromID()。ID 的持久化依赖引擎loadErrorFromID能否成功恢复对象取决于引擎端对Error对象的持久化编码能力——这正是Error实现dagql.PersistedObject接口的原因core/error.go。小结ErrorID看似只是一个简单的类型别名但把它放在 Dagger 的架构中观察就能看到一条完整的链路GraphQL 标量声明 → TypeScript 品牌化类型 →Error.ID()惰性求值 →dagql.PersistedObjectJSON 持久化 →loadErrorFromID反向加载。理解这条链路不仅让你会使用ErrorID更能举一反三地掌握 Dagger 全部 ID 标量的设计哲学——对象即 DAG 节点ID 即节点的寻址句柄。相关参考类型别名文档ErrorID.md、ErrorValueID.md客户端方法文档Client.md引擎侧实现core/error.go、core/schema/error.goSDK 生成代码dagger.gen.go【免费下载链接】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），仅供参考 Dagger TypeScript SDK ErrorID 类型详解：Error 对象唯一标识符的语义、持久化与加载
Dagger TypeScript SDK ErrorID 类型详解Error 对象唯一标识符的语义、持久化与加载【免费下载链接】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本文以 version-0.19 TypeScript API 参考文档 为主线剖析dagger.io/dagger中ErrorID这一类型别名的精确定义、其在 Dagger 类型系统中的定位并结合 core/schema/error.go 与 core/error.go 的源码讲清一个Error对象的 ID 是如何产生、持久化并重新加载的。读完本文你将理解 Dagger 全量 ID 体系的设计思路并能在 TypeScript 代码中正确创建错误、获取其 ID、通过 ID 反向加载错误对象。一、ErrorID 是什么在 Dagger 的 GraphQL API 中几乎所有可持久化的对象类型都配套一个对应的 ID 标量Error对象也不例外。根据 ErrorID.md 的定义ErrorID标量类型表示 Error 类型对象的一个标识符TheErrorIDscalar type represents an identifier for an object of type Error。也就是说ErrorID是某个具体Error对象的唯一引用。在 Dagger 的语义中ID 是对象的稳定句柄拿到 ID即可通过引擎在任意时刻重新加载出同一个对象而无需重新走一遍构造该对象的完整调用链。这是 Dagger 分布式、可缓存执行模型的核心基础——对象以 DAG 形式构建ID 则相当于给 DAG 中的每个节点颁发了一张身份证。类型别名定义ErrorID在文档中的完整声明为 **ErrorID** string object其 Type Declaration 只有一个成员### \_\_ErrorID **\_\_ErrorID**: never需要说明的是这一页是 SDK 的**类型别名Type Alias**参考文档。真正的底层类型定义位于 SDK 的运行时生成代码中在 sdk/typescript/runtime/internal/dagger/dagger.gen.go 中可以看到 Go 侧与之对应的声明// A unique identifier for an object. type ErrorID string从声明形式可以推断文档中的string object是 TypeScript 中典型的品牌化类型branded type写法ErrorID的值形态是一个字符串但通过与对象类型的交叉以及__ErrorID: never这个保留字段使其成为一个与普通string在类型层面互不兼容的独立类型从而避免在编译期把任意字符串误当作ErrorID使用。__ErrorID: never意味着该品牌字段永远不可能被真实赋值它只是类型系统中的一个标记。二、Error 对象在 Dagger 中的角色要理解ErrorID先要理解它标识的Error对象本身。在 Dagger 中Error不是 Go 或 TypeScript 语言层面的异常而是暴露在 GraphQL API 上、可被查询和持久化的核心对象类型。引擎侧的定义位于 core/error.gotype Error struct { Message string field:true doc:A description of the error. Values []*ErrorValue field:true doc:The extensions of the error. }Error携带两个字段Message错误的人类可读描述Values错误的扩展值列表ErrorValue由Name JSONValue组成用于携带结构化附加信息。对应的 GraphQL 解析器注册在 core/schema/error.go查询字段error(message)创建一个新的Error对象message参数为错误描述方法withValue(name, value)向已有错误追加一个扩展值。从这里可以看出Error是一个不可变、可组合的对象每次withValue都会基于克隆返回一个新的错误见 core/error.go 的WithValue实现这与 Dagger 全链式、惰性求值的 API 风格完全一致。而ErrorID正是用来唯一标识这种错误对象的句柄。三、ErrorID 是如何产生的Error.ID()在 TypeScript SDK 中任何Error客户端对象都可以调用ID()方法获取自己的标识符。生成代码位于 sdk/typescript/runtime/internal/dagger/dagger.gen.go// A unique identifier for this Error. func (r *Error) ID(ctx context.Context) (ID, error) { if r.id ! nil { return *r.id, nil } q : r.query.Select(id) var response ID q q.Bind(response) return response, q.Execute(ctx) }两个值得注意的实现细节惰性与缓存如果对象已经持有 ID 则直接返回否则才向引擎发起id字段的 GraphQL 查询。这说明ErrorID本质上是一个 GraphQL 标量值由引擎端计算并下发给客户端。序列化与反序列化Error对象实现了MarshalJSON/UnmarshalJSONdagger.gen.go——序列化时输出其 ID 字符串反序列化时则通过selectNode(dag.query, id, Error)仅凭 ID 重建一个指向该对象的客户端句柄。这正体现了ID 即对象引用的设计跨进程传递Error时实际传递的只是它的ErrorID。四、ID 的持久化从对象到标识符的编码ErrorID并非凭空产生其背后是 Dagger 的统一持久化框架dagql.PersistedObject。在 core/error.go 中var _ dagql.PersistedObject (*Error)(nil) var _ dagql.PersistedObjectDecoder (*Error)(nil)Error实现了两个关键接口EncodePersistedObjectcore/error.go将Error的完整状态Message、Values编码为 JSON 负载DecodePersistedObjectcore/error.go从 JSON 负载还原Error对象。从源码结构看ErrorID就是对这种编码负载的寻址方式引擎把对象编码后存入持久化存储并把地址封装为 ID 返回给调用方后续使用该 ID 时引擎解码负载、恢复对象从而保证同一 ID 始终指向同一对象状态。这也是loadErrorFromID这类查询能够成立的底层机制。另外可以注意到Error本身也实现了标准错误接口errorError() string返回Message见 core/error.go以及dagql.ExtendedError接口Extensions()把Values还原为扩展字段见 core/error.go。这意味着 Dagger 既能以普通错误的形式传播它也能以带扩展信息的结构化错误传播它——这两条路径最终都会生成可供标识的ErrorID。五、通过 ErrorID 加载对象LoadErrorFromID生成代码为每个持久化对象都提供了对应的加载入口。Error的加载方法定义在 sdk/typescript/runtime/internal/dagger/dagger.gen.go// Load a Error from its ID. func (r *Query) LoadErrorFromID(id ErrorID) *Error { q : r.query.Select(loadErrorFromID) q q.Arg(id, id) return Error{query: q} }对应的 API 文档见 Client 类文档 中的loadErrorFromID(id): Error。TypeScript 侧的典型用法如下import { connect } from dagger.io/dagger await connect(async (client) { // 1. 创建一个 Error 对象 const err client.error(build failed: missing dependency) // 2. 获取其 ErrorID const id await err.id() // 3. 仅凭 ID 重新加载该错误对象 const loaded client.loadErrorFromID(id) // 4. 读取 message 验证加载结果 console.log(await loaded.message()) // build failed: missing dependency })client.error()方法对应 Client 类文档 中error(message)的查询构造器其底层 GraphQL 实现就是上文提到的 core/schema/error.go 中的error解析器。六、ErrorID 与 ErrorValueID 的关系Error的扩展值字段Values中的每个元素同样是一个可持久化对象ErrorValue定义见 core/error.go因此它也拥有自己的 ID 类型ErrorValueID。两者声明完全同构——ErrorValueID.md 中同样是string object的形式ErrorValueIDstringobject表示 ErrorValue 类型对象的一个标识符。生成代码中ErrorValueID string紧邻ErrorID stringdagger.gen.go加载入口LoadErrorValueFromID也紧邻LoadErrorFromIDdagger.gen.go。从这些源码布局可以看出Dagger 的 ID 体系是一套完全统一、机械生成的机制每种持久化对象类型都获得同构的 ID 标量、ID()访问器、loadXxxFromID加载器。掌握ErrorID的语义就等于掌握了 Dagger 全部 ID 类型ContainerID、DirectoryID、FileID、CacheVolumeID等完整清单见 api/client.gen README的通用规律。七、使用限制与注意事项基于当前仓库内容使用ErrorID时需要注意以下几点版本前提本文所述类型声明对应 Dagger v0.19 的 TypeScript SDK API文档位于 docs/versioned_docs/version-0.19更高版本的类型定义可能发生变化请以对应版本文档为准。ID 的字符串形态ErrorID的值形态是字符串但由于品牌化类型设计它不能与普通string直接互用需要保持其原生类型以通过编译期检查。生成代码位置SDK 的底层生成代码位于 sdk/typescript/runtime/internal/dagger/dagger.gen.go属于运行时内部实现日常开发应直接使用dagger.io/dagger暴露的公开 API如client.error()、client.loadErrorFromID()。ID 的持久化依赖引擎loadErrorFromID能否成功恢复对象取决于引擎端对Error对象的持久化编码能力——这正是Error实现dagql.PersistedObject接口的原因core/error.go。小结ErrorID看似只是一个简单的类型别名但把它放在 Dagger 的架构中观察就能看到一条完整的链路GraphQL 标量声明 → TypeScript 品牌化类型 →Error.ID()惰性求值 →dagql.PersistedObjectJSON 持久化 →loadErrorFromID反向加载。理解这条链路不仅让你会使用ErrorID更能举一反三地掌握 Dagger 全部 ID 标量的设计哲学——对象即 DAG 节点ID 即节点的寻址句柄。相关参考类型别名文档ErrorID.md、ErrorValueID.md客户端方法文档Client.md引擎侧实现core/error.go、core/schema/error.goSDK 生成代码dagger.gen.go【免费下载链接】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），仅供参考