Dagger TypeScript SDK 的 InputTypeDef 类GraphQL 输入类型定义的表示与使用【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerInputTypeDef是 Dagger TypeScript SDKversion-0.21 API 参考中用于描述 GraphQL 输入类型的核心类。本文以该类的官方参考文档为主体结合仓库内 TypeScript 客户端实现、Go 核心定义与 GraphQL Schema 源码完整讲解其构造方式、三个查询方法fields()、id()、name()的语义与底层实现帮助读者理解 Dagger 中输入类型这一概念的真实定位与适用边界。什么是 InputTypeDef在 Dagger 的类型定义体系中InputTypeDef表示一个GraphQL 输入类型graphql input type本质上就是一组命名参数的集合a group of named args。它属于 Dagger 类型反射/定义体系中的一员与之并列的还有FieldTypeDef、ListTypeDef、EnumTypeDef、InterfaceTypeDef、ScalarTypeDef等定义类它们共同描述了 Dagger 模块可用的各种类型形态。官方文档对它的定位给出了非常明确的两点限定仅用于表示核心 API 中既有pre-existing的 GraphQL 输入类型用法不用于用户模块将来也不应该用于用户模块因为用户模块是通过ID接收输入对象而不是通过 GraphQL 输入类型。这一设计在核心实现中得到了印证。core/typedef.go中InputTypeDef的 Go 结构体及其类型描述core/typedef.go与 GraphQL Schema 定义core/schema/testdata/base_schema.graphqls保持完全一致 A graphql input type, which is essentially just a group of named args. This is currently only used to represent pre-existing usage of graphql input types in the core API. It is not used by user modules and shouldnt ever be as user module accept input objects via their id rather than graphql input types. type InputTypeDef implements Node { Static fields defined on this input object, if any. fields: [FieldTypeDef!]! A unique identifier for this InputTypeDef. id: ID! The name of the input object. name: String! }可以看出InputTypeDef实现了Node接口因此必然具备全局唯一id并对外暴露三个字段fields、id、name这与 TypeScript SDK 中该类暴露的三个方法一一对应。类继承关系与构造器继承自 BaseClientInputTypeDef继承自BaseClient这是 Dagger TypeScript SDK 中所有 GraphQL 对象类的公共基类。在 SDK 生成代码sdk/typescript/src/api/client.gen.ts中可以看到它保留了三个私有缓存字段export class InputTypeDef extends BaseClient { private readonly _id?: ID undefined private readonly _name?: string undefined ... }构造器签名new InputTypeDef(ctx?, _id?, _name?): InputTypeDef构造器接受三个可选参数参数类型说明ctx?Context查询上下文用于携带 GraphQL 客户端状态与选择链selection_id?ID该输入类型的唯一标识符_name?string输入对象的名称官方文档明确强调该构造器仅供内部使用用户不应直接通过它创建对象。其实际作用是SDK 在解析 GraphQL 响应后用已知的_id、_name快速构造实例并填充缓存从而避免对已缓存字段发起重复的 GraphQL 查询。如何获取 InputTypeDef 实例作为普通使用者你通常不会也不应手动new一个InputTypeDef而是通过既有对象的方法或字段获得通过TypeDef的asInput()方法将通用类型定义窄化为输入类型定义client.gen.tsasInput async (): PromiseInputTypeDef | null { const response: AwaitedInputTypeDef await ctx.execute() return new InputTypeDef(ctx.copy().selectNode(response, InputTypeDef)) }或通过loadInputTypeDefFromID(id)从 ID 恢复实例。core/ids.go中定义了 ID 类型别名InputTypeDefID dagql.ID[*InputTypeDef]core/ids.go而核心模块的__loadInputTypeDef函数则按名称在依赖的模块类型定义中查找输入类型core/schema/module.go找不到时返回input type xxx not found错误。方法详解fields()fields(): PromiseFieldTypeDef[]返回该输入对象上定义的静态字段列表每个字段以FieldTypeDef表示。文档措辞为 if any意味着输入类型可能不定义任何字段返回空数组。从 SDK 生成代码看client.gen.tsfields()会构造一个选择链先select(fields)选取字段列表再对每个字段select(id)以获取其标识符最终将响应映射为FieldTypeDef[]fields async (): PromiseFieldTypeDef[] { type fields { id: ID } const ctx this._ctx.select(fields).select(id) const response: Awaitedfields[] await ctx.execute() return response.map( (r) new FieldTypeDef(ctx.copy().selectNode(r.id, FieldTypeDef)), ) }在核心实现中InputTypeDef的 Go 结构体包含Fields dagql.ObjectResultArray[*FieldTypeDef]字段并通过AttachDependencyResults将每个字段与对应结果对象关联core/typedef.go。Schema 侧则在module.go中注册了fields解析器core/schema/module.godagql.Fields[*core.InputTypeDef]{ dagql.Func(fields, s.inputTypeDefFields). Doc(Static fields defined on this input object, if any.), dagql.Func(__withField, s.inputTypeDefWithField), }.Install(dag)注意这里同时注册了一个内部方法__withField它对应inputTypeDefWithField实现core/schema/module.go用于在构建类型定义时向输入对象追加字段——这是类型定义构造阶段的内部机制与查询阶段的fields()读取操作互不冲突。id()id(): PromiseID返回该InputTypeDef的唯一标识符类型为ID对应 GraphQL 标量InputTypeDefID。id是所有实现Node接口的 Dagger 对象共有的能力是对象持久化、引用传递与恢复的基础。SDK 实现中id()会优先返回构造时缓存的_id仅在缓存为空时才发起 GraphQL 查询client.gen.tsid async (): PromiseID { if (this._id) { return this._id } const ctx this._ctx.select(id) const response: AwaitedID await ctx.execute() return response }这一先查缓存、后发请求的模式是 SDK 的通用优化策略避免对同一对象的同一标量字段重复查询。name()name(): Promisestring返回输入对象的名称。与id()类似name()也优先返回构造器传入的_name缓存否则通过select(name)发起查询client.gen.ts。名称在 Dagger 的类型体系中扮演关键角色在core/typedef.go中InputTypeDef的Name字段带有field:true与doNotCache:simple field selection标记core/typedef.go表示这是一个简单字段选择。loadInputTypeDef正是通过遍历TypeDefKindInput类型的定义、比对Name来完成按名称查找core/schema/module.go。从 TypeDef 到 InputObjectSpecInputTypeDef 的底层转化InputTypeDef并非孤立存在它是通用TypeDef的一个具体分支。在 Go 核心中TypeDef结构体通过AsInput dagql.Nullable[dagql.ObjectResult[*InputTypeDef]]持有输入类型定义core/typedef.go并依据TypeDefKindInput进行分发在typeDef.Name()的解析中若AsInput有效则直接返回其名称core/typedef.go在类型挂载attach阶段InputTypeDef会被附加为其依赖结果core/typedef.go在生成 GraphQL 类型时通过ToInputObjectSpec()将输入类型定义转换为dagql.InputObjectSpeccore/typedef.go其每个字段携带名称、描述与类型信息供 dagql 服务端注册真正的 GraphQL input object。此外InputTypeDef还实现了EncodePersistedObject/DecodePersistedObject持久化编解码core/typedef.go配合persistedInputTypeDef载荷结构使输入类型定义能够随 Dagger 的缓存与持久化体系跨会话保存与恢复。在模块类型体系中的位置InputTypeDef属于 Dagger 模块类型定义TypeDef大家族中的输入类定义。官方文档强调用户模块通过 ID 接收输入对象而非 GraphQL 输入类型这意味着在编写用户模块时你通常接触不到该类它更多是核心 API 内部自省introspection与既有 GraphQL 输入类型兼容场景下的产物。如果你想在真实项目中观察它的存在形态可以从以下仓库位置入手TypeScript 客户端生成代码sdk/typescript/src/api/client.gen.ts即本文讲解的类实现本体Go 核心定义core/typedef.go包含结构体、持久化、克隆、依赖挂载与ToInputObjectSpec转化逻辑Schema 注册与加载core/schema/module.gofields解析器与__loadInputTypeDef按名查找逻辑GraphQL Schema 定义core/schema/testdata/base_schema.graphqlsInputTypeDef类型与InputTypeDefID标量的权威声明各语言 SDK 生成示例例如 core/integration/testdata/modules/go/defaults/foobar/internal/dagger/dagger.gen.go 中 Go SDK 的对应生成实现展示了fields()、ID()、Name()等方法的跨语言等价形态。总结InputTypeDef是 Dagger TypeScript SDK 中描述 GraphQL 输入类型的只读视图类成员签名语义构造器new InputTypeDef(ctx?, _id?, _name?)内部使用支持传入上下文与缓存字段fields()PromiseFieldTypeDef[]输入对象上定义的静态字段列表id()PromiseID全局唯一标识符InputTypeDefID标量name()Promisestring输入对象的名称理解该类时最重要的是把握它的边界它是一组命名参数的集合仅为兼容核心 API 中既有的 GraphQL 输入类型而存在在用户模块开发中输入对象一律以 ID 形式传递因此正常情况下你无需直接构造或使用InputTypeDef。结合源码阅读TS 生成代码的缓存优化、Go 核心的类型转化与持久化、Schema 层的解析器注册可以完整还原 Dagger 类型反射体系从 GraphQL Schema 到各语言 SDK 的生成与执行链路。【免费下载链接】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），仅供参考