Dagger TypeScript SDK 的 TypeDefWithInterfaceOpts 类型详解模块接口定义与源码定位【免费下载链接】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本篇技术指南聚焦 DaggerTypeScript SDK类型系统中的TypeDefWithInterfaceOpts类型别名——它是TypeDef.withInterface()方法用于创建 Dagger 模块接口Interface的可选参数对象。读完本文你将掌握该类型的两个可选属性description与sourceMap各自的作用与适用场景、底层 GraphQL 字段到 TypeScript/Go 客户端的映射关系以及如何在自定义 Dagger 模块中通过接口定义实现可扩展的类型抽象并借助SourceMap实现定义位置的精确定位与溯源。TypeDefWithInterfaceOpts 是什么TypeDefWithInterfaceOpts是 Dagger TypeScript SDK 中一个对象类型type alias它承载调用TypeDef.withInterface()时所需的全部可选参数。该类型定义于 SDK 自动生成的客户端代码中export type TypeDefWithInterfaceOpts { description?: string sourceMap?: SourceMap }对应文件sdk/typescript/src/api/client.gen.ts#L3210-L3213从类型结构看它只有两个可选属性?标记意味着构建接口时可以只传入name两个选项均可省略。这与 Dagger 类型系统中其他同类选项类型如TypeDefWithObjectOpts、TypeDefWithFieldOpts的结构保持一致——它们都共享description与sourceMap这两个通用选项。属性一览属性类型必填语义descriptionstring否接口的文档字符串doc string用于说明该接口的用途sourceMapSourceMap否接口定义在模块源码中的位置信息文件、行、列等用于溯源与调试description为接口书写文档description是一个可选的string用于为即将创建的接口提供人类可读的说明。在 GraphQL schema 层该参数有明确的默认值见 core/schema/testdata/base_schema.graphqls#L4794-L4795Returns a TypeDef of kind Interface with the provided name. withInterface(name: String!, description: String , sourceMap: ID expectedType(name: SourceMap)): TypeDef!从 schema 定义可以看到三个关键信息name是必填参数String!而description与sourceMap均为可选description默认值为空字符串sourceMap在 GraphQL 层以ID形式传递其实际类型为SourceMap。在 Dagger 引擎的服务端实现中该字段还会经历非空校验与默认值装配。见 core/schema/module.go#L1083-L1113func (s *moduleSchema) typeDefWithInterface(ctx context.Context, def *core.TypeDef, args struct { Name string Description string default: SourceMap dagql.Optional[core.SourceMapID] SourceModuleName dagql.Optional[dagql.String] internal:true }) (*core.TypeDef, error) { if args.Name { return nil, fmt.Errorf(interface type def must have a name) } // ... }这段源码印证了三点实现事实接口名不能为空否则返回interface type def must have a name错误Description使用default:标签与 GraphQL 层默认值一致接口最终通过__interfaceTypeDef内部字段构造为InterfaceTypeDef再挂载到当前TypeDef上。sourceMap接口定义的源码定位sourceMap是可选的SourceMap对象。SourceMap类在 SDK 中用于承载源码位置信息其可访问的字段包括字段类型含义idID该 SourceMap 的唯一标识符filenamestring模块源码中定义所在的文件名linenumber定义在文件内的行号columnnumber定义在该行内的列号modulestring声明该定义所在的模块依赖urlstring文件的可选 URL可用于在浏览器中打开源码位置这些字段的定义位于 sdk/typescript/src/api/client.gen.ts#L15204-L15320如filename的注释为The filename from the module source.url的注释说明其can be used to link to the source map in the browser。在 Dagger 模块的实践中sourceMap主要用于调试与排障当接口定义引发错误时可借助行/列/文件信息快速定位到模块源码中的具体声明位置工具链集成IDE 插件或代码生成器可以利用url将接口定义链接回浏览器端源码查看器模块溯源module字段标识定义来自哪个模块依赖在多模块工程中尤其有用。从 Go 运行时生成代码也能看到sourceMap作为可选参数的处理方式——只有非零值才会被追加到查询参数中见 sdk/typescript/runtime/internal/dagger/dagger.gen.go#L15216-L15239// TypeDefWithInterfaceOpts contains options for TypeDef.WithInterface type TypeDefWithInterfaceOpts struct { Description string SourceMap *SourceMap } func (r *TypeDef) WithInterface(name string, opts ...TypeDefWithInterfaceOpts) *TypeDef { q : r.query.Select(withInterface) for i : len(opts) - 1; i 0; i-- { if !querybuilder.IsZeroValue(opts[i].Description) { q q.Arg(description, opts[i].Description) } if !querybuilder.IsZeroValue(opts[i].SourceMap) { q q.Arg(sourceMap, opts[i].SourceMap) } } q q.Arg(name, name) // ... }这段代码清晰展示了 Go 版本中选项参数的逐字段零值判断逻辑同时也印证了 TypeScript 类型定义中两个属性均可选的设计——省略即不发送对应 GraphQL 参数。在 Dagger 模块中定义接口的完整用法TypeDefWithInterfaceOpts必须与TypeDef.withInterface()配合使用。在 TypeScript SDK 中该方法签名如下sdk/typescript/src/api/client.gen.ts#L15915-L15921/** * Returns a TypeDef of kind Interface with the provided name. */ withInterface (name: string, opts?: TypeDefWithInterfaceOpts): TypeDef { const ctx this._ctx.select(withInterface, { name, ...opts }) return new TypeDef(ctx) }使用方法非常直观第一个参数是接口名第二个可选参数即TypeDefWithInterfaceOpts。一个带完整选项的调用示例const myIface myTypeDef.withInterface(MyService, { description: MyService 是所有对外服务实现必须遵循的接口契约, sourceMap: dagger.sourceMap(modules/my-service/index.ts, 12, 3), })其中dagger.sourceMap(filename, line, column)用于构造一个SourceMap实例对应 SDK 中的工厂方法见 sdk/typescript/src/api/client.gen.ts#L14401-L14403。如果只需最简用法也可以完全省略选项const myIface myTypeDef.withInterface(MyService)接口与对象的分工在 Dagger 的类型模型中withInterface创建的TypeDef属于Interface类型TypeDefKind.Interface它与withObject创建的对象类型是两套不同的抽象接口Interface定义一组可被多个实现共享的方法签名与字段契约适合描述能力的约定对象Object具体的数据/能力实现可以withFunction挂载方法、withField挂载字段。两者的 GraphQL schema 并置可见于 core/schema/testdata/base_schema.graphqls#L4790-L4812其中withInterface的注释为Returns a TypeDef of kind Interface with the provided name.而withFunction明确指出Adds a function for an Object or Interface TypeDef, failing if the type is not one of those kinds.——即接口与对象都允许通过withFunction添加函数。与其他选项类型的关系TypeDefWithInterfaceOpts并不是孤立存在的。在 SDK 自动生成的代码中围绕TypeDef存在一整套成体系的选项类型sdk/typescript/src/api/client.gen.ts#L3180-L3223export type TypeDefWithFieldOpts { description?: string sourceMap?: SourceMap deprecated?: string } export type TypeDefWithInterfaceOpts { description?: string sourceMap?: SourceMap } export type TypeDefWithObjectOpts { description?: string sourceMap?: SourceMap deprecated?: string } export type TypeDefWithScalarOpts { description?: string }对比可见description与sourceMap是接口、对象、字段三类选项的公共基础deprecated只出现在字段与对象选项中——接口本身不支持弃用标记TypeDefWithScalarOpts最为精简仅保留description。这套命名规约TypeDefWithXxxOpts↔TypeDef.withXxx()贯穿整个 TypeDef API学习时可按方法名 Opts的规律快速定位任意类型定义的选项结构。源码映射小结为便于读者在仓库中继续深入将本文涉及的关键实现位置汇总如下内容仓库路径TypeScript 类型别名定义sdk/typescript/src/api/client.gen.ts#L3210-L3213TypeScriptwithInterface方法sdk/typescript/src/api/client.gen.ts#L15915-L15921TypeScriptSourceMap类sdk/typescript/src/api/client.gen.ts#L15204-L15320Go 运行时选项结构体与参数装配sdk/typescript/runtime/internal/dagger/dagger.gen.go#L15216-L15239GraphQL schema含默认值core/schema/testdata/base_schema.graphqls#L4794-L4795引擎侧服务端解析逻辑core/schema/module.go#L1083-L1113总结TypeDefWithInterfaceOpts虽是一个只有两个可选属性的轻量类型别名但它是 Dagger TypeScript SDK 中定义模块接口的统一入口参数description让接口具备自解释的文档能力sourceMap让接口定义可精确回溯到源码位置。理解它需要同时把握三条线索——TypeScript 层的类型形状、GraphQL schema 层的参数默认值以及引擎侧对接口名的非空校验。掌握了withInterface与这套Opts约定后你就能在自定义 Dagger 模块中灵活搭建接口契约并与对象、字段、函数等 TypeDef 构建方法组合出完整、可维护的类型体系。【免费下载链接】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 的 TypeDefWithInterfaceOpts 类型详解：模块接口定义与源码定位
Dagger TypeScript SDK 的 TypeDefWithInterfaceOpts 类型详解模块接口定义与源码定位【免费下载链接】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本篇技术指南聚焦 DaggerTypeScript SDK类型系统中的TypeDefWithInterfaceOpts类型别名——它是TypeDef.withInterface()方法用于创建 Dagger 模块接口Interface的可选参数对象。读完本文你将掌握该类型的两个可选属性description与sourceMap各自的作用与适用场景、底层 GraphQL 字段到 TypeScript/Go 客户端的映射关系以及如何在自定义 Dagger 模块中通过接口定义实现可扩展的类型抽象并借助SourceMap实现定义位置的精确定位与溯源。TypeDefWithInterfaceOpts 是什么TypeDefWithInterfaceOpts是 Dagger TypeScript SDK 中一个对象类型type alias它承载调用TypeDef.withInterface()时所需的全部可选参数。该类型定义于 SDK 自动生成的客户端代码中export type TypeDefWithInterfaceOpts { description?: string sourceMap?: SourceMap }对应文件sdk/typescript/src/api/client.gen.ts#L3210-L3213从类型结构看它只有两个可选属性?标记意味着构建接口时可以只传入name两个选项均可省略。这与 Dagger 类型系统中其他同类选项类型如TypeDefWithObjectOpts、TypeDefWithFieldOpts的结构保持一致——它们都共享description与sourceMap这两个通用选项。属性一览属性类型必填语义descriptionstring否接口的文档字符串doc string用于说明该接口的用途sourceMapSourceMap否接口定义在模块源码中的位置信息文件、行、列等用于溯源与调试description为接口书写文档description是一个可选的string用于为即将创建的接口提供人类可读的说明。在 GraphQL schema 层该参数有明确的默认值见 core/schema/testdata/base_schema.graphqls#L4794-L4795Returns a TypeDef of kind Interface with the provided name. withInterface(name: String!, description: String , sourceMap: ID expectedType(name: SourceMap)): TypeDef!从 schema 定义可以看到三个关键信息name是必填参数String!而description与sourceMap均为可选description默认值为空字符串sourceMap在 GraphQL 层以ID形式传递其实际类型为SourceMap。在 Dagger 引擎的服务端实现中该字段还会经历非空校验与默认值装配。见 core/schema/module.go#L1083-L1113func (s *moduleSchema) typeDefWithInterface(ctx context.Context, def *core.TypeDef, args struct { Name string Description string default: SourceMap dagql.Optional[core.SourceMapID] SourceModuleName dagql.Optional[dagql.String] internal:true }) (*core.TypeDef, error) { if args.Name { return nil, fmt.Errorf(interface type def must have a name) } // ... }这段源码印证了三点实现事实接口名不能为空否则返回interface type def must have a name错误Description使用default:标签与 GraphQL 层默认值一致接口最终通过__interfaceTypeDef内部字段构造为InterfaceTypeDef再挂载到当前TypeDef上。sourceMap接口定义的源码定位sourceMap是可选的SourceMap对象。SourceMap类在 SDK 中用于承载源码位置信息其可访问的字段包括字段类型含义idID该 SourceMap 的唯一标识符filenamestring模块源码中定义所在的文件名linenumber定义在文件内的行号columnnumber定义在该行内的列号modulestring声明该定义所在的模块依赖urlstring文件的可选 URL可用于在浏览器中打开源码位置这些字段的定义位于 sdk/typescript/src/api/client.gen.ts#L15204-L15320如filename的注释为The filename from the module source.url的注释说明其can be used to link to the source map in the browser。在 Dagger 模块的实践中sourceMap主要用于调试与排障当接口定义引发错误时可借助行/列/文件信息快速定位到模块源码中的具体声明位置工具链集成IDE 插件或代码生成器可以利用url将接口定义链接回浏览器端源码查看器模块溯源module字段标识定义来自哪个模块依赖在多模块工程中尤其有用。从 Go 运行时生成代码也能看到sourceMap作为可选参数的处理方式——只有非零值才会被追加到查询参数中见 sdk/typescript/runtime/internal/dagger/dagger.gen.go#L15216-L15239// TypeDefWithInterfaceOpts contains options for TypeDef.WithInterface type TypeDefWithInterfaceOpts struct { Description string SourceMap *SourceMap } func (r *TypeDef) WithInterface(name string, opts ...TypeDefWithInterfaceOpts) *TypeDef { q : r.query.Select(withInterface) for i : len(opts) - 1; i 0; i-- { if !querybuilder.IsZeroValue(opts[i].Description) { q q.Arg(description, opts[i].Description) } if !querybuilder.IsZeroValue(opts[i].SourceMap) { q q.Arg(sourceMap, opts[i].SourceMap) } } q q.Arg(name, name) // ... }这段代码清晰展示了 Go 版本中选项参数的逐字段零值判断逻辑同时也印证了 TypeScript 类型定义中两个属性均可选的设计——省略即不发送对应 GraphQL 参数。在 Dagger 模块中定义接口的完整用法TypeDefWithInterfaceOpts必须与TypeDef.withInterface()配合使用。在 TypeScript SDK 中该方法签名如下sdk/typescript/src/api/client.gen.ts#L15915-L15921/** * Returns a TypeDef of kind Interface with the provided name. */ withInterface (name: string, opts?: TypeDefWithInterfaceOpts): TypeDef { const ctx this._ctx.select(withInterface, { name, ...opts }) return new TypeDef(ctx) }使用方法非常直观第一个参数是接口名第二个可选参数即TypeDefWithInterfaceOpts。一个带完整选项的调用示例const myIface myTypeDef.withInterface(MyService, { description: MyService 是所有对外服务实现必须遵循的接口契约, sourceMap: dagger.sourceMap(modules/my-service/index.ts, 12, 3), })其中dagger.sourceMap(filename, line, column)用于构造一个SourceMap实例对应 SDK 中的工厂方法见 sdk/typescript/src/api/client.gen.ts#L14401-L14403。如果只需最简用法也可以完全省略选项const myIface myTypeDef.withInterface(MyService)接口与对象的分工在 Dagger 的类型模型中withInterface创建的TypeDef属于Interface类型TypeDefKind.Interface它与withObject创建的对象类型是两套不同的抽象接口Interface定义一组可被多个实现共享的方法签名与字段契约适合描述能力的约定对象Object具体的数据/能力实现可以withFunction挂载方法、withField挂载字段。两者的 GraphQL schema 并置可见于 core/schema/testdata/base_schema.graphqls#L4790-L4812其中withInterface的注释为Returns a TypeDef of kind Interface with the provided name.而withFunction明确指出Adds a function for an Object or Interface TypeDef, failing if the type is not one of those kinds.——即接口与对象都允许通过withFunction添加函数。与其他选项类型的关系TypeDefWithInterfaceOpts并不是孤立存在的。在 SDK 自动生成的代码中围绕TypeDef存在一整套成体系的选项类型sdk/typescript/src/api/client.gen.ts#L3180-L3223export type TypeDefWithFieldOpts { description?: string sourceMap?: SourceMap deprecated?: string } export type TypeDefWithInterfaceOpts { description?: string sourceMap?: SourceMap } export type TypeDefWithObjectOpts { description?: string sourceMap?: SourceMap deprecated?: string } export type TypeDefWithScalarOpts { description?: string }对比可见description与sourceMap是接口、对象、字段三类选项的公共基础deprecated只出现在字段与对象选项中——接口本身不支持弃用标记TypeDefWithScalarOpts最为精简仅保留description。这套命名规约TypeDefWithXxxOpts↔TypeDef.withXxx()贯穿整个 TypeDef API学习时可按方法名 Opts的规律快速定位任意类型定义的选项结构。源码映射小结为便于读者在仓库中继续深入将本文涉及的关键实现位置汇总如下内容仓库路径TypeScript 类型别名定义sdk/typescript/src/api/client.gen.ts#L3210-L3213TypeScriptwithInterface方法sdk/typescript/src/api/client.gen.ts#L15915-L15921TypeScriptSourceMap类sdk/typescript/src/api/client.gen.ts#L15204-L15320Go 运行时选项结构体与参数装配sdk/typescript/runtime/internal/dagger/dagger.gen.go#L15216-L15239GraphQL schema含默认值core/schema/testdata/base_schema.graphqls#L4794-L4795引擎侧服务端解析逻辑core/schema/module.go#L1083-L1113总结TypeDefWithInterfaceOpts虽是一个只有两个可选属性的轻量类型别名但它是 Dagger TypeScript SDK 中定义模块接口的统一入口参数description让接口具备自解释的文档能力sourceMap让接口定义可精确回溯到源码位置。理解它需要同时把握三条线索——TypeScript 层的类型形状、GraphQL schema 层的参数默认值以及引擎侧对接口名的非空校验。掌握了withInterface与这套Opts约定后你就能在自定义 Dagger 模块中灵活搭建接口契约并与对象、字段、函数等 TypeDef 构建方法组合出完整、可维护的类型体系。【免费下载链接】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），仅供参考