尧图网页设计 
Dagger TypeScript SDK 错误体系解析FunctionNotFound 错误类的定义、触发场景与降级机制【免费下载链接】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 中的FunctionNotFound错误类结合官方 API 文档与 SDK 源码系统讲解该错误的类定义、构造参数、属性与方法、底层实现以及它在 Dagger 模块执行器与入口调用链中的真实触发场景和注册表降级机制。读完本文你将掌握如何识别、捕获并程序化处理 Dagger 模块运行期的函数/对象未找到错误并能理解整个 DaggerSDKError 错误码体系D100D110的设计脉络。一、文档定位一个位于错误体系顶层的 API 引用页在 Dagger 的版本化文档中FunctionNotFound.md 是 TypeScript SDKcommon/errors模块的类参考页之一它与DaggerSDKError、ExecError、GraphQLRequestError、UnknownDaggerError等十余个错误类共同构成了 SDK 的错误类型目录完整清单见 common/errors 索引。该页面给出的核心 API 签名如下class FunctionNotFound extends DaggerSDKError { // 构造器 new FunctionNotFound(message: string, options?: DaggerSDKErrorOptions): FunctionNotFound // 属性 code: D109 ERROR_CODES.ExecError name: ExecError ERROR_NAMES.ExecError message: string cause?: Error stack?: string // 方法 printStackTrace(): void }从类名即可看出FunctionNotFound表达的是函数未找到这一语义——当 Dagger 在解析或调用某个模块对象及其方法时无法找到对应实现就会抛出该错误。下面逐项拆解这个类。二、继承关系与构造器FunctionNotFound直接继承自DaggerSDKError详见 DaggerSDKError 类文档。在 SDK 源码中这层关系由 FunctionNotFound.ts 体现import { DaggerSDKError, DaggerSDKErrorOptions } from ./DaggerSDKError.js import { ERROR_CODES, ERROR_NAMES } from ./errors-codes.js export class FunctionNotFound extends DaggerSDKError { name ERROR_NAMES.ExecError code ERROR_CODES.ExecError constructor(message: string, options?: DaggerSDKErrorOptions) { super(message, options) } }构造参数参数类型必填说明messagestring是错误描述信息由抛出方填充例如Object foo not foundoptions?DaggerSDKErrorOptions否可选配置目前仅支持cause字段用于携带导致本次错误的原始ErrorDaggerSDKErrorOptions定义在 DaggerSDKError.tsexport interface DaggerSDKErrorOptions { cause?: Error }构造函数内部直接调用基类构造函数super(message, options)基类会执行super(message)并读取options?.cause赋值给实例的cause属性。关于文档首行描述的一个细节该参考页首行写着 The base error. Every other error inherits this error.基类错误其他错误均继承自它。从源码结构看这句话实际与 DaggerSDKError.ts 中基类的 JSDoc 注释完全一致属于 TypeDoc 自动生成文档时沿用的基类描述。真实情况是DaggerSDKError才是整个错误体系的基础类FunctionNotFound只是它的一个具体子类。阅读文档时留意这一点可以避免对继承层级产生误解。三、属性详解3.1 name 与 code被复用的错误标识这是FunctionNotFound最值得注意的实现细节它的name和code并不是专属值而是直接复用了ExecError的常量name ERROR_NAMES.ExecError // 实际值 ExecError code ERROR_CODES.ExecError // 实际值 D109也就是说从错误码角度FunctionNotFound与ExecError共享D109与名称ExecError。这一点在 errors-codes.ts 中可以确认export const ERROR_CODES { GraphQLRequestError: D100, UnknownDaggerError: D101, TooManyNestedObjectsError: D102, EngineSessionConnectParamsParseError: D103, EngineSessionConnectionTimeoutError: D104, EngineSessionError: D105, InitEngineSessionBinaryError: D106, DockerImageRefValidationError: D107, NotAwaitedRequestError: D108, ExecError: D109, IntrospectionError: D110, } as const注意ERROR_CODES被声明为as const因此每个值都是字面量类型ERROR_NAMES则通过Object.keys(ERROR_CODES)反向生成保证名称与码表一一对应。这意味着你在代码中看到error.code D109时它既可能来自ExecError也可能来自FunctionNotFound——不要仅凭错误码区分这两类错误建议配合instanceof判断具体类型。3.2 message 与 stackmessage: string继承自Error保存构造时传入的错误描述。stack?: string标准 V8 堆栈信息同样继承自基类。可选属性的语义与原生Error.stack一致仅在 V8 生成堆栈后可用。3.3 cause?: Errorcause是DaggerSDKError体系引入的原始错误承载字段/** * The original error, which caused the DaggerSDKError. */ cause?: Error它用于错误链error chaining当 SDK 在捕获到某个底层错误后需要包装为 Dagger 语义错误时可将原始错误挂到cause上方便调试时追溯根因。FunctionNotFound自身并未重写该字段完全继承自基类因此它是可选的optional。四、方法printStackTrace()FunctionNotFound继承自基类的唯一公开方法printStackTrace(): void用于漂亮地打印错误堆栈。其实现位于 DaggerSDKError.tsprintStackTrace() { log(this.stack) }它调用 SDK 内部的log工具函数输出this.stack。该方法的可见性为公开TypeDoc 标记为hidden的Symbol.toStringTaggetter 除外便于在捕获错误后快速在控制台定位调用链。五、触发场景模块执行器中的三处抛错点FunctionNotFound的实际抛出位置集中在 executor.ts它承担着 Dagger TypeScript 模块运行期按名解析对象与方法并执行的核心职责抛错点方法消息模板触发条件第一处getExportedObjectObject ${object} not found在当前已加载的所有Module中找不到导出对象第二处buildClassObject ${object} not found in the module在模块的 introspection 对象表中找不到该对象定义第三处getResultMethod ${method} not found对象存在但实例上不存在要调用的方法对应源码摘录// executor.ts - getExportedObject const module this.modules.find((m) m[key] ! undefined) if (!module) { throw new FunctionNotFound(Object ${object} not found) } // executor.ts - buildClass const daggerObject this.daggerModule.objects[object] if (!daggerObject) { throw new FunctionNotFound(Object ${object} not found in the module) } // executor.ts - getResult const builtObj this.buildClass(object, state) if (!builtObj[method]) { throw new FunctionNotFound(Method ${method} not found) }从源码结构可以推断出典型触发场景当外部调用方通过 GraphQL 请求一个不存在的 Dagger 对象例如dag.getFoo()或请求对象上并不存在的方法例如对某个object()装饰的类调用未用func()暴露的方法时执行器就会以FunctionNotFound中断调用。这是模块 API 与实现不匹配时的第一道防线。六、关键机制invoke 入口的注册表降级FunctionNotFound并非只用于直接失败它还在 invoke.ts 中扮演了降级切换的触发信号角色。入口函数invoke在调用executor.getResult时包裹了 try/catchtry { result await executor.getResult(object.name, method.name, parentState, args) } catch (e) { // If the function isnt found because its // not exported, we try to get the result from the registry. if (e instanceof FunctionNotFound) { result await registry.getResult(object.name, method.name, parentState, args) } else { throw e } }其逻辑可归纳为优先尝试从模块的导出对象executor持有的Module[]中解析并调用函数若抛出FunctionNotFound说明该函数未通过模块导出则转而查询registryregistry.tsregistry是由object()装饰器注册的类与方法的仓储结构内部以 map 作为数据结构以优化查找性能见 registry.ts 中的RegistryClass定义只有instanceof FunctionNotFound才会触发降级其他错误一律原样上抛——这保证了降级路径的精确性。换句话说FunctionNotFound在 Dagger 模块运行模型中承担双轨解析的哨兵职责导出解析失败时它作为可预期信号驱动注册表回退避免模块中大量通过装饰器注册但未显式导出的函数无法被调用。这也是该错误类与ExecError共享错误码却仍有独立类名的现实意义——运行时依赖instanceof而非code做分支判断。七、实战如何识别与处理 FunctionNotFound7.1 程序化识别文档明确说明code的用途是 Use this to identify dagger errors programmatically用错误码在程序中识别 Dagger 错误。结合上文推荐的识别姿势是instanceof优先import { FunctionNotFound, ExecError } from dagger.io/dagger/common/errors try { const result await someModuleFunction() } catch (e) { if (e instanceof FunctionNotFound) { // 对象或方法未找到可提示调用方检查 API 名称 console.error(module resolution failed: ${e.message}) e.printStackTrace() } else if (e instanceof ExecError) { // 真正的执行期错误注意两者 code 均为 D109 console.error(exec error: ${e.message}, { cause: e.cause }) } else { throw e } }如果需要跨版本兼容或无法直接import具体类可退而使用错误码if ((e as DaggerSDKError).code D109)。但要牢记 §3.1 的结论——D109同时属于ExecError与FunctionNotFound仅凭码无法区分两者。7.2 调试建议查看message三种模板Object xxx not found、Object xxx not found in the module、Method xxx not found直接指示是对象级还是方法级解析失败调用printStackTrace()输出完整调用链检查cause若错误由其他底层异常包装而来cause中保存原始Error若出现导出解析失败但注册表降级也未命中的情况请核对模块是否用object()/func()正确装饰类与方法相关装饰器语义见 registry.ts 中的FunctionOptions其中alias可用于为函数设置对外暴露的别名cache可控制函数的缓存策略。八、在错误体系中的位置FunctionNotFound属于 common/errors 目录 下 12 个错误类之一整个体系的骨架是Error └─ DaggerSDKError (抽象基类含 name / code / cause / printStackTrace) ├─ FunctionNotFound (code D109与 ExecError 共用) ├─ ExecError (code D109) ├─ GraphQLRequestError (code D100) ├─ UnknownDaggerError (code D101) ├─ TooManyNestedObjectsError (code D102) ├─ EngineSessionConnectParamsParseError (code D103) ├─ EngineSessionConnectionTimeoutError (code D104) ├─ EngineSessionError (code D105) ├─ InitEngineSessionBinaryError (code D106) ├─ DockerImageRefValidationError (code D107) ├─ NotAwaitedRequestError (code D108) └─ IntrospectionError (code D110)所有错误类的名称与错误码统一定义在 errors-codes.ts由as const保证类型安全ERROR_NAMES由码表键名自动推导。理解这张表你就掌握了整个 Dagger TypeScript SDK 错误信号的字母表——D100至D110覆盖了从 GraphQL 请求、引擎会话建立、镜像引用校验、执行错误到模块内省失败的各类故障域而FunctionNotFound正是其中负责模块函数解析一环的关键成员。参考文件索引类 API 文档FunctionNotFound.md错误模块索引common/errors/README.md类实现FunctionNotFound.ts基类实现DaggerSDKError.ts错误码表errors-codes.ts抛错点executor.ts注册表降级invoke.ts注册表实现registry.ts【免费下载链接】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 错误体系解析：FunctionNotFound 错误类的定义、触发场景与降级机制
Dagger TypeScript SDK 错误体系解析FunctionNotFound 错误类的定义、触发场景与降级机制【免费下载链接】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 中的FunctionNotFound错误类结合官方 API 文档与 SDK 源码系统讲解该错误的类定义、构造参数、属性与方法、底层实现以及它在 Dagger 模块执行器与入口调用链中的真实触发场景和注册表降级机制。读完本文你将掌握如何识别、捕获并程序化处理 Dagger 模块运行期的函数/对象未找到错误并能理解整个 DaggerSDKError 错误码体系D100D110的设计脉络。一、文档定位一个位于错误体系顶层的 API 引用页在 Dagger 的版本化文档中FunctionNotFound.md 是 TypeScript SDKcommon/errors模块的类参考页之一它与DaggerSDKError、ExecError、GraphQLRequestError、UnknownDaggerError等十余个错误类共同构成了 SDK 的错误类型目录完整清单见 common/errors 索引。该页面给出的核心 API 签名如下class FunctionNotFound extends DaggerSDKError { // 构造器 new FunctionNotFound(message: string, options?: DaggerSDKErrorOptions): FunctionNotFound // 属性 code: D109 ERROR_CODES.ExecError name: ExecError ERROR_NAMES.ExecError message: string cause?: Error stack?: string // 方法 printStackTrace(): void }从类名即可看出FunctionNotFound表达的是函数未找到这一语义——当 Dagger 在解析或调用某个模块对象及其方法时无法找到对应实现就会抛出该错误。下面逐项拆解这个类。二、继承关系与构造器FunctionNotFound直接继承自DaggerSDKError详见 DaggerSDKError 类文档。在 SDK 源码中这层关系由 FunctionNotFound.ts 体现import { DaggerSDKError, DaggerSDKErrorOptions } from ./DaggerSDKError.js import { ERROR_CODES, ERROR_NAMES } from ./errors-codes.js export class FunctionNotFound extends DaggerSDKError { name ERROR_NAMES.ExecError code ERROR_CODES.ExecError constructor(message: string, options?: DaggerSDKErrorOptions) { super(message, options) } }构造参数参数类型必填说明messagestring是错误描述信息由抛出方填充例如Object foo not foundoptions?DaggerSDKErrorOptions否可选配置目前仅支持cause字段用于携带导致本次错误的原始ErrorDaggerSDKErrorOptions定义在 DaggerSDKError.tsexport interface DaggerSDKErrorOptions { cause?: Error }构造函数内部直接调用基类构造函数super(message, options)基类会执行super(message)并读取options?.cause赋值给实例的cause属性。关于文档首行描述的一个细节该参考页首行写着 The base error. Every other error inherits this error.基类错误其他错误均继承自它。从源码结构看这句话实际与 DaggerSDKError.ts 中基类的 JSDoc 注释完全一致属于 TypeDoc 自动生成文档时沿用的基类描述。真实情况是DaggerSDKError才是整个错误体系的基础类FunctionNotFound只是它的一个具体子类。阅读文档时留意这一点可以避免对继承层级产生误解。三、属性详解3.1 name 与 code被复用的错误标识这是FunctionNotFound最值得注意的实现细节它的name和code并不是专属值而是直接复用了ExecError的常量name ERROR_NAMES.ExecError // 实际值 ExecError code ERROR_CODES.ExecError // 实际值 D109也就是说从错误码角度FunctionNotFound与ExecError共享D109与名称ExecError。这一点在 errors-codes.ts 中可以确认export const ERROR_CODES { GraphQLRequestError: D100, UnknownDaggerError: D101, TooManyNestedObjectsError: D102, EngineSessionConnectParamsParseError: D103, EngineSessionConnectionTimeoutError: D104, EngineSessionError: D105, InitEngineSessionBinaryError: D106, DockerImageRefValidationError: D107, NotAwaitedRequestError: D108, ExecError: D109, IntrospectionError: D110, } as const注意ERROR_CODES被声明为as const因此每个值都是字面量类型ERROR_NAMES则通过Object.keys(ERROR_CODES)反向生成保证名称与码表一一对应。这意味着你在代码中看到error.code D109时它既可能来自ExecError也可能来自FunctionNotFound——不要仅凭错误码区分这两类错误建议配合instanceof判断具体类型。3.2 message 与 stackmessage: string继承自Error保存构造时传入的错误描述。stack?: string标准 V8 堆栈信息同样继承自基类。可选属性的语义与原生Error.stack一致仅在 V8 生成堆栈后可用。3.3 cause?: Errorcause是DaggerSDKError体系引入的原始错误承载字段/** * The original error, which caused the DaggerSDKError. */ cause?: Error它用于错误链error chaining当 SDK 在捕获到某个底层错误后需要包装为 Dagger 语义错误时可将原始错误挂到cause上方便调试时追溯根因。FunctionNotFound自身并未重写该字段完全继承自基类因此它是可选的optional。四、方法printStackTrace()FunctionNotFound继承自基类的唯一公开方法printStackTrace(): void用于漂亮地打印错误堆栈。其实现位于 DaggerSDKError.tsprintStackTrace() { log(this.stack) }它调用 SDK 内部的log工具函数输出this.stack。该方法的可见性为公开TypeDoc 标记为hidden的Symbol.toStringTaggetter 除外便于在捕获错误后快速在控制台定位调用链。五、触发场景模块执行器中的三处抛错点FunctionNotFound的实际抛出位置集中在 executor.ts它承担着 Dagger TypeScript 模块运行期按名解析对象与方法并执行的核心职责抛错点方法消息模板触发条件第一处getExportedObjectObject ${object} not found在当前已加载的所有Module中找不到导出对象第二处buildClassObject ${object} not found in the module在模块的 introspection 对象表中找不到该对象定义第三处getResultMethod ${method} not found对象存在但实例上不存在要调用的方法对应源码摘录// executor.ts - getExportedObject const module this.modules.find((m) m[key] ! undefined) if (!module) { throw new FunctionNotFound(Object ${object} not found) } // executor.ts - buildClass const daggerObject this.daggerModule.objects[object] if (!daggerObject) { throw new FunctionNotFound(Object ${object} not found in the module) } // executor.ts - getResult const builtObj this.buildClass(object, state) if (!builtObj[method]) { throw new FunctionNotFound(Method ${method} not found) }从源码结构可以推断出典型触发场景当外部调用方通过 GraphQL 请求一个不存在的 Dagger 对象例如dag.getFoo()或请求对象上并不存在的方法例如对某个object()装饰的类调用未用func()暴露的方法时执行器就会以FunctionNotFound中断调用。这是模块 API 与实现不匹配时的第一道防线。六、关键机制invoke 入口的注册表降级FunctionNotFound并非只用于直接失败它还在 invoke.ts 中扮演了降级切换的触发信号角色。入口函数invoke在调用executor.getResult时包裹了 try/catchtry { result await executor.getResult(object.name, method.name, parentState, args) } catch (e) { // If the function isnt found because its // not exported, we try to get the result from the registry. if (e instanceof FunctionNotFound) { result await registry.getResult(object.name, method.name, parentState, args) } else { throw e } }其逻辑可归纳为优先尝试从模块的导出对象executor持有的Module[]中解析并调用函数若抛出FunctionNotFound说明该函数未通过模块导出则转而查询registryregistry.tsregistry是由object()装饰器注册的类与方法的仓储结构内部以 map 作为数据结构以优化查找性能见 registry.ts 中的RegistryClass定义只有instanceof FunctionNotFound才会触发降级其他错误一律原样上抛——这保证了降级路径的精确性。换句话说FunctionNotFound在 Dagger 模块运行模型中承担双轨解析的哨兵职责导出解析失败时它作为可预期信号驱动注册表回退避免模块中大量通过装饰器注册但未显式导出的函数无法被调用。这也是该错误类与ExecError共享错误码却仍有独立类名的现实意义——运行时依赖instanceof而非code做分支判断。七、实战如何识别与处理 FunctionNotFound7.1 程序化识别文档明确说明code的用途是 Use this to identify dagger errors programmatically用错误码在程序中识别 Dagger 错误。结合上文推荐的识别姿势是instanceof优先import { FunctionNotFound, ExecError } from dagger.io/dagger/common/errors try { const result await someModuleFunction() } catch (e) { if (e instanceof FunctionNotFound) { // 对象或方法未找到可提示调用方检查 API 名称 console.error(module resolution failed: ${e.message}) e.printStackTrace() } else if (e instanceof ExecError) { // 真正的执行期错误注意两者 code 均为 D109 console.error(exec error: ${e.message}, { cause: e.cause }) } else { throw e } }如果需要跨版本兼容或无法直接import具体类可退而使用错误码if ((e as DaggerSDKError).code D109)。但要牢记 §3.1 的结论——D109同时属于ExecError与FunctionNotFound仅凭码无法区分两者。7.2 调试建议查看message三种模板Object xxx not found、Object xxx not found in the module、Method xxx not found直接指示是对象级还是方法级解析失败调用printStackTrace()输出完整调用链检查cause若错误由其他底层异常包装而来cause中保存原始Error若出现导出解析失败但注册表降级也未命中的情况请核对模块是否用object()/func()正确装饰类与方法相关装饰器语义见 registry.ts 中的FunctionOptions其中alias可用于为函数设置对外暴露的别名cache可控制函数的缓存策略。八、在错误体系中的位置FunctionNotFound属于 common/errors 目录 下 12 个错误类之一整个体系的骨架是Error └─ DaggerSDKError (抽象基类含 name / code / cause / printStackTrace) ├─ FunctionNotFound (code D109与 ExecError 共用) ├─ ExecError (code D109) ├─ GraphQLRequestError (code D100) ├─ UnknownDaggerError (code D101) ├─ TooManyNestedObjectsError (code D102) ├─ EngineSessionConnectParamsParseError (code D103) ├─ EngineSessionConnectionTimeoutError (code D104) ├─ EngineSessionError (code D105) ├─ InitEngineSessionBinaryError (code D106) ├─ DockerImageRefValidationError (code D107) ├─ NotAwaitedRequestError (code D108) └─ IntrospectionError (code D110)所有错误类的名称与错误码统一定义在 errors-codes.ts由as const保证类型安全ERROR_NAMES由码表键名自动推导。理解这张表你就掌握了整个 Dagger TypeScript SDK 错误信号的字母表——D100至D110覆盖了从 GraphQL 请求、引擎会话建立、镜像引用校验、执行错误到模块内省失败的各类故障域而FunctionNotFound正是其中负责模块函数解析一环的关键成员。参考文件索引类 API 文档FunctionNotFound.md错误模块索引common/errors/README.md类实现FunctionNotFound.ts基类实现DaggerSDKError.ts错误码表errors-codes.ts抛错点executor.ts注册表降级invoke.ts注册表实现registry.ts【免费下载链接】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），仅供参考