Dagger ModuleSourceExperimentalFeature 枚举解析SELF_CALLS 实验特性与模块自调用机制【免费下载链接】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.20 TypeScript SDK 参考文档中的ModuleSourceExperimentalFeature枚举位于 docs/versioned_docs/version-0.20/reference/typescript/api/client.gen/enumerations/ModuleSourceExperimentalFeature.md展开剖析该枚举的唯一成员SELF_CALLS在模块Module体系中的语义、TypeScript 端的调用方式、dagger.json中的配置方法以及它在 Dagger 引擎中的底层实现原理。读完本文你将掌握如何为一个模块源码ModuleSource开启实验特性、理解模块自调用Self Calls的能力边界并能从源码层面解释该特性对模块类型安装与命名空间解析的影响。枚举概览模块的实验特性在 Dagger 的 TypeScript 客户端生成代码中ModuleSourceExperimentalFeature是一个字符串枚举String Enum用于描述一个模块可以开启的实验性功能。其完整定义位于 sdk/typescript/src/api/client.gen.ts/** * Experimental features of a module */ export enum ModuleSourceExperimentalFeature { /** * Self calls */ SelfCalls SELF_CALLS, }从源码结构看该枚举由代码生成器从 GraphQL schema 自动产出与引擎侧的核心类型定义一一对应。引擎端在 core/modulesource.go 中通过dagql枚举机制注册了同名类型type ModuleSourceExperimentalFeature string var ModuleSourceExperimentalFeatures dagql.NewEnum[ModuleSourceExperimentalFeature]() var ModuleSourceExperimentalFeatureSelfCalls ModuleSourceExperimentalFeatures.Register(SELF_CALLS, Self calls)值得注意的事实当前版本该枚举只有SelfCalls一个成员值为字符串字面量SELF_CALLS。它的存在表明 Dagger 保留了通过枚举 特性开关机制扩展模块能力的通道——未来新增实验特性时只需在此枚举中追加成员而无需改动模块配置的整体结构。枚举成员详解SelfCalls枚举成员SelfCalls的底层值为SELF_CALLS官方文档描述为Self calls自调用。结合引擎源码这一特性的核心含义是允许模块在自身运行时 schema 中解析并调用自己定义的类型与根字段root fields即模块可以调用自己。这一理解可以从 core/sdk/dang/v2/sdk.go 的注释得到印证When self-calls are enabled the modules own types (and root fields liketuiQa) only exist in theruntimeschema, after this ModuleTypes pass has installed them... full inference would try to resolve self-referencing bodies against the deps schema, which does not yet carry the modules own API.也就是说未开启该特性时模块自身的类型在类型推断inference阶段不会被解析到开启后模块自己的类型会以命名空间namespace形式安装进运行时 schema从而支持模块内部自引用、自调用。TypeScript SDK 中的使用方式1. 枚举值转换工具函数client.gen.ts为这个枚举配套生成了两个双向转换工具函数便于在模块运行时与 GraphQL API 之间传递枚举值// 枚举值 - 字符串名称用于调用暴露函数时传参 export function ModuleSourceExperimentalFeatureValueToName( value: ModuleSourceExperimentalFeature, ): string { switch (value) { case ModuleSourceExperimentalFeature.SelfCalls: return SELF_CALLS default: return value } } // 字符串名称 - 枚举值用于模块运行时内部使用 export function ModuleSourceExperimentalFeatureNameToValue( name: string, ): ModuleSourceExperimentalFeature { switch (name) { case SELF_CALLS: return ModuleSourceExperimentalFeature.SelfCalls default: return name as ModuleSourceExperimentalFeature } }两个函数定义于 sdk/typescript/src/api/client.gen.ts。其中ValueToName面向向 GraphQL 暴露函数传参的场景NameToValue面向模块运行时内部解析配置的场景。当传入未注册的值时两者都采用原样透传策略default分支直接返回value或name as ...这为未来枚举扩展保留了兼容性。2. 通过 withExperimentalFeatures 开启特性枚举的实际使用入口是ModuleSource上的withExperimentalFeatures方法它接受一个ModuleSourceExperimentalFeature[]数组返回一个新的ModuleSource/** * Enable the experimental features for the module source. * param features The experimental features to enable. */ withExperimentalFeatures ( features: ModuleSourceExperimentalFeature[], ): ModuleSource { const ctx this._ctx.select(withExperimentalFeatures, { features }) return new ModuleSource(ctx) }方法定义于 sdk/typescript/src/api/client.gen.ts是ModuleSource构建器builder风格的 API 之一。典型调用链如下import { ModuleSourceExperimentalFeature, connect, } from dagger.io/dagger // 假设 source 是一个已加载的模块源码 const upgraded source.withExperimentalFeatures([ ModuleSourceExperimentalFeature.SelfCalls, ])由于withExperimentalFeatures返回新的ModuleSource它可以与其他构建器方法如withName、withSDK、withDependencies等自由链式组合这与ModuleSource整体不可变构建器的设计风格保持一致。dagger.json 中的配置方式除了通过 SDK 编程式开启实验特性也体现在模块的dagger.json配置文件中位于sdk.experimental字段。仓库的集成测试样例 core/integration/testdata/modules/dang/self-calls/dagger.json 给出了完整可参考的配置{ name: test, engineVersion: v0.21.9, sdk: { source: dang, experimental: { SELF_CALLS: true } } }关键点说明sdk.experimental是一个 map键为枚举成员名如SELF_CALLS值为布尔开关。引擎读取该 map 时按枚举字符串匹配见下文ExperimentalFeatureEnabled的实现。source指定 SDK示例中使用的是内置 Dang SDK。不过从引擎实现看该配置字段对所有 SDK 的模块配置结构通用。engineVersion该样例为集成测试固定了引擎版本v0.21.9与当前文档对应的 0.20 参考版本身处同一条演进线的邻近版本实际使用时该字段由dagger develop/dagger mod等命令管理。引擎底层实现原理1. 特性开关的存储与查询SDKConfig结构体在 core/modulesource.go 中定义并实现了实验特性的存储与查询type SDKConfig struct { Source string field:true ... Debug bool field:true ... Config map[string]any Experimental map[string]bool } func (sdk *SDKConfig) ExperimentalFeatureEnabled(feature ModuleSourceExperimentalFeature) bool { if sdk.Experimental nil { return false } return sdk.Experimental[feature.String()] }Experimental字段即对应dagger.json中的sdk.experimentalmap查询时以枚举的字符串值如SELF_CALLS为键进行布尔查找。若 map 未初始化或未配置对应键一律返回false默认关闭。2. SelfCallsEnabled 的统一判定入口引擎刻意没有让所有调用点直接检查枚举标志而是收敛到ModuleSource.SelfCallsEnabled()这一统一入口core/modulesource.gotype selfCallsAlwaysEnabler interface { AlwaysEnablesSelfCalls() bool } func (src *ModuleSource) SelfCallsEnabled() bool { if src.SDK ! nil src.SDK.ExperimentalFeatureEnabled(ModuleSourceExperimentalFeatureSelfCalls) { return true } if sc, ok : src.SDKImpl.(selfCallsAlwaysEnabler); ok sc.AlwaysEnablesSelfCalls() { return true } return false }这带来两条启用路径显式开启模块在dagger.json中配置SELF_CALLS: true或通过withExperimentalFeatures开启SDK 强制启用实现selfCallsAlwaysEnabler接口的 SDK如解释型 Dang SDK它需要按名称对照运行时 schema 解析自己的类型无条件启用自调用能力无需用户配置。该注释明确指出之所以要统一入口是为了避免两条路径不一致——一旦不一致会导致模块自身类型既被安装、又被当作重复类型拒绝即安装与校验逻辑自相矛盾。3. 对模块类型安装的影响自调用能力直接影响用户模块userMod的类型安装流程。在 core/module.go 的install中for _, def : range self.ObjectDefs { objDef : def.Self().AsObject.Value.Self() modType, ok, err : self.Deps.ModTypeFor(ctx, def.Self()) if err ! nil { ... } if ok { if src : self.GetSource(); src ! nil src.SelfCallsEnabled() { slog.ExtraDebug(type is already defined by dependency module, ...) } else { return fmt.Errorf(type %q is already defined by module %q, objDef.Name, modType.SourceMod().Name()) } } ... }即当一个类型名同时存在于依赖模块和当前模块时只有开启SELF_CALLS的模块才能容忍这种重名并继续安装通过命名空间区分否则直接报错type ... is already defined by module ...。这正是模块可以拥有自己的类型副本并自调用的引擎级保证。4. Dang SDK 的强制启用与声明式运行器Dang SDK 在 core/sdk/dang/v2/sdk.go 中通过SelfCallsEnabled()决定采用哪种求值运行器开启时改用runDangDirForModuleTypes声明式运行器因为模块自身的类型只存在于运行时的 schema 中此时完整的类型推断会失败关闭时则使用完整推断运行器。同时 core/sdk/dang/v2/helpers.go 中的schemaTypeName也依赖该特性当类型名不在依赖 schema 中时将其按NamespaceObject(name, module.name, module.originalName)命名空间化后解析这一过程要求模块自身类型已通过SELF_CALLS安装进运行时 schema。5. GraphQL 层暴露与测试验证GraphQL 暴露ModuleSource.selfCallsEnabled在 schema 层通过src.Self().SelfCallsEnabled()暴露见 core/schema/modulesource.go客户端 SDK如 TypeScript 的withExperimentalFeatures即映射到该 API 族。测试验证core/modulesource_test.go 中通过require.True(t, src.SelfCallsEnabled())与decodedSrc.SelfCallsEnabled()分别验证了编程式配置与配置反序列化两条路径都能正确启用该特性。使用场景、注意事项与限制典型使用场景编写需要引用自身定义类型例如自递归类型、基于自身 schema 做代码生成的模块的模块时需要开启SELF_CALLS使用解释型 Dang SDK 的模块在依赖自身类型解析时也需要该能力该 SDK 默认强制启用。注意事项与限制实验特性API 可能变动枚举名与文档描述均明确标注 Experimental其行为、配置字段甚至成员本身都可能在后续版本中调整生产使用前应关注版本演进engineVersion需要与引擎匹配。默认关闭除强制启用的 SDK 外特性开关默认false未开启时模块类型与依赖类型重名会直接导致安装报错。命名空间化是配套机制开启自调用后模块自身类型以NamespaceObject形式命名空间化安装理解这一点有助于排查类型重复定义类错误。枚举值透传策略TypeScript 端ValueToName/NameToValue对未知值采用原样透传传入拼写错误的特性名不会被立即发现配置时务必使用枚举常量而非字符串字面量。总结ModuleSourceExperimentalFeature是 Dagger 模块系统中实验特性开关的枚举载体当前唯一成员SelfCalls SELF_CALLS控制着模块的自调用能力。从 TypeScript 端的枚举与withExperimentalFeatures构建器 API到dagger.json中sdk.experimental配置再到引擎端ExperimentalFeatureEnabled/SelfCallsEnabled的双路径判定与类型安装豁免逻辑整条链路在仓库中完整可查。理解这一枚举是掌握 Dagger 模块类型系统与自引用机制的关键一步。【免费下载链接】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 ModuleSourceExperimentalFeature 枚举解析：SELF_CALLS 实验特性与模块自调用机制
Dagger ModuleSourceExperimentalFeature 枚举解析SELF_CALLS 实验特性与模块自调用机制【免费下载链接】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.20 TypeScript SDK 参考文档中的ModuleSourceExperimentalFeature枚举位于 docs/versioned_docs/version-0.20/reference/typescript/api/client.gen/enumerations/ModuleSourceExperimentalFeature.md展开剖析该枚举的唯一成员SELF_CALLS在模块Module体系中的语义、TypeScript 端的调用方式、dagger.json中的配置方法以及它在 Dagger 引擎中的底层实现原理。读完本文你将掌握如何为一个模块源码ModuleSource开启实验特性、理解模块自调用Self Calls的能力边界并能从源码层面解释该特性对模块类型安装与命名空间解析的影响。枚举概览模块的实验特性在 Dagger 的 TypeScript 客户端生成代码中ModuleSourceExperimentalFeature是一个字符串枚举String Enum用于描述一个模块可以开启的实验性功能。其完整定义位于 sdk/typescript/src/api/client.gen.ts/** * Experimental features of a module */ export enum ModuleSourceExperimentalFeature { /** * Self calls */ SelfCalls SELF_CALLS, }从源码结构看该枚举由代码生成器从 GraphQL schema 自动产出与引擎侧的核心类型定义一一对应。引擎端在 core/modulesource.go 中通过dagql枚举机制注册了同名类型type ModuleSourceExperimentalFeature string var ModuleSourceExperimentalFeatures dagql.NewEnum[ModuleSourceExperimentalFeature]() var ModuleSourceExperimentalFeatureSelfCalls ModuleSourceExperimentalFeatures.Register(SELF_CALLS, Self calls)值得注意的事实当前版本该枚举只有SelfCalls一个成员值为字符串字面量SELF_CALLS。它的存在表明 Dagger 保留了通过枚举 特性开关机制扩展模块能力的通道——未来新增实验特性时只需在此枚举中追加成员而无需改动模块配置的整体结构。枚举成员详解SelfCalls枚举成员SelfCalls的底层值为SELF_CALLS官方文档描述为Self calls自调用。结合引擎源码这一特性的核心含义是允许模块在自身运行时 schema 中解析并调用自己定义的类型与根字段root fields即模块可以调用自己。这一理解可以从 core/sdk/dang/v2/sdk.go 的注释得到印证When self-calls are enabled the modules own types (and root fields liketuiQa) only exist in theruntimeschema, after this ModuleTypes pass has installed them... full inference would try to resolve self-referencing bodies against the deps schema, which does not yet carry the modules own API.也就是说未开启该特性时模块自身的类型在类型推断inference阶段不会被解析到开启后模块自己的类型会以命名空间namespace形式安装进运行时 schema从而支持模块内部自引用、自调用。TypeScript SDK 中的使用方式1. 枚举值转换工具函数client.gen.ts为这个枚举配套生成了两个双向转换工具函数便于在模块运行时与 GraphQL API 之间传递枚举值// 枚举值 - 字符串名称用于调用暴露函数时传参 export function ModuleSourceExperimentalFeatureValueToName( value: ModuleSourceExperimentalFeature, ): string { switch (value) { case ModuleSourceExperimentalFeature.SelfCalls: return SELF_CALLS default: return value } } // 字符串名称 - 枚举值用于模块运行时内部使用 export function ModuleSourceExperimentalFeatureNameToValue( name: string, ): ModuleSourceExperimentalFeature { switch (name) { case SELF_CALLS: return ModuleSourceExperimentalFeature.SelfCalls default: return name as ModuleSourceExperimentalFeature } }两个函数定义于 sdk/typescript/src/api/client.gen.ts。其中ValueToName面向向 GraphQL 暴露函数传参的场景NameToValue面向模块运行时内部解析配置的场景。当传入未注册的值时两者都采用原样透传策略default分支直接返回value或name as ...这为未来枚举扩展保留了兼容性。2. 通过 withExperimentalFeatures 开启特性枚举的实际使用入口是ModuleSource上的withExperimentalFeatures方法它接受一个ModuleSourceExperimentalFeature[]数组返回一个新的ModuleSource/** * Enable the experimental features for the module source. * param features The experimental features to enable. */ withExperimentalFeatures ( features: ModuleSourceExperimentalFeature[], ): ModuleSource { const ctx this._ctx.select(withExperimentalFeatures, { features }) return new ModuleSource(ctx) }方法定义于 sdk/typescript/src/api/client.gen.ts是ModuleSource构建器builder风格的 API 之一。典型调用链如下import { ModuleSourceExperimentalFeature, connect, } from dagger.io/dagger // 假设 source 是一个已加载的模块源码 const upgraded source.withExperimentalFeatures([ ModuleSourceExperimentalFeature.SelfCalls, ])由于withExperimentalFeatures返回新的ModuleSource它可以与其他构建器方法如withName、withSDK、withDependencies等自由链式组合这与ModuleSource整体不可变构建器的设计风格保持一致。dagger.json 中的配置方式除了通过 SDK 编程式开启实验特性也体现在模块的dagger.json配置文件中位于sdk.experimental字段。仓库的集成测试样例 core/integration/testdata/modules/dang/self-calls/dagger.json 给出了完整可参考的配置{ name: test, engineVersion: v0.21.9, sdk: { source: dang, experimental: { SELF_CALLS: true } } }关键点说明sdk.experimental是一个 map键为枚举成员名如SELF_CALLS值为布尔开关。引擎读取该 map 时按枚举字符串匹配见下文ExperimentalFeatureEnabled的实现。source指定 SDK示例中使用的是内置 Dang SDK。不过从引擎实现看该配置字段对所有 SDK 的模块配置结构通用。engineVersion该样例为集成测试固定了引擎版本v0.21.9与当前文档对应的 0.20 参考版本身处同一条演进线的邻近版本实际使用时该字段由dagger develop/dagger mod等命令管理。引擎底层实现原理1. 特性开关的存储与查询SDKConfig结构体在 core/modulesource.go 中定义并实现了实验特性的存储与查询type SDKConfig struct { Source string field:true ... Debug bool field:true ... Config map[string]any Experimental map[string]bool } func (sdk *SDKConfig) ExperimentalFeatureEnabled(feature ModuleSourceExperimentalFeature) bool { if sdk.Experimental nil { return false } return sdk.Experimental[feature.String()] }Experimental字段即对应dagger.json中的sdk.experimentalmap查询时以枚举的字符串值如SELF_CALLS为键进行布尔查找。若 map 未初始化或未配置对应键一律返回false默认关闭。2. SelfCallsEnabled 的统一判定入口引擎刻意没有让所有调用点直接检查枚举标志而是收敛到ModuleSource.SelfCallsEnabled()这一统一入口core/modulesource.gotype selfCallsAlwaysEnabler interface { AlwaysEnablesSelfCalls() bool } func (src *ModuleSource) SelfCallsEnabled() bool { if src.SDK ! nil src.SDK.ExperimentalFeatureEnabled(ModuleSourceExperimentalFeatureSelfCalls) { return true } if sc, ok : src.SDKImpl.(selfCallsAlwaysEnabler); ok sc.AlwaysEnablesSelfCalls() { return true } return false }这带来两条启用路径显式开启模块在dagger.json中配置SELF_CALLS: true或通过withExperimentalFeatures开启SDK 强制启用实现selfCallsAlwaysEnabler接口的 SDK如解释型 Dang SDK它需要按名称对照运行时 schema 解析自己的类型无条件启用自调用能力无需用户配置。该注释明确指出之所以要统一入口是为了避免两条路径不一致——一旦不一致会导致模块自身类型既被安装、又被当作重复类型拒绝即安装与校验逻辑自相矛盾。3. 对模块类型安装的影响自调用能力直接影响用户模块userMod的类型安装流程。在 core/module.go 的install中for _, def : range self.ObjectDefs { objDef : def.Self().AsObject.Value.Self() modType, ok, err : self.Deps.ModTypeFor(ctx, def.Self()) if err ! nil { ... } if ok { if src : self.GetSource(); src ! nil src.SelfCallsEnabled() { slog.ExtraDebug(type is already defined by dependency module, ...) } else { return fmt.Errorf(type %q is already defined by module %q, objDef.Name, modType.SourceMod().Name()) } } ... }即当一个类型名同时存在于依赖模块和当前模块时只有开启SELF_CALLS的模块才能容忍这种重名并继续安装通过命名空间区分否则直接报错type ... is already defined by module ...。这正是模块可以拥有自己的类型副本并自调用的引擎级保证。4. Dang SDK 的强制启用与声明式运行器Dang SDK 在 core/sdk/dang/v2/sdk.go 中通过SelfCallsEnabled()决定采用哪种求值运行器开启时改用runDangDirForModuleTypes声明式运行器因为模块自身的类型只存在于运行时的 schema 中此时完整的类型推断会失败关闭时则使用完整推断运行器。同时 core/sdk/dang/v2/helpers.go 中的schemaTypeName也依赖该特性当类型名不在依赖 schema 中时将其按NamespaceObject(name, module.name, module.originalName)命名空间化后解析这一过程要求模块自身类型已通过SELF_CALLS安装进运行时 schema。5. GraphQL 层暴露与测试验证GraphQL 暴露ModuleSource.selfCallsEnabled在 schema 层通过src.Self().SelfCallsEnabled()暴露见 core/schema/modulesource.go客户端 SDK如 TypeScript 的withExperimentalFeatures即映射到该 API 族。测试验证core/modulesource_test.go 中通过require.True(t, src.SelfCallsEnabled())与decodedSrc.SelfCallsEnabled()分别验证了编程式配置与配置反序列化两条路径都能正确启用该特性。使用场景、注意事项与限制典型使用场景编写需要引用自身定义类型例如自递归类型、基于自身 schema 做代码生成的模块的模块时需要开启SELF_CALLS使用解释型 Dang SDK 的模块在依赖自身类型解析时也需要该能力该 SDK 默认强制启用。注意事项与限制实验特性API 可能变动枚举名与文档描述均明确标注 Experimental其行为、配置字段甚至成员本身都可能在后续版本中调整生产使用前应关注版本演进engineVersion需要与引擎匹配。默认关闭除强制启用的 SDK 外特性开关默认false未开启时模块类型与依赖类型重名会直接导致安装报错。命名空间化是配套机制开启自调用后模块自身类型以NamespaceObject形式命名空间化安装理解这一点有助于排查类型重复定义类错误。枚举值透传策略TypeScript 端ValueToName/NameToValue对未知值采用原样透传传入拼写错误的特性名不会被立即发现配置时务必使用枚举常量而非字符串字面量。总结ModuleSourceExperimentalFeature是 Dagger 模块系统中实验特性开关的枚举载体当前唯一成员SelfCalls SELF_CALLS控制着模块的自调用能力。从 TypeScript 端的枚举与withExperimentalFeatures构建器 API到dagger.json中sdk.experimental配置再到引擎端ExperimentalFeatureEnabled/SelfCallsEnabled的双路径判定与类型安装豁免逻辑整条链路在仓库中完整可查。理解这一枚举是掌握 Dagger 模块类型系统与自引用机制的关键一步。【免费下载链接】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），仅供参考