DevOpsCI/CD后端CLI云原生【免费下载链接】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 v0.20 TypeScript API 参考文档 中的float类型别名展开深入讲解它在 Dagger 模块开发中的定位、与原生number类型的区别以及从类型内省introspector到运行时执行的全链路实现原理。读完本文你将掌握如何在 Dagger TypeScript 模块中正确声明浮点类型的函数参数与返回值并理解为什么 Dagger 需要这样一个看似多此一举的类型别名。Dagger 是一个自动化引擎用于在任何代码库上构建、测试和发布可运行在本地、CI 或云端。在使用 Dagger TypeScript SDK 编写模块时float是 api/client.gen.ts 中自动生成的核心类型别名之一它定义了模块函数中浮点数值的统一表达方式。本文结合仓库源码与测试用例从定义、动机、实现原理到实战用法逐层拆解。float类型别名的官方定义在 v0.20 的 TypeScript API 参考中float 类型别名 的定义极其简洁type float number其语义注释为Declare a number as float in the Dagger API.即在 Dagger API 中将number声明为浮点数float。对应到生成代码 sdk/typescript/src/api/client.gen.ts完整实现为/** * This file was auto-generated by client-gen. * Do not make direct changes to the file. */ import { Context, BaseClient } from ../common/context.js /** * Declare a number as float in the Dagger API. */ export type float number两点需要特别注意该文件头部明确标注This file was auto-generated byclient-gen意味着float别名由 Dagger 的代码生成器client-gen统一产出用户不应直接修改类型层面float与number完全等价——它只是一个类型别名type alias不会在 TypeScript 编译期产生任何新的类型行为。它的意义完全体现在 Dagger 的模块内省与运行时系统中这一点下文会详细展开。为什么需要float别名number在 Dagger 中默认是整数float别名的存在根源于 Dagger 类型系统的一个关键约定在 Dagger API 中裸number类型默认被映射为整数Integer而小数数值必须显式声明为float。这一约定在模块内省器introspector的源码中有直接体现。查看 sdk/typescript/src/module/introspector/typescript_module/ast.ts 中的类型转换逻辑if (type.flags ts.TypeFlags.Number) { // Float will be interpreted as number by the TypeScript compiler so we need to check if the // text is float to know if its a float or an integer. // It can also be interpreted as a reference, but this is handled separately at an upper level. if (node.getText().includes(float)) { return { kind: TypeDefKind.FloatKind } } return { kind: TypeDefKind.IntegerKind } }这段代码揭示了两个核心事实TypeScript 编译器会把float当作普通number处理——因为它本质上就是number的别名type.flags ts.TypeFlags.Number为真内省器必须通过检查源码文本是否包含float字样来判断该number究竟应映射为 Dagger 的FloatKind浮点还是IntegerKind整数。这就是为什么必须有一个名为float的别名它是 Dagger 内省器识别浮点意图的唯一文本标记。因此若你在模块函数中写func() ratio(a: number, b: number): number { return a / b // 即使返回小数Dagger 也会将其视为 Integer }Dagger 会把a、b与返回值全部按Integer类型注册。只有当类型标注为float时才会以浮点类型出现在 API 中func() ratio(a: float, b: float): float { return a / b }float的自动注册机制在模块内省阶段float别名会被自动注册为浮点类型引用无需用户额外配置。查看 sdk/typescript/src/module/introspector/dagger_module/module.tsprivate references: References { // Float is a special case, its an alias of number but it serves to declare a float type // in the Dagger API. // So we auto register it because it will be detected as a referenced type by the introspector. float: { kind: TypeDefKind.FloatKind }, }源码注释明确解释了设计意图Float 是特例虽然是number的别名但用于在 Dagger API 中声明浮点类型因此被自动注册否则内省器会将其误判为普通引用类型。float由此进入 reference.ts 定义的TypeDefTypeDefKind.FloatKind合法引用集合成为模块类型定义体系中的一等公民。实战用法参数、返回值与变参列表作为函数参数与返回值仓库中的内省测试用例 multiArgs/index.ts 演示了float与number的混合使用import type { float } from ../../../../../api/client.gen.js import { func, object } from ../../../../decorators.js object() export class MultiArgs { func() compute(a: number, b: number, c: float): float { return a * b c } }这里a、b被注册为 Integerc与返回值被注册为 Float——二者在同一个函数签名中可以共存。内省器通过node.getText().includes(float)逐参数判断因此不会因为函数中同时出现number与float而混淆。作为变参variadic列表的元素类型list/index.ts 展示了float在变参与数组返回场景中的用法import type { float } from ../../../../../api/client.gen.js import { func, object } from ../../../../decorators.js object() export class List { func() create(...n: number[]): Integer[] { return n.map((v) new Integer(v)) } func() floats(...n: float[]): float[] { return n } }对应的内省期望输出 expected.json 中floats参数与返回值的type均为{ kind: LIST_KIND, typeDef: { kind: FLOAT_KIND } }也就是说float[]会被内省为元素类型为FLOAT_KIND的LIST_KIND与整数数组INTEGER_KIND元素在 Dagger 类型层面清晰区分。参数默认值在解析参数默认值时float也被明确纳入number分支。查看 ast.ts 的resolveParameterDefaultValueTypeReferenceconst type typeof value switch (type) { case string: case number: // float is also included here case bigint: case boolean: case object: // Value will be jsonified on registration. return value default: return undefined }注释 float is also included here 表明float类型的默认值如3.14会与普通number一样被保留并在注册时 JSON 序列化不需要特殊处理。运行时保护整数与浮点的返回值校验float别名不仅影响类型注册还在模块函数运行时调用环节承担着返回值校验职责。查看 sdk/typescript/src/module/entrypoint/invoke.tsfunction isFloat(num: number): boolean { return num % 1 ! 0 }以及 invoke.ts 中的守卫逻辑// Guard to catch if a user returned a float number but the functions return // type is set to number (integer). if ( method.returnType!.kind TypeDefKind.IntegerKind isFloat(result) ) { throw new Error( cannot return float ${result} if return type is number (integer), please use float as return type instead, ) }该机制的实战价值非常明确假设你的函数签名声明为number即 Integer返回值但运行时实际返回了3.5这类小数Dagger 会在调用入口直接抛出错误错误信息会明确提示开发者改用float作为返回类型。这是一道防止类型声明与实际返回值不一致的运行时防线避免了小数被静默截断为整数导致的隐蔽 bug。反过来若返回值在运行时是整数num % 1 0则无论声明为float还是number都能正常通过——isFloat只拦截声明为整数却返回小数的情况。float在 Dagger API 中的底层表示SDK 侧标量映射在模块内省结果输出阶段FloatKind会映射为 Dagger GraphQL API 的Float标量。查看 sdk/typescript/src/module/introspector/introspection_json.tscase TypeDefKind.IntegerKind: return nonNull(scalarRef(Scalar.Int)) case TypeDefKind.BooleanKind: return nonNull(scalarRef(Scalar.Boolean)) case TypeDefKind.FloatKind: return nonNull(scalarRef(Scalar.Float))此外register.ts 的isPrimitiveType将FloatKind与 Boolean、Integer、String、Enum 一并归为原始类型primitive而 load.ts 在处理返回值时将FloatKind与 String、Integer、Boolean 等并列直接原样返回数值return value不做对象化包装。引擎侧原始类型建模在 Dagger 引擎core侧浮点类型同样作为原始类型处理。查看 core/schema/coremod.goswitch typeDef.Kind { case core.TypeDefKindString, core.TypeDefKindInteger, core.TypeDefKindFloat, core.TypeDefKindBoolean, core.TypeDefKindVoid: modType core.PrimitiveType{Def: typeDef}TypeDefKindFloat与字符串、整数、布尔、Void 一样被建模为PrimitiveType说明从 TypeScript 模块到 Dagger 引擎浮点数值始终走原始值直传路径不涉及对象化或引用计数。这也解释了为什么float类型的参数和返回值在模块间传递时开销极低、语义直观。小结Dagger TypeScript SDK 的float类型别名官方参考虽在类型层面只是number的别名但在 Dagger 生态中承载着三重职责层面职责关键源码位置类型定义提供统一的浮点声明入口由 client-gen 自动生成client.gen.ts类型内省作为区分 Float 与 Integer 的文本标记自动注册为FloatKindast.ts、module.ts运行时校验拦截声明为整数却返回小数的错误引导开发者改用floatinvoke.ts、invoke.ts实战要点回顾在 Dagger TypeScript 模块中需要浮点语义的参数、返回值、变参元素一律显式标注float裸number会被映射为整数float可自由与number、boolean、对象等类型在同一个函数签名中混用内省器按参数逐个判定若声明为number却返回小数模块调用会直接报错并提示改用float——这不是限制而是防止精度丢失的保护机制。掌握float别名的正确用法是编写类型精确、行为可预期的 Dagger TypeScript 模块的基础能力之一。赞分享DevOpsCI/CD后端CLI云原生【免费下载链接】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 中 DirectoryID 类型别名从声明到引擎实现的全解析Dagger TypeScript SDK 中 DirectoryID 类型别名从声明到引擎实现的全解析 导读 DirectoryID 是 Dagger 0.DevOpsCI/CD后端CLI云原生Dagger TypeScript SDK 中 FunctionCallArgValueID 类型别名函数调用参数值标识符的完整解析Dagger TypeScript SDK 中 FunctionCallArgValueID 类型别名函数调用参数值标识符的完整解析 本指南围绕 DaggerDevOpsCI/CD后端CLI云原生Dagger TypeScript SDK 中 TypeDefWithEnumValueOpts 类型别名解析枚举值 TypeDef 的可选参数Dagger TypeScript SDK 中 TypeDefWithEnumValueOpts 类型别名解析枚举值 TypeDef 的可选参数 本文为 DaDevOpsCI/CD后端CLI云原生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考