Dagger TypeScript SDK 中 DirectoryAsModuleSourceOpts 类型详解sourceRootPath 与模块源码加载【免费下载链接】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导读DirectoryAsModuleSourceOpts是 Dagger TypeScript SDK 中用于将目录加载为 Dagger 模块源码ModuleSource的选项类型。本文以 DirectoryAsModuleSourceOpts.md 为骨架结合 SDK 生成代码client.gen.ts、GraphQL 核心 schemaschema.graphqls与引擎端实现modulesource.go展开帮助读者理解sourceRootPath的作用、默认行为、底层解析链路及真实测试用例从而在构建模块、加载子目录模块等场景中正确使用该选项。类型定义一个仅含单个可选属性的对象DirectoryAsModuleSourceOpts是一个 TypeScript 对象类型别名type alias仅定义了一个可选属性属性类型可选性说明sourceRootPathstringoptional目录中存放模块配置文件的可选子路径未设置时模块源码从目录根加载其对应的 SDK 生成源码位于 sdk/typescript/src/api/client.gen.ts#L1127-L1134export type DirectoryAsModuleSourceOpts { /** * An optional subpath of the directory which contains the modules configuration file. * * If not set, the module source code is loaded from the root of the directory. */ sourceRootPath?: string }从源码结构看该类型与同文件中的DirectoryAsModuleOptsclient.gen.ts#L1118-L1125保持完全一致的字段形态区别在于asModuleSource()返回的是ModuleSource对象而asModule()返回的是加载完成的Module_对象。使用入口Directory.asModuleSource()DirectoryAsModuleSourceOpts被用作Directory类实例方法asModuleSource()的唯一入参其方法签名及 JSDoc 注释位于 client.gen.ts#L6148-L6157/** * Load the directory as a Dagger module source * param opts.sourceRootPath An optional subpath of the directory which contains the modules configuration file. * * If not set, the module source code is loaded from the root of the directory. */ asModuleSource (opts?: DirectoryAsModuleSourceOpts): ModuleSource { const ctx this._ctx.select(asModuleSource, { ...opts }) return new ModuleSource(ctx) }调用时SDK 会把opts原样作为 GraphQL 查询参数传给后端asModuleSource字段this._ctx.select(asModuleSource, { ...opts })返回的ModuleSource对象可用于后续模块构建操作如AsModule()、GeneratedContextChangeset()等。如果不需要指定子路径可以直接调用asModuleSource()而省略参数。底层语义sourceRootPath 决定模块配置文件的查找位置sourceRootPath的核心语义在文档中已明确它指向目录中存放模块配置文件dagger.json的子路径如果不设置模块源码默认从目录根加载。GraphQL schema 层的默认值在核心 GraphQL schema 中asModuleSource字段的sourceRootPath参数带有默认值.见 docs/docs-graphql/schema.graphqls#L1848-L1860asModuleSource( # An optional subpath of the directory which contains the modules configuration file. # If not set, the module source code is loaded from the root of the directory. sourceRootPath: String . ): ModuleSource!也就是说无论 SDK 端是否传参引擎端都会获得一个有效值显式传入的路径或默认的.目录根。引擎端的参数处理引擎端对参数的解析逻辑位于 core/schema/modulesource.go#L869-L928type directoryAsModuleSourceArgs struct { SourceRootPath string default:. ... } func (s *moduleSourceSchema) directoryAsModuleSource( ctx context.Context, contextDir dagql.ObjectResult[*core.Directory], args directoryAsModuleSourceArgs, ) (inst dagql.Result[*core.ModuleSource], err error) { sourceRootSubpath : args.SourceRootPath if sourceRootSubpath { sourceRootSubpath . } ... configFilename, found, err : moduleConfigInDir( ctx, core.DirectoryStatFS{Dir: contextDir}, filepath.Join(/, dirSrc.SourceRootSubpath), ) if err ! nil { return inst, fmt.Errorf(failed to find dir module config: %w, err) } if !found { if !args.AllowNotExists { return inst, fmt.Errorf(dir module source does not contain a dagger config file) } dirSrc.ConfigExists false return dagql.NewResultForCurrentCall(ctx, dirSrc) } ... }从该实现可以确认以下几点空字符串兜底即使显式传入空字符串也会被规整为.与文档所述“未设置则从根加载”一致配置文件定位引擎会在/sourceRootPath目录下查找模块配置文件modules.Filename即dagger.json而不是在整个目录中递归搜索错误行为如果指定路径下不存在 dagger 配置文件会返回错误dir module source does not contain a dagger config file除非AllowNotExists内部标志默认false被启用上下文目录保持SourceRootSubpath与原始ContextDirectory都被记录在DirModuleSource结构中OriginalContextDir、OriginalSourceRootSubpath便于后续加载模块时回溯原始上下文。asModule()方法在引擎端正是通过将sourceRootPath转发给asModuleSource字段再调用asModule完成加载的见 modulesource.go#L881-L903这也解释了为什么两个选项类型字段完全一致。典型用法加载子目录中的模块sourceRootPath最常见的用途是在一个较大的上下文目录中定位位于子目录的模块。例如下面的 GraphQL 查询来自集成测试 core/integration/module_typescript_test.go#L1003{ host { directory(path: .){ asModule(sourceRootPath: ./sub){ id } } } }在 TypeScript SDK 中等价于import { connect } from dagger.io/dagger connect(async (client) { const moduleSource client.host() .directory(.) .asModuleSource({ sourceRootPath: sub }) const module moduleSource.asModule() // ... })这样模块配置dagger.json位于./sub/dagger.json时可以仅用子路径而非复制目录来定位模块源码。官方集成测试中的实证引擎仓库的集成测试 core/integration/module_config_test.go#L989-L1001 给出了完整的 TypeScript/Go 语义等价用例验证了sourceRootPath在“目录中存在模块与非模块文件混合”场景下的行为src : c.Directory(). WithNewFile(outside.txt, keep me). WithNewFile(mod/dagger.json, {name:foo,engineVersion:v1.0.0,sdk:{source:dang}}). WithNewFile(mod/main.dang, type Foo {\n pub hello: String! {\n \hi\\n }\n}\n). AsModuleSource(dagger.DirectoryAsModuleSourceOpts{SourceRootPath: mod}) removed, err : src.GeneratedContextChangeset().RemovedPaths(ctx) require.NoError(t, err) require.NotContains(t, removed, outside.txt)该测试说明当sourceRootPath: mod指向含dagger.json的子目录时mod之外的文件如outside.txt不会被当作模块变更的一部分模块代码生成codegen的变更集只作用于模块目录内部。这也印证了文档中“子路径包含模块配置文件”的表述在实际构建管线中的影响。与其他加载方式的关联DirectoryAsModuleSourceOpts仅是 Dagger 模块源码加载体系中的一个入口。仓库中还存在与之对应的DirectoryAsModuleOpts直接加载为Module、asWorkspace创建合成工作区client.gen.ts#L6159-L6166以及面向 Git 仓库的gitModuleSource与面向本地路径的localModuleSource均见 core/schema/modulesource.go。它们共享同一套“SourceRootSubpath ContextDirectory → 查找 dagger 配置文件 → loadConfiguredModuleSource”的加载流程sourceRootPath的语义在这些入口中保持一致。在 Dagger 0.19 及之后的版本中Workspacedagger.toml体系还通过 core/schema/workspace_module.go#L144-L154 在内部复用asModuleSourcesourceRootPath来校验“路径是否为已初始化模块”若指定路径下没有模块配置asModuleSource会直接报错从而充当模块初始化检查。注意事项sourceRootPath指向的是模块配置文件的所在目录而不是配置文件本身不需要写mod/dagger.json写mod即可路径使用相对目录的路径形式传.、空字符串或不传均可表示目录根该路径下必须存在模块配置文件dagger.json否则加载会失败并返回错误从代码生成方式看DirectoryAsModuleSourceOpts与其他 SDK 生成的DirectoryAsModuleSourceOpts定义一致如 Go SDK 中的dagger.DirectoryAsModuleSourceOpts在 TypeScript、Go、Python、Java 等 SDK 间迁移使用成本很低。参考实现路径类型定义与 JSDocsdk/typescript/src/api/client.gen.ts#L1127-L1134asModuleSource()方法sdk/typescript/src/api/client.gen.ts#L6148-L6157GraphQL schema 字段定义docs/docs-graphql/schema.graphqls#L1848-L1860引擎端实现core/schema/modulesource.go#L869-L952集成测试用例core/integration/module_config_test.go#L989-L1001【免费下载链接】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 中 DirectoryAsModuleSourceOpts 类型详解：sourceRootPath 与模块源码加载
Dagger TypeScript SDK 中 DirectoryAsModuleSourceOpts 类型详解sourceRootPath 与模块源码加载【免费下载链接】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导读DirectoryAsModuleSourceOpts是 Dagger TypeScript SDK 中用于将目录加载为 Dagger 模块源码ModuleSource的选项类型。本文以 DirectoryAsModuleSourceOpts.md 为骨架结合 SDK 生成代码client.gen.ts、GraphQL 核心 schemaschema.graphqls与引擎端实现modulesource.go展开帮助读者理解sourceRootPath的作用、默认行为、底层解析链路及真实测试用例从而在构建模块、加载子目录模块等场景中正确使用该选项。类型定义一个仅含单个可选属性的对象DirectoryAsModuleSourceOpts是一个 TypeScript 对象类型别名type alias仅定义了一个可选属性属性类型可选性说明sourceRootPathstringoptional目录中存放模块配置文件的可选子路径未设置时模块源码从目录根加载其对应的 SDK 生成源码位于 sdk/typescript/src/api/client.gen.ts#L1127-L1134export type DirectoryAsModuleSourceOpts { /** * An optional subpath of the directory which contains the modules configuration file. * * If not set, the module source code is loaded from the root of the directory. */ sourceRootPath?: string }从源码结构看该类型与同文件中的DirectoryAsModuleOptsclient.gen.ts#L1118-L1125保持完全一致的字段形态区别在于asModuleSource()返回的是ModuleSource对象而asModule()返回的是加载完成的Module_对象。使用入口Directory.asModuleSource()DirectoryAsModuleSourceOpts被用作Directory类实例方法asModuleSource()的唯一入参其方法签名及 JSDoc 注释位于 client.gen.ts#L6148-L6157/** * Load the directory as a Dagger module source * param opts.sourceRootPath An optional subpath of the directory which contains the modules configuration file. * * If not set, the module source code is loaded from the root of the directory. */ asModuleSource (opts?: DirectoryAsModuleSourceOpts): ModuleSource { const ctx this._ctx.select(asModuleSource, { ...opts }) return new ModuleSource(ctx) }调用时SDK 会把opts原样作为 GraphQL 查询参数传给后端asModuleSource字段this._ctx.select(asModuleSource, { ...opts })返回的ModuleSource对象可用于后续模块构建操作如AsModule()、GeneratedContextChangeset()等。如果不需要指定子路径可以直接调用asModuleSource()而省略参数。底层语义sourceRootPath 决定模块配置文件的查找位置sourceRootPath的核心语义在文档中已明确它指向目录中存放模块配置文件dagger.json的子路径如果不设置模块源码默认从目录根加载。GraphQL schema 层的默认值在核心 GraphQL schema 中asModuleSource字段的sourceRootPath参数带有默认值.见 docs/docs-graphql/schema.graphqls#L1848-L1860asModuleSource( # An optional subpath of the directory which contains the modules configuration file. # If not set, the module source code is loaded from the root of the directory. sourceRootPath: String . ): ModuleSource!也就是说无论 SDK 端是否传参引擎端都会获得一个有效值显式传入的路径或默认的.目录根。引擎端的参数处理引擎端对参数的解析逻辑位于 core/schema/modulesource.go#L869-L928type directoryAsModuleSourceArgs struct { SourceRootPath string default:. ... } func (s *moduleSourceSchema) directoryAsModuleSource( ctx context.Context, contextDir dagql.ObjectResult[*core.Directory], args directoryAsModuleSourceArgs, ) (inst dagql.Result[*core.ModuleSource], err error) { sourceRootSubpath : args.SourceRootPath if sourceRootSubpath { sourceRootSubpath . } ... configFilename, found, err : moduleConfigInDir( ctx, core.DirectoryStatFS{Dir: contextDir}, filepath.Join(/, dirSrc.SourceRootSubpath), ) if err ! nil { return inst, fmt.Errorf(failed to find dir module config: %w, err) } if !found { if !args.AllowNotExists { return inst, fmt.Errorf(dir module source does not contain a dagger config file) } dirSrc.ConfigExists false return dagql.NewResultForCurrentCall(ctx, dirSrc) } ... }从该实现可以确认以下几点空字符串兜底即使显式传入空字符串也会被规整为.与文档所述“未设置则从根加载”一致配置文件定位引擎会在/sourceRootPath目录下查找模块配置文件modules.Filename即dagger.json而不是在整个目录中递归搜索错误行为如果指定路径下不存在 dagger 配置文件会返回错误dir module source does not contain a dagger config file除非AllowNotExists内部标志默认false被启用上下文目录保持SourceRootSubpath与原始ContextDirectory都被记录在DirModuleSource结构中OriginalContextDir、OriginalSourceRootSubpath便于后续加载模块时回溯原始上下文。asModule()方法在引擎端正是通过将sourceRootPath转发给asModuleSource字段再调用asModule完成加载的见 modulesource.go#L881-L903这也解释了为什么两个选项类型字段完全一致。典型用法加载子目录中的模块sourceRootPath最常见的用途是在一个较大的上下文目录中定位位于子目录的模块。例如下面的 GraphQL 查询来自集成测试 core/integration/module_typescript_test.go#L1003{ host { directory(path: .){ asModule(sourceRootPath: ./sub){ id } } } }在 TypeScript SDK 中等价于import { connect } from dagger.io/dagger connect(async (client) { const moduleSource client.host() .directory(.) .asModuleSource({ sourceRootPath: sub }) const module moduleSource.asModule() // ... })这样模块配置dagger.json位于./sub/dagger.json时可以仅用子路径而非复制目录来定位模块源码。官方集成测试中的实证引擎仓库的集成测试 core/integration/module_config_test.go#L989-L1001 给出了完整的 TypeScript/Go 语义等价用例验证了sourceRootPath在“目录中存在模块与非模块文件混合”场景下的行为src : c.Directory(). WithNewFile(outside.txt, keep me). WithNewFile(mod/dagger.json, {name:foo,engineVersion:v1.0.0,sdk:{source:dang}}). WithNewFile(mod/main.dang, type Foo {\n pub hello: String! {\n \hi\\n }\n}\n). AsModuleSource(dagger.DirectoryAsModuleSourceOpts{SourceRootPath: mod}) removed, err : src.GeneratedContextChangeset().RemovedPaths(ctx) require.NoError(t, err) require.NotContains(t, removed, outside.txt)该测试说明当sourceRootPath: mod指向含dagger.json的子目录时mod之外的文件如outside.txt不会被当作模块变更的一部分模块代码生成codegen的变更集只作用于模块目录内部。这也印证了文档中“子路径包含模块配置文件”的表述在实际构建管线中的影响。与其他加载方式的关联DirectoryAsModuleSourceOpts仅是 Dagger 模块源码加载体系中的一个入口。仓库中还存在与之对应的DirectoryAsModuleOpts直接加载为Module、asWorkspace创建合成工作区client.gen.ts#L6159-L6166以及面向 Git 仓库的gitModuleSource与面向本地路径的localModuleSource均见 core/schema/modulesource.go。它们共享同一套“SourceRootSubpath ContextDirectory → 查找 dagger 配置文件 → loadConfiguredModuleSource”的加载流程sourceRootPath的语义在这些入口中保持一致。在 Dagger 0.19 及之后的版本中Workspacedagger.toml体系还通过 core/schema/workspace_module.go#L144-L154 在内部复用asModuleSourcesourceRootPath来校验“路径是否为已初始化模块”若指定路径下没有模块配置asModuleSource会直接报错从而充当模块初始化检查。注意事项sourceRootPath指向的是模块配置文件的所在目录而不是配置文件本身不需要写mod/dagger.json写mod即可路径使用相对目录的路径形式传.、空字符串或不传均可表示目录根该路径下必须存在模块配置文件dagger.json否则加载会失败并返回错误从代码生成方式看DirectoryAsModuleSourceOpts与其他 SDK 生成的DirectoryAsModuleSourceOpts定义一致如 Go SDK 中的dagger.DirectoryAsModuleSourceOpts在 TypeScript、Go、Python、Java 等 SDK 间迁移使用成本很低。参考实现路径类型定义与 JSDocsdk/typescript/src/api/client.gen.ts#L1127-L1134asModuleSource()方法sdk/typescript/src/api/client.gen.ts#L6148-L6157GraphQL schema 字段定义docs/docs-graphql/schema.graphqls#L1848-L1860引擎端实现core/schema/modulesource.go#L869-L952集成测试用例core/integration/module_config_test.go#L989-L1001【免费下载链接】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），仅供参考